nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/realtime/JsonRpcPeer.js

@@ -0,0 +1,251 @@
+//#region src/realtime/JsonRpcPeer.ts
+var RpcError = class extends Error {
+	name = "RpcError";
+	data;
+	constructor(message, code = -32e3, data) {
+		super(message);
+		this.code = code;
+		if (data !== void 0) this.data = data;
+	}
+};
+/**
+* Réponse d'un handler qui veut JOINDRE des métadonnées serveur à son résultat.
+*
+* Un handler retourne normalement sa valeur nue (elle devient `result`). Quand
+* il retourne une enveloppe, le peer la déballe : `result` reste la valeur nue,
+* et `meta` voyage dans un champ frère de la trame JSON-RPC. Coût pour ceux qui
+* ne l'utilisent pas : un `instanceof` par frame.
+*/
+var RpcEnvelope = class {
+	result;
+	meta;
+	constructor(result, meta) {
+		this.result = result;
+		this.meta = meta;
+	}
+};
+var JsonRpcPeer = class JsonRpcPeer {
+	opts;
+	nextId = 1;
+	pending = null;
+	actions = null;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/** Expose une action (requête entrante `method`+`id` → `result`). Idempotent. */
+	register(method, handler) {
+		(this.actions ??= /* @__PURE__ */ new Map()).set(method, handler);
+	}
+	/** Retire une action. */
+	unregister(method) {
+		this.actions?.delete(method);
+	}
+	/** Liste des actions exposées (pour annoncer au handshake, découverte côté pair). */
+	get methods() {
+		return this.actions ? [...this.actions.keys()] : [];
+	}
+	/** Requête SORTANTE — `Promise` résolue avec le `result` (rejette sur `error`/timeout). */
+	request(method, params, timeoutMs = 3e4) {
+		return this.startCall(method, params, timeoutMs);
+	}
+	/**
+	* Requête SORTANTE **tracée** — rend `{ result, meta }` au lieu du `result` nu.
+	*
+	* Même appel que {@link request} : la seule différence est que l'appelant
+	* garde la méta serveur (en dev, le `requestId` du profil de la frame → sa
+	* radiographie). Un serveur qui n'en émet pas laisse simplement `meta`
+	* absent.
+	*/
+	requestTraced(method, params, timeoutMs = 3e4) {
+		return this.startCall(method, params, timeoutMs, true);
+	}
+	/**
+	* Frame d'une notification sortante — **source unique** de sa forme.
+	*
+	* Extraite pour que le fan-out d'un canal diffusé puisse sérialiser la frame
+	* **une seule fois** pour N abonnés, sans jamais risquer de diverger du format
+	* qu'émet {@link notify} : les deux voies passent par ici.
+	*
+	* @param method - nom de la méthode (côté canal : le nom du canal).
+	* @param params - charge applicative ; omise de la frame si `undefined`.
+	* @returns la frame JSON-RPC 2.0, prête à sérialiser.
+	*/
+	static buildNotification(method, params) {
+		return {
+			jsonrpc: "2.0",
+			method,
+			params
+		};
+	}
+	/**
+	* Notification SORTANTE (pas de réponse attendue).
+	*
+	* @returns `false` si le transport a signalé qu'il n'a pas émis. Une
+	* notification n'attend rien en retour : sans cette valeur, une frame perdue
+	* ne laisserait aucune trace chez l'appelant. Les appels qui se rattrapent
+	* seuls (ré-abonnement au reconnect) peuvent l'ignorer.
+	*/
+	notify(method, params) {
+		return this.opts.send(JsonRpcPeer.buildNotification(method, params)) !== false;
+	}
+	/**
+	* Ingestion d'une frame ENTRANTE déjà parsée → classe (request/notification/
+	* response) et route. Renvoie la nature (utile log/tests). Ne lève jamais.
+	* (Le pendant sortant = `request`/`notify` ; le `send` brut est injecté.)
+	*/
+	receive(msg) {
+		if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0") {
+			this.opts.onFrameAudit?.("invalid", msg, this);
+			return "invalid";
+		}
+		const id = msg.id;
+		const hasId = typeof id === "number" || typeof id === "string";
+		const rawMethod = msg.method;
+		const method = typeof rawMethod === "string" ? rawMethod : void 0;
+		const params = msg.params;
+		if (method !== void 0) {
+			if (this.opts.beforeDispatch && !this.opts.beforeDispatch(msg, this)) {
+				this.opts.onFrameAudit?.("denied", msg, this);
+				if (hasId) {
+					this.opts.send({
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32001,
+							message: "unauthorized"
+						}
+					});
+					return "request";
+				}
+				return "notification";
+			}
+			if (hasId) {
+				this.handleRequest(id, method, params, msg);
+				return "request";
+			}
+			this.opts.onNotification?.(method, params);
+			return "notification";
+		}
+		if (hasId) {
+			this.handleResponse(msg);
+			return "response";
+		}
+		this.opts.onFrameAudit?.("invalid", msg, this);
+		return "invalid";
+	}
+	/** Annule tous les pending (fermeture du transport). */
+	dispose(reason = "peer disposed") {
+		if (!this.pending) return;
+		for (const p of this.pending.values()) {
+			if (p.timer) clearTimeout(p.timer);
+			p.reject(new Error(reason));
+		}
+		this.pending.clear();
+	}
+	startCall(method, params, timeoutMs, withMeta) {
+		const id = this.nextId++;
+		const pending = this.pending ??= /* @__PURE__ */ new Map();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`RPC timeout: ${method}`));
+			}, timeoutMs);
+			pending.set(id, {
+				resolve: (v) => {
+					clearTimeout(timer);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(timer);
+					reject(e);
+				},
+				timer,
+				withMeta
+			});
+			if (this.opts.send({
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			}) === false) {
+				clearTimeout(timer);
+				pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`RPC non émis (transport indisponible) : ${method}`));
+			}
+		});
+	}
+	handleRequest(id, method, params, rawFrame) {
+		const handler = this.actions?.get(method);
+		if (!handler) {
+			this.opts.onFrameAudit?.("method_not_found", rawFrame, this);
+			this.opts.send({
+				jsonrpc: "2.0",
+				id,
+				error: {
+					code: -32601,
+					message: `method not found: ${method}`
+				}
+			});
+			return;
+		}
+		Promise.resolve().then(() => handler(params)).then((result) => {
+			if (result instanceof RpcEnvelope) {
+				this.opts.send({
+					jsonrpc: "2.0",
+					id,
+					result: result.result,
+					meta: result.meta
+				});
+				return;
+			}
+			this.opts.send({
+				jsonrpc: "2.0",
+				id,
+				result
+			});
+		}, (err) => {
+			if (err instanceof RpcError) {
+				const error = {
+					code: err.code,
+					message: err.message
+				};
+				if (err.data !== void 0) error.data = err.data;
+				this.opts.send({
+					jsonrpc: "2.0",
+					id,
+					error
+				});
+				return;
+			}
+			this.opts.onError?.(`rpc ${method}`, err);
+			this.opts.onFrameAudit?.("internal_error", rawFrame, this);
+			this.opts.send({
+				jsonrpc: "2.0",
+				id,
+				error: {
+					code: -32603,
+					message: "internal error"
+				}
+			});
+		});
+	}
+	handleResponse(msg) {
+		if (typeof msg.id !== "number" || !this.pending) return;
+		const pending = this.pending.get(msg.id);
+		if (!pending) return;
+		if (msg.error) {
+			this.pending.delete(msg.id);
+			pending.reject(new RpcError(msg.error.message, msg.error.code, msg.error.data));
+			return;
+		}
+		if ("result" in msg) {
+			this.pending.delete(msg.id);
+			pending.resolve(pending.withMeta ? {
+				result: msg.result,
+				meta: msg.meta
+			} : msg.result);
+		}
+	}
+};
+//#endregion
+export { JsonRpcPeer, JsonRpcPeer as default, RpcEnvelope, RpcError };

