@nodefony/orm-core 10.0.0-alpha.1

package/dist/nodefony/src/readOptions.js

@@ -0,0 +1,52 @@
+import { InvalidOrderOption } from "./errors.js";
+//#region nodefony/src/readOptions.ts
+/**
+* Décrit la FORME d'une valeur reçue, sans jamais en révéler le contenu.
+*
+* Le message d'erreur doit aider à corriger un appel, pas recopier une donnée
+* applicative dans un journal.
+*
+* @param value - valeur observée.
+* @returns une description courte du type (`an object`, `a string`, `null`…).
+*/
+const describeShape = (value) => {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	const t = typeof value;
+	return t === "object" ? "an object" : `a ${t}`;
+};
+/**
+* Vérifie que l'option de lecture `order` respecte le contrat portable
+* `Array<[string, "ASC" | "DESC"]>`, ou lève {@link InvalidOrderOption}.
+*
+* Source de vérité **unique** partagée par tous les adapters : chacun l'appelle une
+* fois, en amont de la construction de sa requête, plutôt que de retester la forme à
+* chaque endroit qui pose un tri. Sans elle, un `order` mal formé était sauté en
+* silence (le test historique `options?.order?.length` est faux pour un objet) et la
+* requête partait sans `ORDER BY`.
+*
+* Absence de tri — `undefined`, `null`, ou tableau vide — est acceptée : rien n'y est
+* exprimé qui puisse être trahi. Seule une TENTATIVE de tri mal formée est refusée.
+*
+* Coût : sortie immédiate dans le cas dominant (`undefined`), aucune allocation sur le
+* chemin nominal — la description n'est construite qu'au moment de lever.
+*
+* @param order - valeur de `options.order` telle que reçue de l'appelant.
+* @param entity - nom logique de l'entité ciblée (diagnostic).
+* @throws InvalidOrderOption si `order` est présent et n'est pas un tableau de couples valides.
+*/
+function assertOrderOption(order, entity) {
+	if (order === void 0 || order === null) return;
+	if (!Array.isArray(order)) throw new InvalidOrderOption(entity, describeShape(order));
+	for (let i = 0; i < order.length; i++) {
+		const pair = order[i];
+		if (!Array.isArray(pair) || pair.length !== 2) throw new InvalidOrderOption(entity, `pair #${i} = ${describeShape(pair)}${Array.isArray(pair) ? ` of length ${pair.length}` : ""}`);
+		if (typeof pair[0] !== "string") throw new InvalidOrderOption(entity, `pair #${i} field = ${describeShape(pair[0])}`);
+		if (pair[1] !== "ASC" && pair[1] !== "DESC") {
+			const got = typeof pair[1] === "string" ? `"${pair[1]}"` : describeShape(pair[1]);
+			throw new InvalidOrderOption(entity, `pair #${i} direction = ${got} (expected exactly "ASC" or "DESC")`);
+		}
+	}
+}
+//#endregion
+export { assertOrderOption };

