@nodefony/http 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/types/nodefony/src/context/transport.d.ts

@@ -0,0 +1,53 @@
+import type { AlpnProtocol, ProtocolName, ServerType } from "../../interfaces/IContext.js";
+/**
+ * Famille du protocole traité par un contexte, déduite du serveur qui l'a
+ * reçu. Règle UNIQUE : `Context` la pose à la construction.
+ *
+ * @param serverType - identité du serveur (`http`, `https`, `ws`, `wss`)
+ * @returns `"websocket"` pour `ws`/`wss`, `"http"` sinon
+ */
+export declare function protocolNameOf(serverType: ServerType): ProtocolName;
+/**
+ * Ce que la détection lit d'une requête Node, et rien d'autre : `http.IncomingMessage`
+ * (HTTP/1.1) et `http2.Http2ServerRequest` (h2, h2c) le satisfont par leur forme, sans
+ * transtypage — et une doublure de test s'écrit en littéral.
+ */
+export interface IAlpnSource {
+    readonly httpVersionMajor: number;
+    readonly stream?: {
+        readonly session?: {
+            readonly alpnProtocol?: string | undefined;
+        } | undefined;
+    } | undefined;
+}
+/**
+ * Protocole du saut qui a porté cette requête jusqu'au processus, au sens du
+ * registre IANA des identifiants ALPN. Règle UNIQUE : `HttpContext` la lit pour
+ * choisir ses classes de requête et de réponse.
+ *
+ * La valeur se CONSTATE sur la requête, elle ne se déduit pas du serveur : un
+ * même serveur TLS reçoit HTTP/1.1 et h2 (`allowHTTP1`). Pour h2, c'est la
+ * session de Node qui tranche — `Http2Session.alpnProtocol` vaut `"h2c"` sur
+ * une session en clair, l'ALPN négocié (`"h2"`) sur une session TLS.
+ *
+ * @param request - la requête Node reçue par le serveur
+ * @returns `"http/1.1"`, `"h2"` ou `"h2c"`
+ */
+export declare function alpnProtocolOf(request: IAlpnSource): AlpnProtocol;
+/**
+ * Autorité (hôte et port) d'une requête, HTTP/1.1 comme HTTP/2. Règle UNIQUE
+ * des lecteurs du serveur.
+ *
+ * `:authority` d'abord, puis `Host` (RFC 9113 §8.3.1). Le repli n'est pas un
+ * confort : un intermédiaire qui convertit une requête HTTP/1.1 de forme origine
+ * (`GET /chemin`) en HTTP/2 ne DOIT PAS fabriquer `:authority` — il garde
+ * `Host`. C'est ce que fait HAProxy `proto h2` vers un port h2c : sans ce repli,
+ * l'hôte est introuvable et la requête part en 421.
+ *
+ * @param headers - en-têtes de la requête Node (`IncomingMessage` ou `Http2ServerRequest`).
+ * @returns l'autorité, ou `undefined` si la requête n'en porte aucune.
+ */
+export declare function requestAuthority(headers: {
+    host?: string | undefined;
+    ":authority"?: string | undefined;
+}): string | undefined;

package/dist/types/nodefony/src/context/websocket/Response.d.ts

@@ -1,3 +1,4 @@
+import type { OutgoingHttpHeaders } from "node:http";
 import Cookie from "../../cookies/cookie.js";
 import { Message, Msgid, Pci, Severity } from "nodefony";
 import WebsocketContext from "./WebsocketContext.js";
@@ -44,8 +45,23 @@ declare class WebsocketResponse {
     };
     clean(): void;
     setEncoding(encoding: BufferEncoding): BufferEncoding;
-    setHeader(): boolean;
-    setHeaders(): boolean;
+    /**
+     * En-têtes de la réponse au handshake, retenus tant que la socket n'est pas
+     * acceptée : ils ne partent que dans un REFUS (`refuseHandshake`) — le `101`
+     * de `ws` ne les porte pas. `null` tant que personne n'en pose (le cas
+     * nominal : aucune allocation).
+     */
+    handshakeHeaders: Record<string, string | number> | null;
+    /**
+     * Retient un en-tête du handshake (cf {@link handshakeHeaders}) ; sans effet
+     * une fois la socket ouverte, où il n'y a plus de réponse HTTP.
+     *
+     * @param name - nom de l'en-tête
+     * @param value - valeur
+     * @returns toujours `true`
+     */
+    setHeader(name: string, value: number | string | readonly string[]): boolean;
+    setHeaders(obj: OutgoingHttpHeaders): boolean;
     addCookie(cookie: Cookie): void;
     setCookies(): void;
     setCookie(_cookie: Cookie): void;