package/dist/node/realtime/RealtimeEventMap.js

@@ -0,0 +1,15 @@
+//#region src/realtime/RealtimeEventMap.ts
+/**
+* Assertion type **compile-time** : `expectType<T>(value)` échoue à la compilation
+* si `value` n'est pas assignable à `T`. **0 coût runtime** (fonction vide).
+*
+* @example
+* ```ts
+* const x = peer.request("chat:ping");
+* expectType<Promise<{ pong: boolean }>>(x); // ✅
+* expectType<Promise<string>>(x);            // ❌ TS error
+* ```
+*/
+function expectType(_value) {}
+//#endregion
+export { expectType };

package/dist/node/realtime/channelRate.js

@@ -0,0 +1,39 @@
+//#region src/realtime/channelRate.ts
+/**
+* Construit le nom d'un canal cadencé à partir de sa base et de la cadence demandée.
+*
+* `intervalMs` omis OU égal à `defaultMs` → renvoie `base` nu : on **n'émet pas** de suffixe
+* pour la cadence par défaut, ce qui évite de fragmenter le canal de base entre consommateurs
+* qui veulent tous la valeur par défaut (ils partagent alors un seul ticker ref-compté).
+*
+* @param base - canal de base (ex. `"nodefony:orm:health"`).
+* @param intervalMs - cadence demandée (ms). Omise → canal de base.
+* @param defaultMs - cadence par défaut du canal ; `intervalMs === defaultMs` ⇒ canal de base.
+* @returns `base` ou `base:<ms>`.
+*/
+function rateChannel(base, intervalMs, defaultMs) {
+	if (intervalMs == null || intervalMs === defaultMs) return base;
+	return `${base}:${intervalMs}`;
+}
+/**
+* Résout la cadence (ms) d'un canal cadencé connu, côté serveur. Le serveur connaît la `base`
+* qu'il vient de matcher ; ce helper en extrait le suffixe `:<ms>`, **borne** dans `bounds` et
+* retombe sur `bounds.default` pour le canal de base nu ou un suffixe invalide.
+*
+* @param channel - canal reçu (`base` ou `base:<ms>`).
+* @param base - canal de base déjà identifié par l'appelant.
+* @param bounds - cadence par défaut + bornes min/max.
+* @returns cadence effective (ms), garantie dans `[bounds.min, bounds.max]` (ou `bounds.default`).
+*/
+function parseRate(channel, base, bounds) {
+	if (channel === base) return bounds.default;
+	const raw = Number.parseInt(channel.slice(base.length + 1), 10);
+	if (!Number.isFinite(raw) || raw <= 0) return bounds.default;
+	return Math.min(bounds.max, Math.max(bounds.min, raw));
+}
+/** Vrai si `channel` est le canal de base nu OU une de ses variantes cadencées `base:<ms>`. */
+function isRateChannel(channel, base) {
+	return channel === base || channel.startsWith(`${base}:`);
+}
+//#endregion
+export { isRateChannel, parseRate, rateChannel };

