@nodefony/orm-core 10.0.0-alpha.1

package/dist/nodefony/src/OrmAdminApi.js

@@ -0,0 +1,491 @@
+import { ormRegistry } from "./OrmRegistry.js";
+import { entityRegistry } from "./EntityRegistry.js";
+import { connectionMonitor } from "./ConnectionMonitor.js";
+import { queryFlowMonitor } from "./QueryFlowMonitor.js";
+import { performance } from "node:perf_hooks";
+//#region nodefony/src/OrmAdminApi.ts
+/**
+* Producteur `IAdminApi` du **modèle de données ORM** — exposé sous
+* `/nodefony/orm/api/*`. Fondation « IA-first » : construit le graphe canonique
+* (ORMs, entités, colonnes, relations) depuis les registres process-wide
+* ({@link ormRegistry} + {@link entityRegistry}), et l'exporte vers des formats
+* que l'écosystème IA comprend (**DBML** d'abord).
+*
+* orm-core est une **lib pure** (pas un Module) → il ne peut pas s'auto-monter ;
+* un module driver l'enregistre via {@link registerOrmAdminApi} à son boot
+* (idempotent). Le graphe lit les registres GLOBAUX → couvre tous les ORM
+* présents, peu importe quel adapter a enregistré l'API.
+*
+* Endpoints :
+*  - `GET /nodefony/orm/api/orms`           → résumé des ORM/connecteurs
+*  - `GET /nodefony/orm/api/entities`       → entités (`?connector=` pour filtrer)
+*  - `GET /nodefony/orm/api/entity/{name}`  → une entité (`?connector=`)
+*  - `GET /nodefony/orm/api/graph`          → graphe complet (`?connector=`)
+*  - `GET /nodefony/orm/api/export/{format}`→ export (`dbml`), `?connector=`
+*  - `GET /nodefony/orm/api/migrations`     → état des migrations (`?connector=`)
+*/
+/** Première valeur d'un param de query (`?connector=default`). */
+function oneParam(req, key) {
+	const raw = req.query[key];
+	return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+* Vendor de l'adapter dérivé de son nom de classe (`DrizzleOrm` → `drizzle`,
+* `DrizzleOrm`/`Drizzle` → `drizzle`…). Dette : remplacer par un
+* `IOrm.vendor` déclaré par chaque adapter (P7.1). `""` si indéterminé.
+*/
+function vendorOf(orm) {
+	const cls = orm?.constructor?.name;
+	if (!cls) return "";
+	return cls.replace(/Orm$/, "").toLowerCase();
+}
+/**
+* Résout un connecteur et lui demande UNE de ses capacités de migration.
+*
+* Les trois points de migration posent la même question dans le même ordre —
+* le connecteur existe-t-il, porte-t-il la capacité, que répond-elle — et
+* trois copies de cette suite auraient fini par répondre trois choses
+* différentes au même cas.
+*
+* @param request - requête admin (`?connector=`, défaut « default »).
+* @param capability - nom de la méthode optionnelle demandée à l'ORM.
+* @param missingMessage - ce qu'on dit quand l'ORM ne la porte pas.
+* @returns la réponse de l'ORM, ou une réponse d'administration explicite.
+*/
+async function migrationCapability(request, capability, missingMessage) {
+	const connector = oneParam(request, "connector") ?? "default";
+	if (!ormRegistry.has(connector)) return {
+		status: 404,
+		body: { error: `aucun connecteur « ${connector} » — ceux que cette application déclare : ${ormRegistry.list().join(", ") || "aucun"}` }
+	};
+	const orm = ormRegistry.get(connector);
+	const fn = orm[capability];
+	if (typeof fn !== "function") return {
+		status: 501,
+		body: {
+			formatVersion: 1,
+			connector,
+			error: {
+				code: "NF_MIGRATE_NO_MIGRATIONS",
+				summary: `Le connecteur « ${connector} » est porté par ${vendorOf(orm) || orm.name}, dont la base ne se met pas à jour par des migrations de schéma.`,
+				meaning: `${missingMessage} Les migrations par fichiers versionnés sont une mécanique SQL ; les autres bases résorbent l'écart entre le code et le schéma autrement.`,
+				nextActions: []
+			}
+		}
+	};
+	return fn.call(orm);
+}
+/** Résumé des ORM enregistrés (statut connexion + nombre d'entités). */
+function buildOrmSummaries() {
+	const entities = entityRegistry.list();
+	return ormRegistry.list().map((name) => {
+		let connected = false;
+		let vendor = "";
+		let connection;
+		try {
+			const orm = ormRegistry.get(name);
+			connected = orm.isConnected();
+			vendor = vendorOf(orm);
+			connection = orm.describeConnection?.();
+		} catch {
+			connected = false;
+		}
+		return {
+			name,
+			vendor,
+			default: name === "default",
+			connected,
+			entityCount: entities.filter((e) => e.connector === name).length,
+			connection
+		};
+	});
+}
+/**
+* Construit un nœud de graphe pour une entité : relations (toujours) + colonnes
+* (via `orm.describeEntity` si l'adapter l'implémente et si l'ORM est connecté).
+*/
+function buildEntityNode(connector, name) {
+	const entity = entityRegistry.get(name, connector);
+	let columns = [];
+	try {
+		columns = ormRegistry.get(connector).describeEntity?.(name) ?? [];
+	} catch {
+		columns = [];
+	}
+	return {
+		name: entity.name,
+		connector: entity.connector,
+		module: entity.module ?? "",
+		domain: entity.domain ?? "",
+		columns,
+		relations: (entity.relations ?? []).map((r) => ({
+			type: r.type,
+			target: r.target,
+			field: r.field,
+			foreignKey: r.foreignKey
+		}))
+	};
+}
+/** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
+function buildOrmGraph(connectorFilter) {
+	const orms = buildOrmSummaries();
+	const entities = entityRegistry.list().filter((e) => !connectorFilter || e.connector === connectorFilter).map((e) => buildEntityNode(e.connector, e.name));
+	return {
+		orms: connectorFilter ? orms.filter((o) => o.name === connectorFilter) : orms,
+		entities
+	};
+}
+/**
+* Construit le **diagnostic complet des connexions** (per-instance) : ping live
+* (latence enregistrée dans la fenêtre glissante), sonde profonde driver
+* ({@link IOrm.probe} — stockage/pool), et compteurs de cycle de vie du
+* {@link connectionMonitor}. Réutilisé par l'endpoint `connection/health` ET par
+* le ticker hub realtime de Studio (« contrôle total des ORM »).
+*
+* @param filter - nom de connecteur (optionnel) pour ne sonder que celui-ci.
+* @returns un {@link IConnectionHealth} par connecteur.
+*/
+async function buildConnectionHealth(filter) {
+	const instanceId = String(process.pid);
+	const names = ormRegistry.list().filter((n) => !filter || n === filter);
+	const out = [];
+	for (const name of names) {
+		let connected = false;
+		let vendor = "";
+		let driver = "";
+		let target;
+		let version;
+		let ormVersion;
+		let pingMs = null;
+		let pingOk = false;
+		let pingError = null;
+		let storage;
+		let pool;
+		let extra;
+		try {
+			const inst = ormRegistry.get(name);
+			connected = inst.isConnected();
+			vendor = vendorOf(inst);
+			const c = inst.describeConnection?.();
+			if (c) {
+				driver = c.driver;
+				target = c.target;
+				version = c.version;
+				ormVersion = c.ormVersion;
+			}
+			if (connected) {
+				const t0 = performance.now();
+				try {
+					if (typeof inst.ping === "function") await inst.ping();
+					else await inst.transaction(async () => void 0);
+					pingMs = Math.round((performance.now() - t0) * 100) / 100;
+					pingOk = true;
+					connectionMonitor.recordPing(name, pingMs);
+				} catch (e) {
+					pingError = e instanceof Error ? e.message : "ping failed";
+					connectionMonitor.recordError(name, pingError);
+				}
+				try {
+					const probe = await inst.probe?.();
+					if (probe) {
+						storage = probe.storage;
+						pool = probe.pool;
+						extra = probe.extra;
+					}
+				} catch {}
+			}
+		} catch (e) {
+			pingError = e instanceof Error ? e.message : String(e);
+		}
+		const core = connectionMonitor.snapshot(name);
+		out.push({
+			instanceId,
+			name,
+			vendor,
+			driver,
+			target,
+			version,
+			ormVersion,
+			connected,
+			connectedSince: core.connectedSince,
+			uptimeMs: core.uptimeMs,
+			connectCount: core.connectCount,
+			reconnectCount: core.reconnectCount,
+			errorCount: core.errorCount,
+			lastError: core.lastError,
+			recentErrors: core.recentErrors,
+			lastConnectMs: core.lastConnectMs,
+			pingMs,
+			pingOk,
+			pingError,
+			latency: core.latency,
+			storage,
+			pool,
+			extra
+		});
+	}
+	return out;
+}
+/**
+* Construit le rapport de **flux ORM** (per-instance) : débit (via `total`),
+* latence (moyenne + EWMA), pire latence et requêtes lentes récentes, par
+* connecteur enregistré. Lecture pure du {@link queryFlowMonitor} (aucune
+* requête émise — contrairement à `buildConnectionHealth` qui ping) → bon marché.
+* Réutilisé par l'endpoint `flow` ET le ticker hub realtime de Studio.
+*
+* @param filter - nom de connecteur (optionnel) pour ne rapporter que celui-ci.
+* @returns le rapport (`enabled=false` en prod → connecteurs à 0).
+*/
+function buildOrmFlow(filter) {
+	const connectors = ormRegistry.list().filter((n) => !filter || n === filter).map((name) => {
+		let vendor = "";
+		try {
+			vendor = vendorOf(ormRegistry.get(name));
+		} catch {
+			vendor = "";
+		}
+		return queryFlowMonitor.snapshot(name, vendor);
+	});
+	return {
+		enabled: queryFlowMonitor.enabled,
+		ts: Date.now(),
+		instanceId: String(process.pid),
+		slowMs: queryFlowMonitor.slowMs,
+		connectors
+	};
+}
+/** Échappe un identifiant DBML s'il contient autre chose que `[A-Za-z0-9_]`. */
+function dbmlId(name) {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `"${name}"`;
+}
+/**
+* Sérialise un graphe en **DBML** (Database Markup Language) — format pivot lu
+* par dbdiagram.io, les outils IA et convertible en SQL. Les `Ref:` sont dérivés
+* des relations selon la convention FK des adapters (`<source>Id` sur la cible
+* pour 1-N ; `<target>Id` sur la source pour N-1/1-1). Le many-to-many est
+* annoté en commentaire (table de jonction non portable).
+*
+* @param graph - graphe canonique.
+* @returns texte DBML.
+*/
+function toDbml(graph) {
+	const lines = [];
+	for (const node of graph.entities) {
+		lines.push(`Table ${dbmlId(node.name)} {`);
+		if (node.columns.length === 0) lines.push("  // colonnes non introspectées par l'adapter");
+		for (const col of node.columns) {
+			const settings = [];
+			if (col.primaryKey) settings.push("pk");
+			if (col.unique && !col.primaryKey) settings.push("unique");
+			if (!col.nullable && !col.primaryKey) settings.push("not null");
+			const suffix = settings.length ? ` [${settings.join(", ")}]` : "";
+			lines.push(`  ${dbmlId(col.name)} ${col.type || "unknown"}${suffix}`);
+		}
+		lines.push("}");
+		lines.push("");
+	}
+	const refs = /* @__PURE__ */ new Set();
+	for (const node of graph.entities) for (const rel of node.relations) {
+		if (rel.type === "many-to-many") {
+			refs.add(`// many-to-many ${node.name}.${rel.field} <> ${rel.target} (table de jonction)`);
+			continue;
+		}
+		const camel = (n) => `${n.charAt(0).toLowerCase()}${n.slice(1)}Id`;
+		if (rel.type === "one-to-many") {
+			const fk = rel.foreignKey ?? camel(node.name);
+			refs.add(`Ref: ${dbmlId(rel.target)}.${dbmlId(fk)} > ${dbmlId(node.name)}.id`);
+		} else {
+			const fk = rel.foreignKey ?? camel(rel.target);
+			refs.add(`Ref: ${dbmlId(node.name)}.${dbmlId(fk)} > ${dbmlId(rel.target)}.id`);
+		}
+	}
+	lines.push(...refs);
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+/**
+* Mappe un type natif rapporté par l'adapter (`describeEntity`) vers un type
+* JSON Schema. Heuristique tolérante (SQL + Mongoose) : `INTEGER`→integer,
+* `VARCHAR(255)`/`uuid`/`ObjectId`→string, `BOOLEAN`→boolean, `json`→object,
+* `timestamp`→string(date-time). Défaut prudent : `string`.
+*/
+function jsonSchemaType(nativeType) {
+	const t = nativeType.toLowerCase();
+	if (/\b(serial|bigint|smallint|tinyint|mediumint|int|integer)\b/.test(t)) return { type: "integer" };
+	if (/(real|float|double|decimal|numeric|number)/.test(t)) return { type: "number" };
+	if (/bool/.test(t)) return { type: "boolean" };
+	if (/json/.test(t)) return { type: "object" };
+	if (/(date|time|timestamp)/.test(t)) return {
+		type: "string",
+		format: "date-time"
+	};
+	return { type: "string" };
+}
+/**
+* Sérialise un graphe en **JSON Schema** (draft 2020-12) — un `$defs` par
+* entité. Format « IA-first » : un agent (text-to-SQL, génération de formulaire,
+* validation de payload) consomme directement ce schéma. Les colonnes
+* non-nullables alimentent `required` ; les relations deviennent des `$ref`
+* (N→1/1→1) ou des tableaux de `$ref` (1→N/N→N) vers les autres `$defs`.
+*
+* @param graph - graphe canonique.
+* @returns document JSON Schema ({@link IJsonSchemaObject} par entité).
+*/
+function toJsonSchema(graph) {
+	const $defs = {};
+	for (const node of graph.entities) {
+		const properties = {};
+		const required = [];
+		for (const col of node.columns) {
+			properties[col.name] = jsonSchemaType(col.type);
+			if (!col.nullable) required.push(col.name);
+		}
+		for (const rel of node.relations) {
+			const ref = `#/$defs/${rel.target}`;
+			properties[rel.field] = rel.type === "one-to-many" || rel.type === "many-to-many" ? {
+				type: "array",
+				items: { $ref: ref }
+			} : { $ref: ref };
+		}
+		$defs[node.name] = {
+			type: "object",
+			title: node.name,
+			properties,
+			...required.length ? { required } : {},
+			additionalProperties: false
+		};
+	}
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		$defs
+	};
+}
+const descriptor = {
+	label: "ORM",
+	icon: "database",
+	order: 4
+};
+/**
+* Construit le producteur `IAdminApi` du data plane ORM.
+*
+* @returns le `IAdminApi` (namespace `"orm"`).
+*/
+function createOrmAdminApi() {
+	const endpoints = [
+		{
+			path: "orms",
+			summary: "ORMs/connecteurs enregistrés (statut + nombre d'entités)",
+			handler: () => buildOrmSummaries()
+		},
+		{
+			path: "entities",
+			summary: "Entités du modèle (colonnes + relations) — ?connector= pour filtrer",
+			handler: (request) => buildOrmGraph(oneParam(request, "connector")).entities
+		},
+		{
+			path: "entity/{name}",
+			summary: "Une entité (colonnes + relations) — ?connector= si homonymes",
+			handler: (request) => {
+				const name = request.params.name ?? "";
+				const connector = oneParam(request, "connector");
+				try {
+					const found = entityRegistry.list().find((e) => e.name === name && (!connector || e.connector === connector));
+					if (!found) return {
+						status: 404,
+						body: { error: `entity "${name}" not found` }
+					};
+					return buildEntityNode(found.connector, found.name);
+				} catch {
+					return {
+						status: 404,
+						body: { error: `entity "${name}" not found` }
+					};
+				}
+			}
+		},
+		{
+			path: "graph",
+			summary: "Graphe canonique complet (ORMs + entités) — ?connector= pour filtrer",
+			handler: (request) => buildOrmGraph(oneParam(request, "connector"))
+		},
+		{
+			path: "counts",
+			summary: "Nombre de lignes par entité (COUNT(*)) — ?connector= pour filtrer. Lazy : 1 COUNT par table.",
+			handler: async (request) => {
+				const connector = oneParam(request, "connector");
+				const counts = {};
+				const entities = entityRegistry.list().filter((e) => !connector || e.connector === connector);
+				for (const e of entities) try {
+					const inst = ormRegistry.get(e.connector);
+					counts[e.name] = inst.isConnected() ? await inst.getRepository(e.name).count() : -1;
+				} catch {
+					counts[e.name] = -1;
+				}
+				return counts;
+			}
+		},
+		{
+			path: "migrations",
+			summary: "État des migrations d'un connecteur (?connector=, défaut « default ») — MÊME objet que `orm:migrate:status --json`. 501 si l'ORM ne porte pas de migrations, 404 si le connecteur n'existe pas.",
+			handler: async (request) => migrationCapability(request, "migrationStatus", "Ce connecteur ne suit pas de migrations.")
+		},
+		{
+			path: "migrations/plan",
+			summary: "Ce qui S'APPLIQUERAIT, avec son SQL (?connector=) — lecture seule, sert la confirmation avant application.",
+			handler: async (request) => migrationCapability(request, "migrationPlan", "Ce connecteur ne sait pas dire ce qui s'appliquerait.")
+		},
+		{
+			path: "migrations/apply",
+			method: "POST",
+			summary: "Applique les migrations en attente (?connector=) — DÉVELOPPEMENT seulement : le pilote refuse ailleurs, en le disant. En production, les migrations passent par un travail d'orchestrateur.",
+			handler: async (request) => migrationCapability(request, "applyMigrations", "Ce connecteur ne sait pas appliquer de migrations.")
+		},
+		{
+			path: "connection/health",
+			summary: "Diagnostic des connexions (per-instance) — état, ping/latence (fenêtre), erreurs, reconnexions, sondes (stockage/pool). ?connector= pour filtrer.",
+			handler: (request) => buildConnectionHealth(oneParam(request, "connector"))
+		},
+		{
+			path: "flow",
+			summary: "Flux des requêtes (per-instance) — débit (via total), latence moy/EWMA, pire latence, requêtes lentes. ?connector= pour filtrer. enabled=false en prod.",
+			handler: (request) => buildOrmFlow(oneParam(request, "connector"))
+		},
+		{
+			path: "export/{format}",
+			summary: "Export du modèle — format: dbml | jsonschema (?connector= pour filtrer)",
+			handler: (request) => {
+				const format = (request.params.format ?? "").toLowerCase();
+				const graph = buildOrmGraph(oneParam(request, "connector"));
+				if (format === "dbml") return {
+					format: "dbml",
+					content: toDbml(graph)
+				};
+				if (format === "jsonschema") return {
+					format: "jsonschema",
+					content: JSON.stringify(toJsonSchema(graph), null, 2)
+				};
+				return {
+					status: 400,
+					body: { error: `unsupported export format "${format}" (dbml, jsonschema)` }
+				};
+			}
+		}
+	];
+	return {
+		adminNamespace: "orm",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+/**
+* Enregistre l'`OrmAdminApi` sur le broker admin, **idempotent** (no-op si déjà
+* monté). Appelé par un module driver à son `onKernelBoot` (orm-core est une lib
+* pure et ne peut pas s'auto-monter).
+*
+* @param registry - broker admin (`container.get("adminBroker")`).
+*/
+function registerOrmAdminApi(registry) {
+	if (registry.has("orm")) return;
+	registry.register(createOrmAdminApi());
+}
+//#endregion
+export { buildConnectionHealth, buildOrmFlow, buildOrmGraph, createOrmAdminApi, registerOrmAdminApi, toDbml, toJsonSchema };

package/dist/nodefony/src/OrmRegistry.js

@@ -0,0 +1,75 @@
+//#region nodefony/src/OrmRegistry.ts
+/**
+* Registre process-wide des instances ORM enregistrées sous un nom unique.
+*
+* Support multi-ORM natif : chaque driver (`@nodefony/mongoose`,
+* `@nodefony/drizzle`...) s'enregistre à son boot via
+* {@link OrmRegistry.register} sous une clé logique (`"db_principale"`,
+* `"db_logs"`...). Les consommateurs (repositories, session storage, security)
+* résolvent l'ORM voulu par cette clé, jamais par référence directe au driver.
+*
+* Pas de coupling à `nodefony` : structure pure et lazy (la `Map` interne n'est
+* allouée qu'au premier `register`), donc trivialement testable en isolation.
+*/
+var OrmRegistry = class {
+	/** Allouée paresseusement au premier enregistrement (zéro coût au boot). */
+	#orms = null;
+	/**
+	* Enregistre une instance ORM sous un nom unique.
+	*
+	* @param name - clé logique de l'ORM (ex. `"db_principale"`).
+	* @param orm - instance implémentant {@link IOrm}.
+	* @throws si un ORM du même nom est déjà enregistré (erreur de configuration).
+	*/
+	register(name, orm) {
+		if (this.#orms === null) this.#orms = /* @__PURE__ */ new Map();
+		if (this.#orms.has(name)) throw new Error(`OrmRegistry: an ORM named "${name}" is already registered.`);
+		this.#orms.set(name, orm);
+	}
+	/**
+	* Résout l'ORM enregistré sous un nom.
+	*
+	* @param name - clé logique de l'ORM.
+	* @returns l'instance {@link IOrm} correspondante.
+	* @throws si aucun ORM n'est enregistré sous ce nom.
+	*/
+	get(name) {
+		const orm = this.#orms?.get(name);
+		if (orm === void 0) throw new Error(`OrmRegistry: no ORM registered under "${name}".`);
+		return orm;
+	}
+	/**
+	* Indique si un ORM est enregistré sous ce nom.
+	*
+	* @param name - clé logique de l'ORM.
+	*/
+	has(name) {
+		return this.#orms?.has(name) ?? false;
+	}
+	/**
+	* Liste les noms des ORM enregistrés.
+	*
+	* @returns tableau des clés (vide si aucun ORM enregistré).
+	*/
+	list() {
+		return this.#orms === null ? [] : [...this.#orms.keys()];
+	}
+	/**
+	* Retire un ORM du registre (utile au teardown des tests / hot-reload).
+	*
+	* @param name - clé logique de l'ORM.
+	* @returns `true` si un ORM a été retiré, `false` sinon.
+	*/
+	unregister(name) {
+		return this.#orms?.delete(name) ?? false;
+	}
+};
+/**
+* Singleton process-wide partagé par tous les drivers et consommateurs ORM.
+*
+* Les modules ORM s'enregistrent ici ; la classe {@link OrmRegistry} reste
+* instanciable séparément pour des registres isolés (tests).
+*/
+const ormRegistry = new OrmRegistry();
+//#endregion
+export { OrmRegistry, ormRegistry };

package/dist/nodefony/src/QueryFlowMonitor.js

@@ -0,0 +1,128 @@
+//#region nodefony/src/QueryFlowMonitor.ts
+/** Taille max du ring de requêtes lentes (borne mémoire). */
+const MAX_SLOW = 20;
+/** Facteur de lissage EWMA (0–1) : plus haut = suit plus vite les variations. */
+const EWMA_ALPHA = .2;
+/** Seuil « lent » par défaut (ms) — au-delà, la requête est capturée. */
+const DEFAULT_SLOW_MS = 50;
+/** Flux neutre d'un connecteur jamais observé (réutilisé, jamais muté). */
+const EMPTY_FLOW = {
+	total: 0,
+	avgMs: null,
+	ewmaMs: null,
+	lastMs: null,
+	maxMs: 0,
+	slowTotal: 0,
+	slow: []
+};
+/**
+* **QueryFlowMonitor** — sonde de **débit ORM** per-instance (process-local),
+* agrégée et **indépendante de l'ALS** : compte les requêtes, suit leur latence
+* (moyenne + EWMA) et capture les plus lentes, pour le panneau Supervision
+* (« contrôle total » des ORM, patron sondes+hub).
+*
+* Distinct du **profiler par-requête** (debug bar, buffer de scope ALS, dev-only,
+* coût nul hors requête tracée) : ce moniteur observe le débit **global** et doit
+* donc compter en continu → il est **gaté** par {@link enabled} (OFF par défaut)
+* pour rester **coût nul en production** et ne pas pénaliser les bancs de charge
+* (qui instancient les adapters hors kernel → `enabled` reste à `false`). Le
+* module driver l'active au boot en environnement non-prod.
+*
+* Perf (règle ABSOLUE) :
+*  - structure lazy (`Map` allouée au 1ᵉʳ enregistrement, ring `slow` au 1ᵉʳ lent) ;
+*  - le hot path n'alloue rien hors cas lent et n'appelle **jamais** `toSQL()`
+*    (l'appelant ne capture le SQL que sur le chemin lent, rare) ;
+*  - le débit/s n'est pas calculé ici (dérivé du delta de `total` à la lecture)
+*    → 0 état mutable côté lecture, 0 ring de timestamps sous charge.
+*
+* Cloud-native : per-instance ; la vue multi-pod relève de l'agrégation
+* (Prometheus / fan-out Redis P13), pas de cette classe. Reset au restart.
+*/
+var QueryFlowMonitor = class {
+	/** Sonde active ? OFF par défaut → coût nul tant que le driver ne l'active pas. */
+	enabled = false;
+	/** Seuil « lent » (ms) — modifiable par le driver/config. */
+	slowMs = DEFAULT_SLOW_MS;
+	/** `null` tant qu'aucune requête n'a été enregistrée (lazy). */
+	#stats = null;
+	/** Active/désactive la sonde (appelé au boot du module driver selon l'env). */
+	setEnabled(on) {
+		this.enabled = on;
+	}
+	/** Crée/retourne les stats mutables d'un connecteur (alloue à la demande). */
+	#ensure(connector) {
+		if (this.#stats === null) this.#stats = /* @__PURE__ */ new Map();
+		let s = this.#stats.get(connector);
+		if (s === void 0) {
+			s = {
+				total: 0,
+				sumMs: 0,
+				ewmaMs: null,
+				lastMs: null,
+				maxMs: 0,
+				slowTotal: 0,
+				slow: null
+			};
+			this.#stats.set(connector, s);
+		}
+		return s;
+	}
+	/**
+	* Enregistre une requête mesurée. À n'appeler **que** si {@link enabled} (le
+	* tap appelant teste le drapeau pour éviter tout coût quand la sonde est OFF).
+	*
+	* @param connector - clé du connecteur ORM (registre).
+	* @param durationMs - durée de la requête (ms).
+	* @param sql - SQL paramétré+redacté, fourni **uniquement** si la requête est
+	*   lente (l'appelant n'extrait le texte que sur le chemin lent — rare).
+	*/
+	record(connector, durationMs, sql) {
+		const s = this.#ensure(connector);
+		s.total += 1;
+		s.sumMs += durationMs;
+		s.lastMs = durationMs;
+		if (durationMs > s.maxMs) s.maxMs = durationMs;
+		s.ewmaMs = s.ewmaMs === null ? durationMs : EWMA_ALPHA * durationMs + .8 * s.ewmaMs;
+		if (durationMs >= this.slowMs) {
+			s.slowTotal += 1;
+			if (s.slow === null) s.slow = [];
+			s.slow.unshift({
+				ts: Date.now(),
+				durationMs,
+				connector,
+				sql
+			});
+			if (s.slow.length > MAX_SLOW) s.slow.length = MAX_SLOW;
+		}
+	}
+	/**
+	* Vue figée du flux d'un connecteur (ou flux neutre si jamais observé).
+	*
+	* @param connector - clé du connecteur ORM.
+	* @param vendor - vendor de l'adapter (dérivé par l'appelant).
+	*/
+	snapshot(connector, vendor) {
+		const s = this.#stats?.get(connector);
+		if (s === void 0) return {
+			connector,
+			vendor,
+			...EMPTY_FLOW
+		};
+		const round = (v) => Math.round(v * 100) / 100;
+		return {
+			connector,
+			vendor,
+			total: s.total,
+			avgMs: s.total ? round(s.sumMs / s.total) : null,
+			ewmaMs: s.ewmaMs === null ? null : round(s.ewmaMs),
+			lastMs: s.lastMs === null ? null : round(s.lastMs),
+			maxMs: round(s.maxMs),
+			slowTotal: s.slowTotal,
+			slow: s.slow ?? []
+		};
+	}
+};
+/** Singleton process-wide de la sonde de flux ORM. */
+const queryFlowMonitor = new QueryFlowMonitor();
+//#endregion
+export { queryFlowMonitor };