package/dist/types/nodefony/src/context/websocket/WebsocketContext.d.ts

@@ -4,21 +4,21 @@ import { Severity, Msgid, Message, nodefonyError, Scope } from "nodefony";
 import Ws from "ws";
 import type { IncomingMessage } from "node:http";
 import WebsocketResponse from "./Response.js";
+import type { IUpgradeAdmission } from "../../servers/upgradeDispatch.js";
 import { URL } from "node:url";
 import { HTTPMethod } from "../Context.js";
 import HttpError from "../../errors/httpError.js";
 import { FrameProfile } from "../../profiler/FrameProfile.js";
-import type { PhaseName } from "../../../interfaces/IContext.js";
+import type { PhaseName, IWebsocketContext } from "../../../interfaces/IContext.js";
 import { ProxyType } from "../http/HttpContext.js";
 import { type ResolvedProxy } from "../forwarded.js";
 export interface IWsRequestExtension {
     url: URL;
     query: Record<string, string>;
-    queryGet: Record<string, string>;
     path: string;
 }
 export type WsIncomingMessage = IncomingMessage & IWsRequestExtension;
-import type { IWebsocketContext as IWebsocketContextInterface } from "../../../interfaces/IContext.js";
+import type { IWebsocketContext as IWebsocketContextInterface, IWebsocketConnectionState } from "../../../interfaces/IContext.js";
 /**
  * Coerce un code (applicatif / HTTP / WS) en code de fermeture WebSocket VALIDE
  * et conforme RFC 6455 §7.4, en PRÉFÉRANT les codes standard §7.4.1 quand le
@@ -36,7 +36,36 @@ import type { IWebsocketContext as IWebsocketContextInterface } from "../../../i
  * @returns un code de fermeture WS valide.
  */
 export declare function toWsCloseCode(code: number | undefined | null): number;