package/dist/node/realtime/platformChannels.js

@@ -0,0 +1,155 @@
+//#region src/realtime/platformChannels.ts
+/**
+* platformChannels — **espace de nommage des surfaces temps réel de la plateforme**,
+* partagé par les deux bords de la socket (serveur et navigateur).
+*
+* Tout ce que Nodefony expose sur la socket pour parler **de lui-même** (journaux,
+* santé de la base, métriques du process, supervision du cluster, journal d'audit,
+* contrôle du pod) porte le préfixe {@link NODEFONY_CHANNEL_NAMESPACE}. Ce que
+* l'application expose pour parler de **son métier** ne le porte pas.
+*
+* C'est la même convention que les routes d'administration (`/nodefony/<module>/api/*`) :
+* une seule marque, des deux côtés du transport. Avant, chaque sonde apportait son
+* propre namespace (`syslog:`, `orm:`, `dashboard:`, `node:`…) — neuf territoires pour
+* une douzaine de canaux, dont un (`node:`) qui percutait le préfixe d'import des
+* modules natifs Node et polluait tout audit.
+*
+* **La table est la source unique** : personne n'écrit un nom de canal de plateforme en
+* clair, ni côté serveur (producteurs) ni côté navigateur (consommateurs). Une chaîne
+* recopiée dans un écran est une chaîne qui survivra au renommage suivant.
+*
+* Pur et isomorphe (aucun import, aucune allocation) : chargé aussi bien dans le bundle
+* navigateur que dans le pod.
+*
+* @see {@link rateChannel} — le suffixe de cadence (`base:<ms>`) se compose PAR-DESSUS
+*   ces bases ; ajouter un segment au préfixe ne le perturbe pas.
+*/
+/**
+* Marque des surfaces de plateforme sur la socket. Un canal qui commence par ce préfixe
+* décrit le serveur, jamais le métier de l'application.
+*
+* Conséquence côté sécurité : ces canaux ont un **plancher irréductible**
+* (authentification exigée, et sans module de sécurité ils sont purement fermés aux
+* connexions clientes). Une application ne peut pas se les approprier par accident —
+* c'est tout l'intérêt d'une marque en toutes lettres plutôt que d'un mot courant.
+*/
+const NODEFONY_CHANNEL_NAMESPACE = "nodefony:";
+/**
+* Canaux de **diffusion** de la plateforme (le serveur pousse, les écrans regardent).
+*
+* Les valeurs sont des **bases** : trois d'entre elles se déclinent par cible
+* (`…@<pid>` pour un forage sur un process, `…@<id>` pour un job) et toutes acceptent
+* le suffixe de cadence `:<ms>` (cf {@link rateChannel}). Composer, jamais concaténer
+* un préfixe à la main.
+*/
+const PLATFORM_CHANNELS = {
+	/** Journaux du pod (flux de `Pdu`, coalescé par le pont syslog). */
+	syslog: "nodefony:syslog",
+	/** Journal d'audit sécurité — plancher super-admin, un cran au-dessus des autres. */
+	audit: "nodefony:audit",
+	/** Métriques agrégées du tableau de bord (vue d'ensemble). */
+	dashboard: "nodefony:dashboard",
+	/** Supervision des process du cluster ; forage par process : `…@<pid>`. */
+	supervision: "nodefony:supervision",
+	/** Sondes de la barre de debug (mêmes mesures que la supervision, ticker séparé). */
+	debugbar: "nodefony:debugbar",
+	/** Auto-observabilité de la socket elle-même (canaux, abonnés, fan-out, backpressure). */
+	socket: "nodefony:socket",
+	/** Santé des connecteurs de base (état, ping). */
+	ormHealth: "nodefony:orm:health",
+	/** Flux ORM (débit de requêtes, latence, requêtes lentes) — plus dynamique que la santé. */
+	ormFlow: "nodefony:orm:flow",
+	/** Forage détaillé d'un connecteur sur un process donné : `…@<pid>`. */
+	ormRich: "nodefony:orm:rich",
+	/** Sortie d'un job de génération de code : `…@<jobId>` (développement uniquement). */
+	scaffoldJob: "nodefony:scaffold:job"
+};
+/**
+* Canaux **MONTANTS** de la plateforme (le navigateur pousse, le pod reçoit).
+*
+* Ils vivent dans une table à part parce qu'ils sont l'inverse de
+* {@link PLATFORM_CHANNELS} : là un écran regarde, ici un écran ÉCRIT. Les mélanger
+* ferait passer une surface d'écriture pour une surface de lecture au premier coup
+* d'œil — et c'est précisément la distinction qui décide des bornes à poser.
+*
+* Ils portent la même marque `nodefony:`, donc le même **plancher irréductible**
+* (authentification exigée ; sans module de sécurité, fermés aux connexions
+* clientes). C'est le défaut voulu : un journal d'exploitation ouvert en écriture
+* anonyme se noie et se falsifie. Une application qui veut capter les erreurs de
+* visiteurs non authentifiés le déclare explicitement, et hérite des bornes.
+*/
+const PLATFORM_INBOUND = { 
+/** Journaux du navigateur remontés vers le `Syslog` du pod (lots de `Pdu`). */
+syslogUplink: "nodefony:syslog:uplink" };
+/**
+* Méthodes **RPC** de la plateforme (le client demande, le serveur répond).
+*
+* Elles portent la même marque que les canaux pour la même raison : ce sont des
+* surfaces du serveur, pas de l'application. `nodefony:kernel:gc` déclenche un cycle
+* de ramasse-miettes bloquant — un nom aussi lourd de conséquences n'a rien à faire
+* dans l'espace de nommage où une application déclare ses propres actions.
+*
+* ⚠️ À ne pas confondre avec les **notifications du protocole** (`realtime:welcome`,
+* `realtime:denied`) : celles-là décrivent la mécanique de la socket elle-même, pas
+* une surface de la plateforme, et ne sont ni des canaux ni des actions.
+*/
+const PLATFORM_METHODS = {
+	/** Liveness + mesure du temps d'aller-retour. */
+	ping: "nodefony:kernel:ping",
+	/** Force un cycle GC (seulement si le pod tourne avec `--expose-gc`). */
+	gc: "nodefony:kernel:gc",
+	/** Ce qu'un scaffold écrirait — fichiers créés, diff des réécritures — sans rien écrire. */
+	scaffoldPreview: "nodefony:scaffold:preview",
+	/** Démarre un job de génération de code et rend son identifiant. */
+	scaffoldRun: "nodefony:scaffold:run",
+	/** Demande l'arrêt d'un job de génération en cours. */
+	scaffoldCancel: "nodefony:scaffold:cancel"
+};
+/**
+* Événements **DOM** de la plateforme (`window`), dans le même espace de nommage.
+*
+* Ils ne passent pas par la socket — ce sont des `CustomEvent` que le navigateur
+* fait circuler entre la barre de debug, le pont HMR et l'écran qui les écoute.
+* Ils portent la marque pour la même raison que les canaux : `window` est un
+* espace partagé avec l'application, et un nom d'événement générique s'y
+* télescoperait.
+*/
+const PLATFORM_EVENTS = {
+	/** Un hot-update Vite vient d'être appliqué (émis par le pont du template). */
+	hmr: "nodefony:hmr",
+	/** L'utilisateur a choisi une entrée dans la barre de debug. */
+	debugbarSelect: "nodefony:debugbar:select"
+};
+/**
+* `s` commence-t-il par `prefix`, **insensible à la casse** et sans allocation ?
+*
+* La casse doit être neutralisée : sinon `NODEFONY:syslog` échapperait au plancher que
+* `nodefony:syslog` subit — un contournement à un `toUpperCase()` près. Comparaison
+* caractère par caractère plutôt que `toLowerCase()` : ce test est sur le chemin
+* d'abonnement, on n'y alloue pas de chaîne.
+*/
+function startsWithCI(s, prefix) {
+	if (s.length < prefix.length) return false;
+	for (let i = 0; i < prefix.length; i += 1) {
+		let a = s.charCodeAt(i);
+		if (a >= 65 && a <= 90) a += 32;
+		let b = prefix.charCodeAt(i);
+		if (b >= 65 && b <= 90) b += 32;
+		if (a !== b) return false;
+	}
+	return true;
+}
+/**
+* Le nom désigne-t-il une surface de la plateforme (canal OU méthode) ?
+*
+* Un seul `startsWith` insensible à la casse, là où il fallait auparavant parcourir
+* neuf préfixes à chaque abonnement.
+*
+* @param name - nom du canal demandé (suffixes de cadence/forage inclus) ou de la
+*   méthode RPC appelée.
+*/
+function isPlatformChannel(name) {
+	return startsWithCI(name, NODEFONY_CHANNEL_NAMESPACE);
+}
+//#endregion
+export { NODEFONY_CHANNEL_NAMESPACE, PLATFORM_CHANNELS, PLATFORM_EVENTS, PLATFORM_INBOUND, PLATFORM_METHODS, isPlatformChannel, startsWithCI };