package/dist/nodefony/src/serviceWiring.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@nodefony/orm-core` — fondation multi-ORM de Nodefony.
+ *
+ * Expose les contrats abstraits (`IOrm`, `IEntity`, `IRepository`,
+ * `ITransaction`) consommés par les adapters (`@nodefony/mongoose`,
+ * `@nodefony/drizzle`...). Lib pure : aucun runtime
+ * Module, pas d'enregistrement dans `@modules()`. Les drivers concrets sont les
+ * Modules ; ils s'enregistrent eux-mêmes dans le `OrmRegistry` à leur boot.
+ */
+export type { IOrm, IEntity, IEntityRelation, IRepository, OrmCriteria, Criteria, FieldCriteria, FieldOperators, UpdateData, UpdateOperators, RepositoryReadOptions, ITransaction, IPage, IPageQuery, PageQuery, } from "./nodefony/interfaces/index.js";
+export { OPERATOR_KEYS, isFieldOperators, searchCriteria, LIKE_ESCAPE_CHAR, escapeLikeTerm, likePatternToRegExp, } from "./nodefony/src/criteria.js";
+export type { OperatorKey } from "./nodefony/src/criteria.js";
+export { UPDATE_OPERATOR_KEYS, isUpdateOperators, } from "./nodefony/src/criteria.js";
+export type { UpdateOperatorKey } from "./nodefony/src/criteria.js";
+export { UnknownCriteriaField, InvalidOrderOption, } from "./nodefony/src/errors.js";
+export { assertOrderOption } from "./nodefony/src/readOptions.js";
+export { OrmRegistry, ormRegistry } from "./nodefony/src/OrmRegistry.js";
+export { EntityRegistry, entityRegistry } from "./nodefony/src/EntityRegistry.js";
+export { Orm } from "./nodefony/src/Orm.js";
+export { Entity } from "./nodefony/src/Entity.js";
+export { AbstractCrudService } from "./nodefony/src/AbstractCrudService.js";
+export type { ServiceWiring } from "./nodefony/src/serviceWiring.js";
+export { paginate } from "./nodefony/src/paginate.js";
+export { buildOrmGraph, buildConnectionHealth, buildOrmFlow, toDbml, toJsonSchema, createOrmAdminApi, registerOrmAdminApi, } from "./nodefony/src/OrmAdminApi.js";
+export { queryFlowMonitor } from "./nodefony/src/QueryFlowMonitor.js";
+export { connectionMonitor } from "./nodefony/src/ConnectionMonitor.js";
+export { buildOrmLeanHealth } from "./nodefony/src/buildOrmLeanHealth.js";
+export { wireOrmAdminPlane, resolveOrmFlowEnabled, reportOrmBootLines, } from "./nodefony/src/ormWiring.js";
+export type { ISlowQuery, IQueryFlow, IOrmFlowReport, } from "./nodefony/interfaces/IOrmFlow.js";
+export type { IColumnInfo, IConnectionInfo, IRelationInfo, IEntityGraphNode, IOrmSummary, IOrmGraph, IConnectionError, IConnectionHealth, } from "./nodefony/interfaces/IOrmGraph.js";
+export type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe, IOrmProbe, } from "./nodefony/interfaces/IOrmProbe.js";
+export type { IOrmMigrationAction, IOrmMigrationEntry, IOrmMigrationSource, IOrmMigrationStatus, IOrmMigrationFailure, IOrmMigrationReply, IOrmPendingMigration, IOrmMigrationPlan, IOrmMigrationPlanReply, IOrmMigrationApplied, IOrmMigrationApplyReply, } from "./nodefony/interfaces/IOrmMigrations.js";
+export { isMigrationFailure } from "./nodefony/interfaces/IOrmMigrations.js";
+export { entity, entities, DEFAULT_CONNECTOR, repository, } from "./nodefony/src/decorators/index.js";
+export { defineEntity } from "./nodefony/src/defineEntity.js";
+export type { IEntityDefinition } from "./nodefony/src/defineEntity.js";
+export type { EntitiesOptions } from "./nodefony/src/decorators/index.js";
+export { getEntityMeta, hasEntityMeta, getRepositoryMeta, hasRepositoryMeta, } from "./nodefony/src/decorators/index.js";
+export type { EntityOptions, RepositoryOptions, EntityMetadata, RepositoryMetadata, DecoratedClass, } from "./nodefony/src/decorators/index.js";

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

@@ -0,0 +1,65 @@
+/**
+ * Relation déclarative entre deux entités, indépendante du driver ORM.
+ */
+export interface IEntityRelation {
+    /** Cardinalité de la relation. */
+    readonly type: "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
+    /** Nom logique de l'entité cible (clé de lookup dans le registre). */
+    readonly target: string;
+    /** Champ portant la relation côté entité courante. */
+    readonly field: string;
+    /**
+     * Clé étrangère explicite. Si omise, l'adapter en dérive une déterministe
+     * (camelCase `<entité>Id`) — évite la divergence avec le défaut du driver
+     * (certains ORM génèrent du PascalCase `UserId`).
+     */
+    readonly foreignKey?: string;
+}
+/**
+ * Description d'une entité enregistrée dans le registre cross-ORM.
+ *
+ * Une même entité logique (ex. `User`) peut exister sur plusieurs connecteurs :
+ * `connector` désigne la connexion nommée cible (celle déclarée dans
+ * `connectors: { … }` de la config) et `schema`/`model` portent la définition
+ * propre au driver (schéma Mongoose, schéma Drizzle...). `model` n'est
+ * disponible qu'après connexion de l'ORM (compilation du modèle).
+ *
+ * Le mot désigne le **rôle** : une entité est liée à une *connexion*, jamais à
+ * un ORM — l'ORM (Drizzle, Mongoose) est le *driver* qui sert cette connexion.
+ *
+ * @typeParam S - type du schéma natif du driver.
+ * @typeParam M - type du modèle compilé natif du driver.
+ */
+export interface IEntity<S = unknown, M = unknown> {
+    /** Nom logique de l'entité (clé de lookup, ex. `"User"`). */
+    readonly name: string;
+    /** Connexion nommée cible, telle que déclarée en config (ex. `"default"`). */
+    readonly connector: string;
+    /**
+     * Module Nodefony propriétaire de l'entité (ex. `"user"`, `"test"`).
+     * **Optionnel** : sert au regroupement dans le graphe canonique / ERD Studio.
+     * Non renseigné → entité non rattachée (groupe « — » côté UI).
+     */
+    readonly module?: string;
+    /**
+     * **Classification** de l'entité (ex. domaine fonctionnel `"facturation"`,
+     * `"comptabilité"`) — axe de regroupement **distinct** du `module`
+     * (propriété/qui enregistre). Indispensable pour rendre lisible une **grosse
+     * base** (centaines de tables d'un même module) : l'ERD groupe/filtre par
+     * `domain`. **Optionnel** ; non renseigné → retombe sur `module`.
+     */
+    readonly domain?: string;
+    /** Définition de schéma propre au driver (forme libre). */
+    readonly schema: S;
+    /** Modèle compilé natif, renseigné après connexion de l'ORM. */
+    model?: M;
+    /**
+     * Active la gestion **automatique** des horodatages `createdAt`/`updatedAt` par
+     * l'adapter qui la supporte nativement (Mongoose `timestamps: true`). Les ORM
+     * schema-as-code (Drizzle) les expriment en colonnes → ce flag y est sans effet.
+     * **Optionnel**, défaut `false`.
+     */
+    readonly timestamps?: boolean;
+    /** Relations déclarées vers d'autres entités (par nom logique). */
+    readonly relations?: ReadonlyArray<IEntityRelation>;
+}

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

@@ -0,0 +1,136 @@
+import type { IRepository } from "./IRepository.js";
+import type { ITransaction } from "./ITransaction.js";
+import type { IColumnInfo, IConnectionInfo } from "./IOrmGraph.js";
+import type { IOrmProbe } from "./IOrmProbe.js";
+import type { IOrmMigrationApplyReply, IOrmMigrationPlanReply, IOrmMigrationReply } from "./IOrmMigrations.js";
+/**
+ * Contrat d'une instance ORM gérée par le framework (une par connexion logique).
+ *
+ * Implémenté par chaque adapter (`@nodefony/mongoose`, `@nodefony/drizzle`...) et enregistré dans `OrmRegistry` sous un nom unique
+ * (ex. `"db_principale"`, `"db_logs"`) pour le support multi-ORM simultané.
+ */
+export interface IOrm {
+    /** Nom unique de l'instance dans le registre (clé `OrmRegistry.get`). */
+    readonly name: string;
+    /** Établit la connexion sous-jacente et compile les entités enregistrées. */
+    connect(): Promise<void>;
+    /** Ferme proprement la connexion et libère le pool. */
+    disconnect(): Promise<void>;
+    /** Indique si la connexion est actuellement active. */
+    isConnected(): boolean;
+    /**
+     * Retourne le repository typé d'une entité enregistrée.
+     *
+     * @param name - nom logique de l'entité (ex. `"User"`).
+     * @typeParam T - type de l'entité gérée.
+     * @returns le repository CRUD de l'entité.
+     * @throws si aucune entité de ce nom n'est enregistrée pour cet ORM.
+     */
+    getRepository<T = unknown>(name: string): IRepository<T>;
+    /**
+     * Exécute un travail dans une transaction : commit si résolu, rollback si rejeté.
+     *
+     * @param work - callback recevant la transaction active.
+     * @typeParam R - type du résultat retourné par le travail.
+     */
+    transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>;
+    /**
+     * Expose la connexion native du driver (trappe SQL/commandes brutes).
+     *
+     * Anti-blocage indispensable : autorise une requête brute non couverte par
+     * l'abstraction (tag `sql` Drizzle, `connection` Mongoose, etc.) — typiquement
+     * une projection de colonnes, une CTE ou une agrégation.
+     *
+     * **Passer le type de l'adapter, jamais rien.** Le paramètre retombe sur
+     * `unknown` s'il est omis, et la seule issue devient alors un `as any` : c'est
+     * le contraire de ce que cette trappe cherche à offrir. Le type vient de
+     * l'adapter employé — `DrizzleDb` exporté par `@nodefony/drizzle`,
+     * `Connection` du paquet `mongoose` pour `@nodefony/mongoose` :
+     *
+     * ```ts
+     * import type { DrizzleDb } from "@nodefony/drizzle";
+     * const db = orm.getNativeConnection<DrizzleDb>();
+     * ```
+     *
+     * @typeParam C - type natif attendu, exporté par l'adapter employé.
+     */
+    getNativeConnection<C = unknown>(): C;
+    /**
+     * Décrit les colonnes normalisées d'une entité pour le graphe canonique
+     * (data plane ORM / ERD / contexte IA). **Optionnel** : un adapter qui ne
+     * l'implémente pas laisse le graphe sans colonnes (relations seules).
+     *
+     * @param name - nom logique de l'entité.
+     * @returns colonnes normalisées, ou `[]` si inconnu/non implémenté.
+     */
+    describeEntity?(name: string): IColumnInfo[];
+    /**
+     * Décrit la connexion sous-jacente (driver + cible lisible) pour le data plane
+     * ORM / dashboard. **Optionnel** : un adapter qui ne l'implémente pas laisse le
+     * connecteur sans détail de connexion. Ne DOIT jamais exposer de credential
+     * (mot de passe retiré de la cible).
+     *
+     * @returns infos de connexion, ou `undefined` si non implémenté.
+     */
+    describeConnection?(): IConnectionInfo;
+    /**
+     * Ping bas-coût de la connexion (round-trip réel vers la base) pour le
+     * diagnostic du data plane. **Optionnel** : un adapter qui ne l'implémente pas
+     * laisse le diagnostic mesurer une latence `null` (état dérivé d'`isConnected`).
+     * SQL → `SELECT 1` ; Mongo → `admin().ping`. Doit **rejeter** si la base ne
+     * répond pas (la latence et l'erreur alimentent le moniteur de connexion).
+     *
+     * @throws si la base est injoignable.
+     */
+    ping?(): Promise<void>;
+    /**
+     * Sonde profonde driver-spécifique (stockage, pool…) pour le contrôle total
+     * des ORM via le hub temps réel. **Optionnel** : un adapter qui ne l'implémente
+     * pas ne rapporte que les métriques génériques (latence, cycle de vie).
+     * Best-effort : ne DOIT jamais throw (retourner un objet partiel/vide).
+     *
+     * @returns métriques driver, ou objet vide si rien à rapporter.
+     */
+    probe?(): Promise<IOrmProbe>;
+    /**
+     * État des migrations de ce connecteur — **capacité optionnelle**, et son
+     * ABSENCE est une réponse.
+     *
+     * Un ORM qui ne l'implémente pas ne porte pas de migrations par fichiers
+     * versionnés : le plan d'administration le DIT en le nommant, plutôt que de
+     * rendre une page vide. Les autres bases résorbent l'écart entre le code et
+     * le schéma autrement — la question est la même, la réponse n'est pas la
+     * même.
+     *
+     * ⚠️ **Lecture seule, et sans privilège emprunté** : cette méthode ne doit
+     * rien appliquer, et ne doit pas emprunter le compte réservé au travail de
+     * migration. Un serveur qui répond à une requête d'administration n'a aucune
+     * raison de détenir le droit de modifier un schéma.
+     *
+     * @returns l'état, ou l'empêchement qui explique pourquoi il n'y en a pas.
+     */
+    migrationStatus?(): Promise<IOrmMigrationReply>;
+    /**
+     * Ce qui S'APPLIQUERAIT, avec son SQL — **capacité optionnelle**, lecture
+     * seule.
+     *
+     * Sert la confirmation d'un geste d'application : on ne confirme pas une
+     * modification de schéma sur une promesse, on la confirme sur ce qu'elle va
+     * exécuter.
+     *
+     * @returns le plan, ou l'empêchement.
+     */
+    migrationPlan?(): Promise<IOrmMigrationPlanReply>;
+    /**
+     * Applique les migrations en attente — **capacité optionnelle, et ÉCRIVANTE**.
+     *
+     * ⚠️ Réservée au DÉVELOPPEMENT par l'implémentation, qui doit refuser
+     * ailleurs en le disant. Ce n'est pas une précaution d'interface : en
+     * production, les migrations s'appliquent dans un travail d'orchestrateur qui
+     * se termine AVANT que le premier nouvel exemplaire ne démarre — pas au clic
+     * de quelqu'un qui regarde une console pendant que le trafic passe.
+     *
+     * @returns ce qui a été appliqué, ou l'empêchement.
+     */
+    applyMigrations?(): Promise<IOrmMigrationApplyReply>;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Sonde **flux ORM** — débit de requêtes vers la base, agrégé process-wide et
+ * **indépendant de l'ALS** (≠ profiler par-requête de la debug bar).
+ *
+ * Observe « combien de requêtes/s, à quelle latence, et lesquelles sont lentes »
+ * pour le panneau Supervision Studio (patron sondes+hub). Alimenté par le même
+ * tap que le profiler ({@link IOrm} adapters), mais via un compteur global
+ * ({@link QueryFlowMonitor}) au lieu du buffer de scope — donc visible sans
+ * requête HTTP en cours.
+ *
+ * Perf : le débit instantané (queries/s) n'est **pas** stocké ici ; il est dérivé
+ * côté consommateur à partir du delta de {@link IQueryFlow.total} entre deux
+ * lectures (même technique que le CPU%) → 0 état mutable à la lecture, robuste
+ * même quand l'event-loop dérape (le delta couvre alors une fenêtre plus large).
+ */
+/**
+ * Une requête « lente » capturée (au-delà du seuil). Le SQL est **paramétré**
+ * (placeholders, jamais les valeurs) et redacté → 0 credential. Capturé
+ * uniquement sur le chemin lent (rare) pour ne rien coûter au cas nominal.
+ */
+export interface ISlowQuery {
+    /** Horodatage de la requête (ms epoch). */
+    ts: number;
+    /** Durée mesurée (ms). */
+    durationMs: number;
+    /** Connecteur ORM (clé du registre). */
+    connector: string;
+    /** SQL paramétré et redacté (absent si l'adapter ne sait pas l'extraire). */
+    sql?: string;
+}
+/**
+ * Compteurs de flux d'UN connecteur ORM. Cumuls depuis le boot (le débit/s se
+ * dérive du delta de `total`). Latence en deux vues : moyenne sur la vie du
+ * process (`avgMs`) et EWMA lissée (`ewmaMs`, suit les variations récentes).
+ */
+export interface IQueryFlow {
+    /** Connecteur ORM (clé du registre, ex. `"default"`). */
+    connector: string;
+    /** Vendor de l'adapter (`drizzle`, `mongoose`), `""` si inconnu. */
+    vendor: string;
+    /** Requêtes mesurées depuis le boot (le débit/s = Δtotal / Δts côté lecteur). */
+    total: number;
+    /** Latence moyenne sur la vie du process (ms), `null` si aucune requête. */
+    avgMs: number | null;
+    /** Latence EWMA lissée (ms) — suit les variations récentes, `null` si aucune. */
+    ewmaMs: number | null;
+    /** Dernière latence mesurée (ms), `null` si aucune. */
+    lastMs: number | null;
+    /** Pire latence observée (ms), `0` si aucune. */
+    maxMs: number;
+    /** Requêtes classées lentes depuis le boot (≥ seuil). */
+    slowTotal: number;
+    /** Ring borné des requêtes lentes récentes (la plus récente en tête). */
+    slow: ISlowQuery[];
+}
+/**
+ * Rapport de flux complet — un par instance (cloud-native : per-process). Le
+ * débit/s n'y figure pas (dérivé du delta de `total` entre deux `ts`).
+ */
+export interface IOrmFlowReport {
+    /** La sonde est-elle active ? `false` en production par défaut (coût nul). */
+    enabled: boolean;
+    /** Horodatage du rapport (ms epoch) — sert au calcul du débit (Δts). */
+    ts: number;
+    /** Identifiant de l'instance (pid, ou `NF_INSTANCE_ID`). */
+    instanceId: string;
+    /** Seuil « lent » courant (ms) — au-delà, la requête est capturée. */
+    slowMs: number;
+    /** Flux par connecteur ORM enregistré. */
+    connectors: IQueryFlow[];
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Représentation **canonique et sérialisable** du modèle de données multi-ORM.
+ *
+ * C'est la pièce maîtresse « IA-first » du data plane ORM : un graphe normalisé
+ * (ORM-agnostique) qui sert à la fois :
+ *  - la **visualisation** (ERD React Flow côté Studio) ;
+ *  - l'**IA** (contexte d'un agent : text-to-SQL, RAG schéma-aware) ;
+ *  - l'**interop** (export DBML / JSON Schema / SQL DDL).
+ *
+ * Une source, plusieurs consommateurs. Le diagramme n'est qu'une projection.
+ */
+import type { ILatencyWindow, IOrmStorageProbe, IOrmPoolProbe } from "./IOrmProbe.js";
+/** Colonne/champ normalisé d'une entité (extrait via {@link IOrm.describeEntity}). */
+export interface IColumnInfo {
+    /** Nom de la colonne. */
+    name: string;
+    /** Type natif tel que rapporté par le driver (ex. `text`, `integer`, `String`). */
+    type: string;
+    /** `true` si clé primaire. */
+    primaryKey: boolean;
+    /** `true` si la colonne accepte `NULL`. */
+    nullable: boolean;
+    /** `true` si contrainte d'unicité. */
+    unique: boolean;
+}
+/** Relation projetée pour le graphe (sous-ensemble sérialisable de `IEntityRelation`). */
+export interface IRelationInfo {
+    /** Cardinalité. */
+    type: "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
+    /** Entité cible (nom logique). */
+    target: string;
+    /** Champ portant la relation côté entité courante. */
+    field: string;
+    /** Clé étrangère (explicite ou dérivée déterministe). */
+    foreignKey?: string;
+}
+/** Nœud du graphe : une entité avec ses colonnes et ses relations. */
+export interface IEntityGraphNode {
+    /** Nom logique de l'entité. */
+    name: string;
+    /** Connexion nommée qui porte l'entité (clé de `connectors` en config). */
+    connector: string;
+    /**
+     * Module Nodefony propriétaire (regroupement ERD), `""` si non rattaché.
+     */
+    module: string;
+    /**
+     * Classification (domaine fonctionnel) — axe de regroupement ERD distinct du
+     * `module`, `""` si non renseigné. Rend une grosse base navigable.
+     */
+    domain: string;
+    /** Colonnes normalisées (vide si l'adapter n'implémente pas `describeEntity`). */
+    columns: IColumnInfo[];
+    /** Relations déclarées. */
+    relations: IRelationInfo[];
+}
+/** Connexion sous-jacente d'un ORM (extrait via {@link IOrm.describeConnection}). */
+export interface IConnectionInfo {
+    /**
+     * Base/driver sous-jacent en minuscules (`sqlite`, `postgres`, `mysql`,
+     * `mariadb`, `mongodb`…) — sert à choisir le logo et qualifier le connecteur.
+     */
+    driver: string;
+    /**
+     * Cible lisible : chemin du fichier (SQLite, **relatif** — jamais d'absolu),
+     * `host:port/base` (serveur) ou URI redactée. **Jamais de credential** (mot de
+     * passe retiré côté adapter).
+     */
+    target?: string;
+    /** Version du moteur/base (ex. SQLite `3.45.1`), si l'adapter peut l'obtenir. */
+    version?: string;
+    /** Version de la lib ORM elle-même (ex. drizzle-orm `0.44.x`), si connue. */
+    ormVersion?: string;
+}
+/** Résumé d'un ORM/connecteur enregistré. */
+export interface IOrmSummary {
+    /** Clé du connecteur dans le `OrmRegistry`. */
+    name: string;
+    /**
+     * Vendor de l'adapter en minuscules (`drizzle`, `mongoose`…),
+     * dérivé du nom de classe. `""` si indéterminé. Dette : promouvoir en
+     * `IOrm.vendor` déclaré par chaque adapter (P7.1 industrialisation ORM).
+     */
+    vendor: string;
+    /** `true` si c'est le connecteur par défaut (`"default"`). */
+    default: boolean;
+    /** État de la connexion. */
+    connected: boolean;
+    /** Nombre d'entités rattachées à cet ORM. */
+    entityCount: number;
+    /** Connexion sous-jacente (driver + cible), si l'adapter l'expose. */
+    connection?: IConnectionInfo;
+}
+/** Erreur de connexion horodatée (message **redacté** — jamais de credential). */
+export interface IConnectionError {
+    /** Message d'erreur (driver), credential déjà retiré. */
+    message: string;
+    /** Horodatage epoch ms. */
+    ts: number;
+}
+/**
+ * Diagnostic d'un connecteur — réponse de `/nodefony/orm/api/connection/health`.
+ * Combine l'état figé ({@link IConnectionInfo}), les compteurs de cycle de vie
+ * (connexions, **reconnexions**, **erreurs**) du moniteur, et un **ping live**
+ * (round-trip réel mesuré à la requête).
+ */
+export interface IConnectionHealth {
+    /**
+     * Identité de l'**instance** (process) qui rapporte — cloud-native : le
+     * diagnostic est per-pod (pool DB local au process). Vue multi-pod = agrégation
+     * externe (Prometheus / fan-out Redis P13).
+     */
+    instanceId: string;
+    /** Clé du connecteur. */
+    name: string;
+    /** Vendor ORM (`drizzle`, `mongoose`…). */
+    vendor: string;
+    /** Base/driver (`sqlite`, `mongodb`…). */
+    driver: string;
+    /** Cible lisible (chemin relatif / host:port), jamais de credential. */
+    target?: string;
+    /** Version moteur. */
+    version?: string;
+    /** Version lib ORM. */
+    ormVersion?: string;
+    /** État courant (`isConnected`). */
+    connected: boolean;
+    /** Connecté depuis (epoch ms), `null` si jamais connecté. */
+    connectedSince: number | null;
+    /** Durée depuis la dernière connexion réussie (ms), `null` si jamais. */
+    uptimeMs: number | null;
+    /** Nombre total de connexions réussies. */
+    connectCount: number;
+    /** Reconnexions (connexions au-delà de la première). */
+    reconnectCount: number;
+    /** Nombre total d'erreurs enregistrées (connexion + ping). */
+    errorCount: number;
+    /** Dernière erreur, `null` si aucune. */
+    lastError: IConnectionError | null;
+    /** Erreurs récentes (ring borné, plus récentes d'abord). */
+    recentErrors: IConnectionError[];
+    /** Latence de la dernière connexion réussie (ms), `null` si inconnue. */
+    lastConnectMs: number | null;
+    /** Latence du ping live (ms), `null` si non pingable / déconnecté. */
+    pingMs: number | null;
+    /** `true` si le ping live a réussi. */
+    pingOk: boolean;
+    /** Message d'erreur du ping live, `null` si OK. */
+    pingError: string | null;
+    /** Fenêtre glissante de latence (min/moy/max sur les N derniers pings). */
+    latency: ILatencyWindow;
+    /** Sonde de stockage (driver), si l'adapter l'expose. */
+    storage?: IOrmStorageProbe;
+    /** Sonde de pool de connexions (driver), si l'adapter l'expose. */
+    pool?: IOrmPoolProbe;
+    /** Métriques driver libres (clé→valeur). */
+    extra?: Record<string, string | number | boolean>;
+}
+/** Graphe complet du modèle de données — réponse de `/nodefony/orm/api/graph`. */
+export interface IOrmGraph {
+    /** ORMs/connecteurs enregistrés. */
+    orms: IOrmSummary[];
+    /** Entités (colonnes + relations), éventuellement filtrées par ORM. */
+    entities: IEntityGraphNode[];
+}