-export default class WebsocketContext extends Context implements IWebsocketContextInterface {
+/**
+ * Statut HTTP d'un handshake REFUSÉ avant le `101` (RFC 6455 §4.2.2) — la
+ * réciproque de {@link toWsCloseCode} : une erreur levée pendant la décision
+ * porte un code HTTP (pare-feu, garde) ou, par héritage, un code de fermeture
+ * WS (origine `1008`, protocole `1002`, introuvable `4004`) ; le client qui
+ * lit le statut doit y reconnaître le même sens.
+ *
+ * @param code - code porté par l'erreur
+ * @returns un statut HTTP 4xx/5xx
+ */
+export declare function toHandshakeStatus(code: number | undefined | null): number;
+/**
+ * Statut HTTP que reçoit le client d'un handshake refusé — ou `null` si la
+ * connexion était déjà acceptée.
+ *
+ * La ligne de journal d'un refus s'écrit AVANT `refuseHandshake` : sans ce
+ * calcul, elle affichait le code de fermeture par défaut (`1000`) en ERROR,
+ * pour un `400` que le client reçoit. Même conversion que le refus
+ * ({@link toHandshakeStatus}), donc même chiffre. Chemin d'ERREUR seulement :
+ * 1 comparaison et 1 `typeof`, aucune allocation.
+ *
+ * @param context - le contexte WS de la ligne
+ * @param error - l'erreur qui a interrompu le handshake
+ * @returns le statut HTTP du refus, ou `null` après l'acceptation
+ */
+export declare function handshakeRefusalStatus(context: IWebsocketContext, error: Error): number | null;
+interface WebsocketContext extends IWebsocketConnectionState {
+}
+export { WebsocketContext as default };
+declare class WebsocketContext extends Context implements IWebsocketContextInterface {
     #private;
     request: WsIncomingMessage | null;
     response: WebsocketResponse | null;
@@ -45,16 +74,37 @@ export default class WebsocketContext extends Context implements IWebsocketConte
     rejected: boolean;
     teardownWired: boolean;
     connection: Ws | null;
+    /**
+     * Le verdict du handshake encore à rendre : posé par le noyau tant que le
+     * pipeline décide (pare-feu, garde de l'action), `null` dès que la socket
+     * est acceptée ou refusée. Tant qu'il est là, AUCUN `101` n'est parti.
+     */
+    admission: IUpgradeAdmission | null;
     origin: string;
     proxy: ProxyType | null;
     forwarded: ResolvedProxy | null;
     wsUrl: URL | null;
-    queryGet: Record<string, string>;
-    queryRequest: Record<string, string>;
+    query: Record<string, string>;
     wsPath: string;
-    constructor(scope: Scope, req: IncomingMessage, ws: Ws, type: ServerType);
+    constructor(scope: Scope, req: IncomingMessage, ws: Ws | null, serverType: ServerType);
     log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
     logRequest(httpError?: Error | HttpError | nodefonyError | null, acceptedProtocol?: string | null): import("nodefony").Pdu | undefined;
+    /**
+     * Rattache la socket que le handshake vient d'ouvrir (`101` envoyé) : le
+     * contexte a été construit et jugé AVANT, sans elle.
+     *
+     * @param ws - la socket acceptée
+     */
+    acceptConnection(ws: Ws): void;
+    /**
+     * Refuse le handshake par un statut HTTP, avant tout `101` (RFC 6455
+     * §4.2.2) — avec les en-têtes posés pendant la décision (`WWW-Authenticate`
+     * du pare-feu, `Retry-After`).
+     *
+     * @param status - statut HTTP du refus
+     * @returns `false` si le verdict était déjà rendu (rien n'est écrit)
+     */
+    refuseHandshake(status: number): boolean;
     connect(): Promise<Ws>;
     handle(data?: unknown[]): Promise<this>;
     render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>;

package/dist/types/nodefony/src/context/websocket/isWebsocketContext.d.ts

@@ -0,0 +1,15 @@
+import type { ContextType } from "../../../service/http-kernel.js";
+import type WebsocketContext from "./WebsocketContext.js";
+/**
+ * Dit si un contexte sert une connexion WebSocket — la garde qui rétrécit
+ * `ContextType` à `WebsocketContext` sans conversion.
+ *
+ * Elle lit la famille (`type`) posée à la construction du contexte, jamais
+ * `instanceof` : deux copies installées de `@nodefony/http` font échouer
+ * `instanceof` en silence, quand ce champ dit vrai pour les deux. Deux
+ * Une comparaison de chaînes, aucune allocation.
+ *
+ * @param context - le contexte à éprouver.
+ * @returns `true` si le contexte traite une connexion WebSocket (`ws` ou `wss`).
+ */
+export declare function isWebsocketContext(context: ContextType): context is WebsocketContext;

package/dist/types/nodefony/src/context/websocket/websocketUrl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * URL d'une requête d'upgrade WebSocket, telle que le pipeline la lit.
+ *
+ * Seule construction : le contexte WebSocket en tire son chemin et sa requête,
+ * et le contrôle d'avant `101` en tire le chemin qu'il confronte aux routes.
+ * Deux constructions divergeraient — `//a/b` lu comme un chemin d'un côté, comme
+ * un hôte de l'autre — et une route acceptée par l'une serait refusée par
+ * l'autre.
+ *
+ * @param scheme - `ws` ou `wss`
+ * @param host - en-tête `Host` de la requête (`localhost` s'il manque)
+ * @param rawUrl - cible brute de la requête (`/` si elle manque)
+ * @returns l'URL analysée
+ * @throws TypeError si l'hôte ou la cible ne forment pas une URL
+ */
+export declare function parseWebsocketUrl(scheme: string, host: string | undefined, rawUrl: string | undefined): URL;

package/dist/types/nodefony/src/profiler/FrameProfile.d.ts

@@ -1,5 +1,6 @@
 import type { IProfilerQuery } from "nodefony";
-import type { ISecurityTrace, PhaseName, PhaseTiming } from "../../interfaces/IContext.js";
+import type { ISecurityTrace, PhaseName, PhaseTiming, ProtocolName } from "../../interfaces/IContext.js";
+import type { IResolvedRoute, IRouteResolver } from "../../interfaces/IRouting.js";
 /**
  * Zone firewall capturée sur le contexte (`SecuredArea`, lue en structurel :
  * `@nodefony/http` ne peut pas importer `@nodefony/security`).
@@ -10,22 +11,22 @@ export interface ProfiledArea {
     mode?: string;
     authenticators?: readonly string[];
 }
-/** Ce que le Profiler lit d'un Resolver (route/controller/action). */
+/**
+ * Ce que le Profiler lit d'un Resolver (route/controller/action) — dérivé de
+ * {@link IRouteResolver}, en lecture seule : tout résolveur du contrat s'y range
+ * sans conversion, et les deux types ne peuvent plus diverger.
+ */
 export interface ProfiledResolver {
-    route?: {
-        name?: string;
-    } | null;
-    controller?: {
-        name?: string;
-    } | null;
-    actionName?: string;
+    readonly route?: Pick<IResolvedRoute, "name"> | null | undefined;
+    readonly controller?: IRouteResolver["controller"];
+    readonly actionName?: string | undefined;
 }
 /** Descripteur d'ouverture d'une invocation (ce que le pont connaît d'entrée). */
 export interface FrameProfileInit {
     /** Identifiant du profil — `<requestId de la connexion>.<n° de frame>`. */
     requestId: string;
-    /** Type de transport du contexte porteur (`websocket` / `websocket-secure`). */
-    type: string;
+    /** Famille du contexte porteur (`context.type` : `websocket`). */
+    type: ProtocolName;
     scheme: string;
     /** Méthode LOGIQUE de l'invocation (`GET`, `POST`…), pas le transport. */
     method: string;
@@ -63,7 +64,7 @@ export interface FrameProfileInit {
  */
 export declare class FrameProfile {
     readonly requestId: string;
-    readonly type: string;
+    readonly type: ProtocolName;
     readonly scheme: string;
     readonly method: string;
     readonly url: string;

package/dist/types/nodefony/src/profiler/Profiler.d.ts

@@ -18,6 +18,8 @@
  * Multi-process : un profil vit sur le worker qui a traité l'appel (fetch même
  * origine par requestId). Agrégat cluster = Redis (P13).
  */
+import type { ProfiledResolver } from "./FrameProfile.js";
+import type { ProtocolName } from "../../interfaces/IContext.js";
 /** Une phase du pipeline, projetée pour le transport (durée résolue). */
 export interface ProfilePhase {
     name: string;
@@ -77,6 +79,11 @@ export interface ProfileSecurity {
 /** Profil complet d'une requête (HTTP ou message WS), exposé par `get`. */
 export interface ProfileEntry {
     requestId: string;
+    /**
+     * Numéro d'ordre de collecte, croissant sur la vie du profileur. Un profil
+     * réinséré (identifiant réutilisé) reçoit un numéro neuf.
+     */
+    seq: number;
     /** Horodatage de la collecte (`Date.now()`), pour le tri client. */
     ts: number;
     kind: "http" | "ws";
@@ -116,7 +123,8 @@ export interface ProfileSummary {
 /** Forme structurelle minimale lue sur un `Context` (lecture défensive). */
 interface ProfilableContext {
     requestId?: string | undefined;
-    type?: string | undefined;
+    userIdentifier?: string | null | undefined;
+    type?: ProtocolName | undefined;
     scheme?: string | undefined;
     method?: string | null | undefined;
     url?: string | undefined;
@@ -133,15 +141,7 @@ interface ProfilableContext {
         startMs: number;
         durationMs?: number | undefined;
     }> | undefined;
-    resolver?: {
-        route?: {
-            name?: string | undefined;
-        } | null;
-        controller?: {
-            name?: string | undefined;
-        } | null | undefined;
-        actionName?: string | undefined;
-    } | null | undefined;
+    resolver?: ProfiledResolver | null | undefined;
     /**
      * Buffer de requêtes ORM rempli pendant la requête (dev-only). Même tableau
      * que la payload ALS — les adapters ORM y poussent via `RequestContext`.
@@ -167,10 +167,50 @@ interface ProfilableContext {
         roles: string[] | null;
     } | null | undefined;
 }
-export declare class Profiler {
-    private readonly _buf;
-    private readonly _cap;
-    constructor(cap?: number);
+/** Les profils collectés depuis un curseur. */
+export interface IProfileBatch {
+    /** Profils de numéro supérieur au curseur, du plus ancien au plus récent. */
+    entries: ProfileEntry[];
+    /** Curseur à repasser au prochain appel : le dernier numéro attribué. */
+    cursor: number;
+    /**
+     * Profils collectés depuis le curseur mais disparus avant d'être lus —
+     * évincés par le tampon, ou écrasés par un identifiant réutilisé. Exact.
+     */
+    lost: number;
+}
+/**
+ * Ce qu'un lecteur extérieur (outil de l'agent de code, banc) attend du
+ * profileur : suivre les profils au fil de l'eau, ou en retrouver un par son
+ * identifiant. Contrat structurel — on le résout par NOM dans le conteneur
+ * (`"profiler"`), sans dépendre de la classe.
+ */
+export interface IProfilerReader {
+    /** Curseur courant : le passer à {@link since} pour ne lire que la suite. */
+    readonly cursor: number;
+    /** Profils collectés depuis `cursor`, et le compte de ceux qui ont été perdus. */
+    since(cursor: number): IProfileBatch;
+    /** Profil complet d'une requête, ou `undefined` si évincé/inconnu. */
+    get(requestId: string): ProfileEntry | undefined;
+}
+/**
+ * Collecteur des profils de requête, en un anneau par provenance
+ * ({@link profileLane}) : l'application, l'outillage, les assets relayés.
+ * Chacun évince ses propres profils — ouvrir la console ne chasse plus celui
+ * qu'on y consulte.
+ */
+export declare class Profiler implements IProfilerReader {
+    #private;
+    private readonly _lanes;
+    private readonly _caps;
+    /** Dernier numéro d'ordre attribué (0 = aucun profil collecté). */
+    private _seq;
+    /**
+     * @param cap - capacité de l'anneau de l'application.
+     * @param sideCap - capacité de chacun des anneaux de l'outillage et des
+     *          assets relayés.
+     */
+    constructor(cap?: number, sideCap?: number);
     /**
      * Snapshot un `Context` en fin de requête. Tolérant aux champs absents
      * (handshake WS, erreur précoce). À appeler AVANT `context.clean()`.
@@ -184,9 +224,23 @@ export declare class Profiler {
      * Résumés des requêtes les plus récentes (récent → ancien), capés à `limit`.
      */
     recent(limit?: number): ProfileSummary[];
+    /** Dernier numéro d'ordre attribué : le point de départ d'une lecture suivie. */
+    get cursor(): number;
+    /**
+     * Profils collectés après `cursor`, tous anneaux confondus, dans l'ordre
+     * des numéros.
+     *
+     * Les pertes se comptent sans estimation : chaque numéro attribué est un
+     * profil collecté, donc ce qui manque entre le curseur et le dernier numéro
+     * a disparu avant d'être lu. Un curseur venu d'ailleurs (supérieur au
+     * dernier numéro) repart de zéro.
+     *
+     * @param cursor - le `cursor` rendu par l'appel précédent, ou {@link cursor}.
+     */
+    since(cursor: number): IProfileBatch;
     /** Nombre de profils en mémoire. */
     get size(): number;
-    /** Vide le ring buffer. */
+    /** Vide les anneaux. */
     clear(): void;
 }
 export default Profiler;

package/dist/types/nodefony/src/profiler/aggregate.d.ts

@@ -0,0 +1,215 @@
+import type { ProfileEntry } from "./Profiler.js";
+/**
+ * Agrégation des profils de requêtes — règle PURE, sans horloge ni I/O.
+ *
+ * Une seule implémentation pour tout ce qui résume le profileur : l'outil MCP
+ * qui observe l'application (`nodefony_observe`), celui qui tire lui-même des
+ * requêtes sur une route, et demain la console d'administration. Elle est
+ * bornée par construction : un échantillon de durées par route, un nombre
+ * maximal de formes SQL retenues, quelques exemples d'erreurs — observer une
+ * application chargée ne fait jamais grossir la mémoire avec la fenêtre.
+ */
+/**
+ * Répétitions d'une même forme SQL, dans UNE requête, à partir desquelles on
+ * signale un N+1. En dessous, ce sont des boucles courtes légitimes (quelques
+ * lectures de configuration, une pagination) qu'on signalerait à tort.
+ */
+export declare const N_PLUS_ONE_MIN_REPEATS = 5;
+/** Durées retenues par route pour les percentiles (échantillonnage au-delà). */
+export declare const ROUTE_SAMPLE_CAP = 256;
+/** Formes SQL distinctes retenues ; les suivantes ne sont plus que comptées. */
+export declare const SQL_SHAPE_CAP = 200;
+/** Exemples d'erreurs retenus (statut ≥ 500 ou exception). */
+export declare const ERROR_SAMPLE_CAP = 10;
+/** Préfixe des routes de l'outillage (console, API d'administration, porte MCP). */
+export declare const TOOLING_URL_PREFIX = "/nodefony/";
+/**
+ * Provenance d'un profil : l'application, l'outillage (`/nodefony/…` :
+ * console, API d'administration, porte MCP), ou un asset relayé sous un
+ * préfixe de module (`/_vite/`).
+ */
+export type ProfileLane = "app" | "tooling" | "asset";
+/**
+ * Range un profil par provenance, d'après son URL. Seule règle du partage —
+ * les anneaux du profileur et le filtre de l'agrégation la lisent tous deux.
+ *
+ * @param url - URL du profil, absolue ou chemin.
+ * @returns la provenance du profil.
+ */
+export declare function profileLane(url: string): ProfileLane;
+/**
+ * Le profil vient-il de l'outillage (routes `/nodefony/…` ou assets relayés)
+ * plutôt que de l'application.
+ *
+ * @param url - URL du profil, absolue ou chemin.
+ */
+export declare function isToolingUrl(url: string): boolean;
+/** Groupe des requêtes qu'aucune route n'a servies (404, statique, sondes). */
+export declare const NO_ROUTE = "(aucune route)";
+/** Pseudo-phase : le temps de l'action hors phases imbriquées et hors SQL. */
+export declare const ACTION_SELF_PHASE = "action.self";
+/** Répartition des statuts HTTP d'une route. */
+export interface IStatusBreakdown {
+    s2xx: number;
+    s3xx: number;
+    s4xx: number;
+    s5xx: number;
+    /** Dont 401 : la route exige une authentification que la requête n'avait pas. */
+    unauthorized: number;
+    /** Dont 403 : authentifiée, mais refusée. */
+    forbidden: number;
+}
+/** Temps cumulé d'une phase sur les requêtes d'une route. */
+export interface IPhaseTotal {
+    totalMs: number;
+    /** Requêtes où la phase est apparue et s'est terminée. */
+    count: number;
+}
+/** Statistiques d'une route sur la fenêtre agrégée. */
+export interface IRouteStats {
+    route: string;
+    kind: "http" | "ws";
+    controller: string | null;
+    action: string | null;
+    count: number;
+    /** Requêtes sans durée mesurée (mesure des phases désactivée, erreur précoce). */
+    untimed: number;
+    /**
+     * Requêtes SERVIES et chronométrées (statut < 400, sans exception) : la
+     * population de tout ce qui se dit « par requête » ci-dessous. Refus et
+     * erreurs se lisent dans `status` et `errors`.
+     */
+    served: number;
+    /** Percentiles et maximum, sur les requêtes servies. */
+    p50Ms: number | null;
+    p95Ms: number | null;
+    maxMs: number | null;
+    status: IStatusBreakdown;
+    /** Requêtes en erreur : statut ≥ 500 ou exception levée. */
+    errors: number;
+    /**
+     * Requêtes SQL/NoSQL des requêtes servies : total, maximum dans une
+     * requête, temps CUMULÉ (des requêtes parallèles s'y additionnent).
+     */
+    queries: {
+        total: number;
+        perRequestMax: number;
+        totalMs: number;
+    };
+    /** Temps par phase des requêtes servies, `action.self` compris. */
+    phases: Record<string, IPhaseTotal>;
+}
+/** Un N+1 : la même forme SQL répétée dans une requête. */
+export interface INPlusOne {
+    route: string;
+    controller: string | null;
+    action: string | null;
+    shape: string;
+    /** Plus grand nombre de répétitions vu dans une requête. */
+    maxRepeats: number;
+    /** Requêtes touchées. */
+    requests: number;
+    /** Temps cumulé de ces répétitions. */
+    totalMs: number;
+    /** Une requête touchée, pour aller voir son profil complet. */
+    sampleRequestId: string;
+}
+/** Une forme SQL et son coût sur la fenêtre. */
+export interface ISqlShapeStats {
+    shape: string;
+    connector: string | null;
+    count: number;
+    totalMs: number;
+    maxMs: number;
+    /** Routes qui l'ont émise (au plus cinq). */
+    routes: string[];
+}
+/** Un exemple d'erreur, de quoi la retrouver dans le journal. */
+export interface IErrorSample {
+    route: string;
+    status: number | null;
+    error: string | null;
+    requestId: string;
+}
+/** Le rapport agrégé. */
+export interface IProfileReport {
+    /** Requêtes agrégées (hors outillage filtré). */
+    requests: number;
+    http: number;
+    ws: number;
+    /** Requêtes de l'outillage écartées (`/nodefony/…`, `/_vite/…`). */
+    filteredTooling: number;
+    /** Requêtes sans durée mesurée. */
+    untimed: number;
+    /** Triées par p95 décroissant. */
+    routes: IRouteStats[];
+    /** Triés par temps cumulé décroissant. */
+    nPlusOne: INPlusOne[];
+    /** Les dix formes SQL les plus coûteuses (temps cumulé décroissant). */
+    slowQueries: ISqlShapeStats[];
+    /** Formes SQL distinctes vues au-delà de la capacité, comptées sans détail. */
+    sqlShapesDropped: number;
+    errors: IErrorSample[];
+}
+/** Réglages d'une agrégation. */
+export interface IProfileAggregatorOptions {
+    /** Répétitions à partir desquelles une forme SQL est un N+1. */
+    nPlusOneMinRepeats?: number | undefined;
+    /** Agréger aussi les requêtes de l'outillage (`/nodefony/…`, `/_vite/…`). */
+    includeTooling?: boolean | undefined;
+    /** Source d'aléa de l'échantillonnage — injectée par les tests. */
+    random?: (() => number) | undefined;
+}
+/** Accumulateur : on lui donne les profils un à un, il rend le rapport. */
+export interface IProfileAggregator {
+    /** Ajoute un profil ; `false` s'il a été écarté (outillage). */
+    add(entry: ProfileEntry): boolean;
+    /** Le rapport à cet instant ; l'accumulateur continue d'accepter des profils. */
+    result(): IProfileReport;
+}
+/**
+ * Réduit une requête SQL (ou le descripteur d'une commande NoSQL) à sa FORME :
+ * valeurs remplacées par `?`, listes de valeurs repliées, blancs compactés.
+ *
+ * Deux requêtes qui ne diffèrent que par leurs valeurs ont la même forme — c'est
+ * ce qui permet de reconnaître un N+1. Et aucune valeur ne survit : la forme
+ * peut sortir dans un rapport sans emporter une donnée personnelle.
+ *
+ * @param sql - le texte tel que l'adaptateur l'a poussé au profileur.
+ * @returns la forme normalisée.
+ */
+export declare function sqlShape(sql: string): string;
+/**
+ * Une requête en ERREUR du serveur : statut ≥ 500, ou exception levée sans
+ * verdict client. Règle unique — le rapport, ses exemples et la lecture de leurs
+ * journaux en dépendent.
+ *
+ * Un statut 4xx n'en est JAMAIS une, même porteur d'une exception : un refus
+ * 401/403 (l'authentification lève une `AuthenticationError`) ou une ressource
+ * absente est le verdict rendu au client, compté à part — le lister parmi les
+ * erreurs ferait chercher une panne là où il manque une identité.
+ *
+ * @param entry - le profil (seuls statut et erreur sont lus).
+ */
+export declare function isFailedProfile(entry: Pick<ProfileEntry, "status" | "error">): boolean;
+/**
+ * Le chemin d'une URL de profil. Le profileur enregistre l'URL ABSOLUE
+ * (`http://hôte:port/chemin`) : un filtre écrit sur le chemin ne mordrait
+ * jamais dessus. Sans `URL` à construire — appelée sur chaque profil lu.
+ */
+export declare function urlPath(url: string): string;
+/**
+ * Crée un accumulateur de profils.
+ *
+ * @param options - seuil N+1, prise en compte de l'outillage, aléa injecté.
+ * @returns l'accumulateur ; son `result()` peut être appelé à tout moment.
+ */
+export declare function createProfileAggregator(options?: IProfileAggregatorOptions): IProfileAggregator;
+/**
+ * Agrège une liste de profils en une fois.
+ *
+ * @param entries - les profils, dans n'importe quel ordre.
+ * @param options - mêmes réglages que {@link createProfileAggregator}.
+ * @returns le rapport.
+ */
+export declare function aggregateProfiles(entries: Iterable<ProfileEntry>, options?: IProfileAggregatorOptions): IProfileReport;