package/dist/node/runtime/GcScheduler.js

@@ -0,0 +1,92 @@
+//#region src/runtime/GcScheduler.ts
+const DEFAULT_INITIAL_DELAY_MS = 3e4;
+const DEFAULT_JITTER_CAP_MS = 6e4;
+/**
+* Timer de maintenance déterministe, jittéré et désarmable. Voir la doc du
+* module pour le rationnel complet.
+*
+* @example
+* ```ts
+* const gc = new GcScheduler({
+*   intervalS: config.gcIntervalS,
+*   jitter: config.gcJitter,
+*   run: () => store.gc(),
+*   onError: (e) => this.log(e, "WARNING"),
+* });
+* gc.start();           // au boot / onReady
+* // …
+* gc.stop();            // au onTerminate
+* ```
+*/
+var GcScheduler = class {
+	/** Timer du délai initial (jittéré) — `null` tant que non armé / après tir. */
+	#start = null;
+	/** Timer récurrent — `null` tant que la 1ʳᵉ passe n'a pas eu lieu / après stop. */
+	#timer = null;
+	/** Garde-fou anti-empilement : `true` pendant qu'une passe court. */
+	#running = false;
+	#opts;
+	constructor(opts) {
+		this.#opts = opts;
+	}
+	/** `true` si l'ordonnanceur est armé (délai initial en cours OU timer récurrent). */
+	get armed() {
+		return this.#start !== null || this.#timer !== null;
+	}
+	/**
+	* Arme l'ordonnanceur. Idempotent (no-op si déjà armé). Retourne `false` si
+	* `intervalS ≤ 0` (désarmé volontaire — délégation cron / TTL natif), `true`
+	* si un timer a été posé. Premier balayage après `initialDelayMs (+ jitter)`,
+	* puis tous les `intervalS`.
+	*/
+	start() {
+		if (this.armed) return true;
+		const intervalS = this.#opts.intervalS;
+		if (!Number.isFinite(intervalS) || intervalS <= 0) return false;
+		const base = intervalS * 1e3;
+		const cap = this.#opts.jitterCapMs ?? DEFAULT_JITTER_CAP_MS;
+		const initial = this.#opts.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+		const phase = this.#opts.jitter === false ? 0 : Math.floor(Math.random() * Math.min(base, cap));
+		const start = setTimeout(() => {
+			this.#start = null;
+			this.runNow();
+			const timer = setInterval(() => void this.runNow(), base);
+			timer.unref?.();
+			this.#timer = timer;
+		}, initial + phase);
+		start.unref?.();
+		this.#start = start;
+		return true;
+	}
+	/**
+	* Exécute une passe **immédiatement** — point d'entrée public (le timer
+	* l'appelle ; un worker cron / une commande batch peut l'appeler à sa place).
+	* Anti-empilement : ignore l'appel si une passe court déjà. **Ne lève jamais**
+	* — une erreur va à `onError`, pour ne pas tuer le déclencheur (retry au tick
+	* suivant).
+	*/
+	async runNow() {
+		if (this.#running) return;
+		this.#running = true;
+		try {
+			await this.#opts.run();
+		} catch (error) {
+			this.#opts.onError?.(error);
+		} finally {
+			this.#running = false;
+		}
+	}
+	/** Désarme les timers (idempotent) — à appeler au shutdown. */
+	stop() {
+		if (this.#start) {
+			clearTimeout(this.#start);
+			this.#start = null;
+		}
+		if (this.#timer) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+	}
+};
+//#endregion
+export { GcScheduler };

package/dist/node/runtime/RequestContext.js

@@ -0,0 +1,76 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/runtime/RequestContext.ts
+/**
+* AsyncLocalStorage facade — single shared instance per process. Lazily
+* constructed so importing this module has zero cost if `run()` is never
+* called (the ALS allocation is the only cost).
+*
+* Perf : `als.run` adds ~50-100 ns per request on Node 22+. `.getStore()`
+* is a hot-path read — keep it cheap.
+*/
+var RequestContext = class {
+	static _als = null;
+	static get als() {
+		if (this._als === null) this._als = new AsyncLocalStorage();
+		return this._als;
+	}
+	/** Enter a new request scope. All `await`s inside `fn` see the payload. */
+	static run(payload, fn) {
+		return this.als.run(payload, fn);
+	}
+	/** Returns the current payload, or `undefined` outside any request scope. */
+	static get() {
+		if (this._als === null) return void 0;
+		return this._als.getStore();
+	}
+	/** Shortcut — returns the current requestId or `undefined`. */
+	static getRequestId() {
+		return this.get()?.requestId;
+	}
+	/** Shortcut — returns the current authenticated user (P6) or `undefined`. */
+	static getUser() {
+		return this.get()?.user;
+	}
+	/**
+	* Shortcut — returns the current transport context (V4.1) or `undefined`.
+	* Générique car le core ne connaît pas les types de `@nodefony/http` :
+	* `RequestContext.getContext<ContextType>()` côté framework.
+	*/
+	static getContext() {
+		return this.get()?.context;
+	}
+	/** Shortcut — returns the current userId (P6) or `undefined`. */
+	static getUserId() {
+		return this.get()?.userId;
+	}
+	/**
+	* Mutate the current payload in place. No-op outside a scope.
+	* Used by security after login to inject `user`/`userId` without re-running.
+	*/
+	static set(key, value) {
+		const store = this.get();
+		if (store) store[key] = value;
+	}
+	/**
+	* `true` si un buffer de profiling de requêtes ORM est actif sur le scope
+	* courant (dev + `HttpKernel` profiler activé). Les adapters ORM lisent ce
+	* flag AVANT de mesurer (`performance.now()`) pour rester gratuits en prod.
+	*
+	* @returns `true` si `pushQuery` aura un effet, `false` sinon.
+	*/
+	static isProfiling() {
+		return this.get()?.queries !== void 0;
+	}
+	/**
+	* Pousse une requête ORM dans le buffer de profiling du scope courant.
+	* No-op hors scope ou hors dev (buffer absent) → coût nul en prod.
+	*
+	* @param query - requête capturée (sql, durée, lignes, connecteur).
+	*/
+	static pushQuery(query) {
+		const buf = this.get()?.queries;
+		if (buf) buf.push(query);
+	}
+};
+//#endregion
+export { RequestContext as default };