@nodefony/orm-core 10.0.0-alpha.1

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

@@ -0,0 +1,158 @@
+import { Service } from "nodefony";
+import type { IRepository, Criteria, RepositoryReadOptions, IPage, PageQuery } from "../interfaces/index.js";
+import type { ServiceWiring } from "./serviceWiring.js";
+/**
+ * Service CRUD **générique** — socle réutilisable au-dessus d'un {@link IRepository}.
+ *
+ * Toute entité (User, Article, Room...) expose son CRUD « toujours de la même
+ * manière » en étendant cette classe : `class UserService extends
+ * AbstractCrudService<IUser, IUserRepository>`. Le service est la **source de
+ * vérité métier**, transport-agnostique : les adaptateurs (REST controller, WS
+ * RPC, resolver GraphQL, commande CLI) l'appellent sans dupliquer la logique.
+ *
+ * Étend {@link Service} (DI, Syslog, bus d'événements) → instancié **une seule
+ * fois** (singleton DI). C'est légitime car la classe est **stateless** : son
+ * état d'instance ne porte que des invariants partagés (le `repository` injecté).
+ * L'état par requête (utilisateur courant, tenant, transaction) vit dans le
+ * `Context`/ALS, **jamais** dans un champ du service.
+ *
+ * **Perf** : les lectures (`find`/`findOne`/`findById`/`count`) délèguent
+ * directement au repository — aucun hook ni event sur le chemin chaud. Les
+ * mutations (`create`/`update`/`delete`) passent par les hooks template-method et
+ * émettent un événement de cycle de vie (`onCreated`/`onUpdated`/`onDeleted`)
+ * consommable pour l'audit, le cache, ou Studio.
+ *
+ * @typeParam T - type de l'entité gérée.
+ * @typeParam R - type concret du repository (conserve les finders métier dans la
+ *   sous-classe, ex. `IUserRepository`). Défaut : `IRepository<T>`.
+ */
+export declare abstract class AbstractCrudService<T, R extends IRepository<T> = IRepository<T>> extends Service {
+    protected readonly repository: R;
+    /**
+     * @param name - identifiant logique du service (msgid des logs, clé d'abonnement events).
+     * @param repository - source de persistance injectée (DI).
+     * @param wiring - câblage Service ({@link ServiceWiring} : `container?`,
+     *   `notificationsCenter?`, `options?`) — quasi toujours omis (fourni par le container DI).
+     */
+    constructor(name: string, repository: R, ...wiring: ServiceWiring);
+    /**
+     * Liste les entités correspondant au critère (toutes si omis).
+     *
+     * @param criteria - filtre typé optionnel.
+     * @param options - eager-load / pagination / tri portables.
+     */
+    find(criteria?: Criteria<T>, options?: RepositoryReadOptions): Promise<T[]>;
+    /**
+     * Première entité correspondant au critère, ou `null`.
+     *
+     * @param criteria - filtre de sélection.
+     * @param options - eager-load portable.
+     */
+    findOne(criteria: Criteria<T>, options?: RepositoryReadOptions): Promise<T | null>;
+    /**
+     * Entité par clé primaire `id`, ou `null`.
+     *
+     * @remarks Suppose une PK nommée `id` (convention Nodefony : UUID `string`).
+     * Override dans la sous-classe si la PK diffère.
+     * @param id - identifiant primaire.
+     * @param options - eager-load portable.
+     */
+    findById(id: string, options?: RepositoryReadOptions): Promise<T | null>;
+    /**
+     * Compte les entités correspondant au critère (toutes si omis).
+     *
+     * @param criteria - filtre optionnel.
+     */
+    count(criteria?: Criteria<T>): Promise<number>;
+    /**
+     * Liste **une page** d'entités — pagination **native** (jamais matérialiser
+     * toute la collection). C'est la primitive à utiliser pour toute liste admin /
+     * data plane : elle ne charge qu'une page en mémoire, quelle que soit la taille
+     * de la table.
+     *
+     * @param page - requête de page ({@link PageQuery} : `limit` obligatoire,
+     *   `offset`/`order`/`criteria`/`withTotal` optionnels).
+     * @returns une {@link Page} : au plus `limit` items, `hasNext`, et `total` si demandé.
+     * @throws `PageQueryError` (`400`) si un `?q=` est reçu alors que
+     *   {@link AbstractCrudService.searchableFields} est vide.
+     */
+    findPage(page: PageQuery<T>): Promise<IPage<T>>;
+    /**
+     * Champs sur lesquels `?q=` cherche — **vide par défaut, donc `q` est refusé**.
+     *
+     * Un service CRUD générique ne peut pas deviner ce qui, dans une entité, se
+     * cherche : un titre oui, une clé étrangère ou un horodatage non. Le défaut
+     * vide n'est donc pas une lacune mais la seule réponse honnête — et il refuse
+     * plutôt qu'il n'ignore, sans quoi une recherche non honorée rendrait toute la
+     * table sous un `200`.
+     *
+     * L'activer tient en une ligne dans le service concret, et la recherche
+     * devient alors réelle de bout en bout (`?q=` → `LIKE` ancré, indexable) :
+     *
+     * ```ts
+     * protected override readonly searchableFields = ["title", "slug"] as const;
+     * ```
+     *
+     * ⚠️ Le déclarer ici ne suffit PAS à ouvrir la route : le contrat de page
+     * refuse `q` en amont tant que le point d'entrée HTTP ne passe pas
+     * `searchable: true` à `parsePageQuery`. Les deux se déclarent, pour la même
+     * raison — une capacité se constate à chaque étage qu'elle traverse.
+     */
+    protected readonly searchableFields: ReadonlyArray<keyof T & string>;
+    /**
+     * Crée une entité : `beforeCreate` → persistance → `afterCreate` → `onCreated`.
+     *
+     * @param data - champs de l'entité à créer.
+     * @returns l'entité persistée. Émet `onCreated`.
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * Met à jour **au plus une** entité : `beforeUpdate` → persistance atomique
+     * → `afterUpdate` → `onUpdated`.
+     *
+     * S'appuie sur {@link IRepository.updateOne} (atomique, `RETURNING` /
+     * `findOneAndUpdate`) : l'entité retournée reflète l'écriture, donc l'event
+     * `onUpdated` part de façon fiable même quand le critère porte sur un champ
+     * modifié (corrige le faux `null` de l'ancien `update` + relecture).
+     *
+     * `updateMany` (mise à jour en masse) n'est volontairement **pas** exposée
+     * ici : c'est une primitive de niveau repository (`IRepository.updateMany`) —
+     * on la remontera dans un service le jour où un usage métier la réclame.
+     *
+     * @param criteria - filtre de sélection (champ inconnu → `UnknownCriteriaField`).
+     * @param data - champs à modifier.
+     * @returns l'entité mise à jour, ou `null` si aucune ne correspond (pas d'event).
+     */
+    updateOne(criteria: Criteria<T>, data: Partial<T>): Promise<T | null>;
+    /**
+     * Supprime : `beforeDelete` → persistance → `afterDelete` → `onDeleted`.
+     *
+     * @param criteria - filtre de sélection.
+     * @returns le nombre d'entités supprimées. Émet `onDeleted` (criteria, count)
+     *   uniquement si au moins une ligne a été supprimée.
+     */
+    delete(criteria: Criteria<T>): Promise<number>;
+    /**
+     * Transforme/valide les données avant création (ex. hacher un mot de passe).
+     *
+     * @param data - données entrantes.
+     * @returns les données préparées à persister.
+     */
+    protected beforeCreate(data: Partial<T>): Partial<T> | Promise<Partial<T>>;
+    /** Effet de bord après création (ex. provisionner une ressource liée). */
+    protected afterCreate(_entity: T): void | Promise<void>;
+    /**
+     * Transforme/valide les données avant mise à jour.
+     *
+     * @param criteria - cible de la mise à jour.
+     * @param data - données entrantes.
+     * @returns les données préparées à persister.
+     */
+    protected beforeUpdate(_criteria: Criteria<T>, data: Partial<T>): Partial<T> | Promise<Partial<T>>;
+    /** Effet de bord après mise à jour. */
+    protected afterUpdate(_entity: T): void | Promise<void>;
+    /** Garde/validation avant suppression (ex. interdire la suppression du dernier admin). */
+    protected beforeDelete(_criteria: Criteria<T>): void | Promise<void>;
+    /** Effet de bord après suppression (ex. nettoyer un cache). */
+    protected afterDelete(_criteria: Criteria<T>, _removed: number): void | Promise<void>;
+}

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

@@ -0,0 +1,86 @@
+import type { IConnectionError } from "../interfaces/IOrmGraph.js";
+import type { ILatencyWindow } from "../interfaces/IOrmProbe.js";
+/** Vue figée des compteurs du moniteur pour un connecteur. */
+export interface IConnectionMonitorCore {
+    connectedSince: number | null;
+    uptimeMs: number | null;
+    connectCount: number;
+    reconnectCount: number;
+    /** Pertes de connexion constatées depuis le démarrage du process. */
+    lostCount: number;
+    errorCount: number;
+    lastConnectMs: number | null;
+    lastError: IConnectionError | null;
+    recentErrors: IConnectionError[];
+    latency: ILatencyWindow;
+}
+/**
+ * **ConnectionMonitor** — observabilité **per-instance** (process-local) du
+ * cycle de vie des connexions ORM : connexions, **reconnexions**, **erreurs**
+ * (connexion + ping).
+ *
+ * Alimenté par la template method {@link Orm.connect} (capture latence + erreur
+ * de connexion) et par le ping live de l'endpoint `connection/health`. Lecture
+ * via {@link snapshot} (data plane ORM / dashboard Studio).
+ *
+ * **Cloud-native** : l'état d'une connexion DB est local au process (pool par
+ * pod) → le moniteur est volontairement per-instance. La vue multi-pod relève
+ * de l'agrégation (Prometheus par pod / fan-out Redis P13), pas de cette classe.
+ *
+ * **Perf** : structure lazy (`Map` allouée au 1ᵉʳ enregistrement) ; ring
+ * d'erreurs alloué seulement au 1ᵉʳ incident ; aucun coût tant qu'aucun ORM ne
+ * se connecte ou n'échoue. Reset au restart (diagnostic, pas d'état durable).
+ */
+declare class ConnectionMonitor {
+    #private;
+    /**
+     * Enregistre une latence de ping live dans la fenêtre glissante (ring borné).
+     *
+     * @param name - clé du connecteur.
+     * @param ms - latence du ping (ms).
+     */
+    recordPing(name: string, ms: number): void;
+    /**
+     * Enregistre une connexion réussie + sa latence.
+     *
+     * Ne compte PAS une reconnexion : une reprise du driver ne repasse jamais
+     * par `Orm.connect()`, elle se signale par {@link ConnectionMonitor.recordReconnect}.
+     *
+     * @param name - clé du connecteur.
+     * @param latencyMs - durée de l'établissement (ms).
+     */
+    recordConnect(name: string, latencyMs: number): void;
+    /**
+     * Enregistre une **perte** de connexion constatée par l'adapter.
+     *
+     * `connectedSince` retombe à `null` : un uptime qui continue de croître
+     * pendant que le serveur est tombé est pire qu'absent — il se lit comme une
+     * preuve de bonne santé.
+     *
+     * @param name - clé du connecteur.
+     */
+    recordLost(name: string): void;
+    /**
+     * Enregistre une **reprise** de connexion constatée par l'adapter.
+     *
+     * @param name - clé du connecteur.
+     */
+    recordReconnect(name: string): void;
+    /**
+     * Enregistre une erreur (connexion échouée ou ping en échec).
+     *
+     * @param name - clé du connecteur.
+     * @param message - message d'erreur (credential déjà retiré par l'appelant).
+     */
+    recordError(name: string, message: string): void;
+    /**
+     * Vue figée des compteurs d'un connecteur (ou compteurs neutres si jamais
+     * observé).
+     *
+     * @param name - clé du connecteur.
+     */
+    snapshot(name: string): IConnectionMonitorCore;
+}
+/** Singleton process-wide du moniteur de connexions. */
+export declare const connectionMonitor: ConnectionMonitor;
+export {};

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

@@ -0,0 +1,44 @@
+import type { IEntity, IEntityRelation } from "../interfaces/index.js";
+/**
+ * Classe de base abstraite d'une entité, indépendante du driver ORM.
+ *
+ * Porte le contrat {@link IEntity} : nom logique, connecteur cible, schéma natif
+ * (calculé via {@link Entity.getSchema}), modèle compilé (post-connexion) et
+ * relations déclaratives. {@link Entity.register} insère l'entité dans le
+ * {@link entityRegistry} process-wide.
+ *
+ * **Pas d'auto-enregistrement dans le constructeur** : en TypeScript, le
+ * constructeur de la classe de base s'exécute AVANT les initialiseurs de champs
+ * de la sous-classe — `name`/`connector` seraient encore `undefined`. L'enregistrement
+ * automatique est donc porté par le décorateur `@entity` (P5.3), qui lit les
+ * métadonnées de classe ; en attendant, appeler explicitement
+ * {@link Entity.register} après instanciation.
+ *
+ * @typeParam S - type du schéma natif du driver.
+ * @typeParam M - type du modèle compilé natif du driver.
+ */
+export declare abstract class Entity<S = unknown, M = unknown> implements IEntity<S, M> {
+    /** Nom logique de l'entité (clé de lookup, ex. `"User"`). */
+    abstract readonly name: string;
+    /** Connexion nommée cible, telle que déclarée en config (clé du `ormRegistry`). */
+    abstract readonly connector: string;
+    /** Modèle compilé natif, renseigné après connexion de l'ORM. */
+    model?: M;
+    /** Relations déclarées vers d'autres entités (par nom logique). */
+    readonly relations?: ReadonlyArray<IEntityRelation>;
+    /**
+     * Construit la définition de schéma propre au driver.
+     *
+     * @returns le schéma natif (forme libre selon l'ORM).
+     */
+    abstract getSchema(): S;
+    /** Définition de schéma propre au driver (délègue à {@link Entity.getSchema}). */
+    get schema(): S;
+    /**
+     * Enregistre cette entité dans le {@link entityRegistry} process-wide.
+     *
+     * @returns `this` (chaînable).
+     * @throws si l'entité est déjà enregistrée sur le même connecteur.
+     */
+    register(): this;
+}

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

@@ -0,0 +1,60 @@
+import type { IEntity } from "../interfaces/index.js";
+/**
+ * Registre cross-ORM des entités, indexé par nom logique puis par connecteur.
+ *
+ * Une même entité logique (ex. `User`) peut exister sur plusieurs connexions :
+ * l'index interne est `entities[entityName][connectorName] = IEntity`. Le lookup
+ * {@link EntityRegistry.get} accepte un nom seul (résolu si l'entité n'existe
+ * que sur un connecteur) ou un couple nom + connecteur pour lever l'ambiguïté.
+ *
+ * Structure pure (`Object.create(null)`) et lazy : rien n'est alloué tant
+ * qu'aucune entité n'est enregistrée. Aucun coupling à `nodefony`.
+ */
+export declare class EntityRegistry {
+    #private;
+    /**
+     * Enregistre une entité pour son connecteur cible.
+     *
+     * @param entity - entité implémentant {@link IEntity} (utilise `name` + `connector`).
+     * @throws si cette entité est déjà enregistrée sur le même connecteur.
+     */
+    register(entity: IEntity): void;
+    /**
+     * Résout une entité par nom (et connecteur si plusieurs candidats).
+     *
+     * @param name - nom logique de l'entité (ex. `"User"`).
+     * @param connector - connecteur cible ; obligatoire si l'entité existe sur plusieurs.
+     * @returns l'entité correspondante.
+     * @throws si l'entité est inconnue, absente du connecteur demandé, ou ambiguë
+     *   (plusieurs connecteurs) sans `connector` précisé.
+     */
+    get(name: string, connector?: string): IEntity;
+    /**
+     * Indique si une entité (optionnellement sur un connecteur précis) est enregistrée.
+     *
+     * @param name - nom logique de l'entité.
+     * @param connector - connecteur cible facultatif.
+     */
+    has(name: string, connector?: string): boolean;
+    /**
+     * Liste toutes les entités enregistrées, tous connecteurs confondus.
+     *
+     * @returns tableau d'entités (vide si registre vide).
+     */
+    list(): IEntity[];
+    /**
+     * Retire une entité du registre (teardown tests / hot-reload).
+     *
+     * @param name - nom logique de l'entité.
+     * @param connector - si fourni, retire seulement cette variante ; sinon toutes.
+     * @returns `true` si quelque chose a été retiré, `false` sinon.
+     */
+    unregister(name: string, connector?: string): boolean;
+}
+/**
+ * Singleton process-wide partagé. Les entités s'y enregistrent (via le
+ * décorateur `entities([...])` posé sur le Module, ou {@link Entity.register}).
+ * La classe {@link EntityRegistry} reste instanciable pour des registres isolés
+ * (tests).
+ */
+export declare const entityRegistry: EntityRegistry;

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

@@ -0,0 +1,197 @@
+import { Service } from "nodefony";
+import type { Container, Event, DefaultOptionsService } from "nodefony";
+import type { IColumnInfo, IConnectionInfo, IOrm, IRepository, ITransaction } from "../interfaces/index.js";
+/**
+ * Classe de base abstraite de tout ORM Nodefony — câble {@link Service} (DI,
+ * Syslog, bus d'événements) et le contrat {@link IOrm}, et s'auto-enregistre
+ * dans le {@link ormRegistry} process-wide à la construction.
+ *
+ * Les drivers concrets (`@nodefony/mongoose`, `@nodefony/drizzle`...)
+ * implémentent les opérations bas niveau ({@link Orm.onConnect}, `disconnect`,
+ * `getRepository`, `transaction`, `getNativeConnection`). La connexion passe par
+ * la template method {@link Orm.connect} qui émet l'événement `onOrmReady` une
+ * fois le driver connecté — garantissant que tous les ORM signalent leur
+ * disponibilité de façon homogène (avant le `onReady` du Kernel).
+ *
+ * @typeParam — aucun ; les types natifs du driver transitent via les génériques
+ *   des méthodes ({@link IRepository}, {@link ITransaction}, native connection).
+ */
+export declare abstract class Orm extends Service implements IOrm {
+    #private;
+    /**
+     * État de vie de la connexion — source UNIQUE de `isConnected()`.
+     *
+     * `protected` et non `#privé` : `disconnect()` est implémenté par chaque
+     * adapter et doit pouvoir le remettre à `false`.
+     */
+    protected alive: boolean;
+    /**
+     * **Ce que cet adapter sait VRAIMENT de l'état de sa connexion** — déclaré,
+     * jamais supposé.
+     *
+     * `"events"` : le driver signale les pertes et les reprises, l'adapter les
+     * traduit ; `isConnected()` est un CONSTAT.
+     * `"assumed"` : rien ne signale quoi que ce soit (base embarquée, driver
+     * muet) ; `isConnected()` dit seulement « la connexion a été établie et
+     * n'a pas été fermée » — une supposition.
+     *
+     * **Le défaut est `"assumed"`, et il n'est pas abstrait — délibérément.**
+     * Le rendre obligatoire forcerait chaque adapter à répondre, mais casserait
+     * la compilation de tout adapter existant : ajouter un ORM deviendrait une
+     * rupture. Le défaut prudent protège aussi bien de l'oubli, parce qu'il dit
+     * la VÉRITÉ sur un adapter qui n'a rien câblé — il ne sait pas. Ce qu'il
+     * faut empêcher, ce n'est pas le silence : c'est qu'un silence se fasse
+     * passer pour un constat.
+     */
+    get liveness(): "events" | "assumed";
+    /**
+     * @param name - clé unique de l'ORM dans le {@link ormRegistry}.
+     * @param container - container DI hérité (Kernel) ou nouveau si omis.
+     * @param notificationsCenter - bus d'événements partagé, `false` pour aucun.
+     * @param options - options de service.
+     * @throws si un ORM du même `name` est déjà enregistré.
+     */
+    constructor(name: string, container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService);
+    /**
+     * Connecte le driver puis émet `onOrmReady`.
+     *
+     * Template method : ne pas surcharger — implémenter {@link Orm.onConnect}.
+     * Instrumente le {@link connectionMonitor} (latence + reconnexion en cas de
+     * succès, erreur de connexion en cas d'échec).
+     */
+    connect(): Promise<void>;
+    /**
+     * **Le driver a PERDU la connexion** — à appeler par l'adapter depuis
+     * l'événement natif de son driver (`pool.on("error")` côté `pg`,
+     * `connection.on("disconnected")` côté Mongoose…).
+     *
+     * Idempotent : un driver émet souvent plusieurs erreurs pour une seule
+     * coupure (une par connexion du pool). Seule la PREMIÈRE bascule l'état,
+     * compte l'incident et émet `onOrmLost` — sinon un pool de 10 connexions
+     * ferait dix fois le tour du framework pour un seul serveur tombé.
+     *
+     * @param reason - cause lisible, sans credential (elle est journalisée).
+     */
+    protected connectionLost(reason: string): void;
+    /**
+     * **Le driver a RÉTABLI la connexion** — à appeler par l'adapter depuis
+     * l'événement natif correspondant (`pool.on("connect")`, `reconnected`…).
+     *
+     * **Une reprise n'existe que s'il y a eu une perte.** `pg` émet `connect` et
+     * `acquire` à chaque client pris au pool, y compris quand rien n'est tombé,
+     * et y compris pendant l'établissement initial : sans cette condition, un
+     * pool qui grandit sous la charge — ou simplement une application qui
+     * démarre — compterait des reconnexions imaginaires.
+     */
+    protected connectionRestored(): void;
+    /**
+     * Période du battement de cœur, en millisecondes. `0` le désactive.
+     *
+     * **Pourquoi le framework doit fournir ça** : le driver MongoDB surveille ses
+     * serveurs en permanence (SDAM) et sait donc qu'une base est tombée même sans
+     * le moindre trafic. `pg` et `mysql2` n'ont RIEN de tel — ils n'apprennent
+     * l'état du serveur que par leurs requêtes. Mesuré : sur ces deux dialectes,
+     * une coupure survenue pendant qu'une requête était en vol, ou un serveur
+     * simplement GELÉ (qui ne ferme rien), n'émettent aucun événement : l'état
+     * restait « connecté » indéfiniment. Un battement comble cette asymétrie —
+     * il ne réinvente rien, il donne aux drivers muets ce que Mongo a déjà.
+     *
+     * Pourquoi pas une instrumentation des requêtes : son coût croît avec le
+     * trafic, pour une information qui ne change qu'aux rares instants de panne ;
+     * et il faudrait distinguer une erreur de connexion d'une contrainte violée.
+     * Ici le coût est CONSTANT et connu d'avance : une requête légère par période.
+     */
+    protected heartbeatMs: number;
+    /**
+     * Délai au-delà duquel un battement sans réponse vaut une PERTE.
+     *
+     * Sans lui, le battement ne sert à rien contre le cas qui l'a justifié :
+     * une base GELÉE ne ferme rien et ne répond pas, donc `ping()` PEND — et
+     * le battement pendait avec elle, indéfiniment, sans jamais conclure
+     * (mesuré : 30 s de gel, aucune détection). Une sonde doit avoir sa
+     * propre montre, sinon elle hérite de la panne qu'elle est censée voir.
+     */
+    protected heartbeatTimeoutMs: number;
+    /**
+     * Démarre le battement si l'adapter sait répondre à un `ping()` et que la
+     * période n'est pas nulle. Idempotent.
+     *
+     * La minuterie est `unref()` : elle ne doit JAMAIS retenir le process en vie
+     * — un banc, un script CLI ou un test qui se termine ne doit pas attendre le
+     * prochain battement pour rendre la main.
+     */
+    protected startHeartbeat(): void;
+    /** Arrête le battement et libère la minuterie. Idempotent. */
+    protected stopHeartbeat(): void;
+    /**
+     * **Bat MAINTENANT**, sans attendre la fin de la période.
+     *
+     * À appeler par un adapter dont le driver émet un signal SUSPECT mais pas
+     * concluant — typiquement la fermeture du socket d'une connexion du pool :
+     * elle arrive aussi bien pour un serveur tombé que pour une connexion
+     * inactive recyclée, et l'adapter ne peut pas les distinguer. Plutôt que de
+     * trancher à sa place — ce qui inscrirait de faux incidents à chaque
+     * recyclage — il délègue ici : le battement fait la seule chose qui tranche,
+     * une requête, et met l'état à jour selon la réponse.
+     *
+     * Sans cette porte, un dialecte muet reste marqué connecté jusqu'au battement
+     * suivant : 30 s par défaut, là où `pg` bascule en millisecondes. C'est une
+     * asymétrie de détection entre deux dialectes de production, pas un réglage.
+     *
+     * Ne coûte rien quand rien ne va mal : la garde `#beating` écarte les
+     * battements concurrents, donc un pool dont dix connexions tombent d'un coup
+     * ne sonde qu'une fois. Ne rétablit ni ne perd quoi que ce soit après un
+     * `disconnect()` — `#beat` y voit un arrêt volontaire et s'abstient.
+     */
+    protected beatNow(): void;
+    /**
+     * Indique si la connexion est active — **implémentation UNIQUE**, portée par
+     * la classe de base et non par chaque adapter.
+     *
+     * C'est délibéré : tant que chaque adapter portait son propre booléen posé à
+     * la connexion, aucun ne le remettait à `false` quand le serveur tombait —
+     * la santé ORM répondait « connecté » en pleine coupure. L'état vit ici, et
+     * il n'a que trois sources : `connect()`, `disconnect()`, et les deux
+     * signaux que l'adapter traduit depuis son driver.
+     */
+    isConnected(): boolean;
+    /**
+     * Établit la connexion native du driver (compilation des entités, pool...).
+     *
+     * Appelé par {@link Orm.connect} ; ne pas émettre `onOrmReady` ici.
+     */
+    protected abstract onConnect(): Promise<void>;
+    /** Ferme la connexion et libère le pool. */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Repository typé d'une entité enregistrée.
+     *
+     * @param name - nom logique de l'entité.
+     */
+    abstract getRepository<T = unknown>(name: string): IRepository<T>;
+    /**
+     * Exécute un travail transactionnel (commit si résolu, rollback si rejeté).
+     *
+     * @param work - callback recevant la transaction active.
+     */
+    abstract transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>;
+    /** Expose la connexion native du driver (trappe SQL/commandes brutes). */
+    abstract getNativeConnection<C = unknown>(): C;
+    /**
+     * Décrit les colonnes d'une entité pour le graphe canonique. Défaut : `[]`
+     * (relations seules dans l'ERD). Les adapters surchargent avec l'introspection
+     * native (Drizzle `getTableConfig`, Mongoose paths).
+     *
+     * @param _name - nom logique de l'entité.
+     * @returns colonnes normalisées.
+     */
+    describeEntity(_name: string): IColumnInfo[];
+    /**
+     * Décrit la connexion sous-jacente (driver + cible). Défaut : driver vide
+     * (inconnu). Les adapters surchargent (Drizzle → `sqlite` + fichier, etc.).
+     * Ne DOIT jamais exposer de credential.
+     *
+     * @returns infos de connexion (driver vide si non renseigné).
+     */
+    describeConnection(): IConnectionInfo;
+}

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

@@ -0,0 +1,84 @@
+import type { IAdminApi, IAdminRegistry } from "nodefony";
+import type { IConnectionHealth, IOrmGraph } from "../interfaces/IOrmGraph.js";
+import type { IOrmFlowReport } from "../interfaces/IOrmFlow.js";
+/** Construit le graphe canonique complet (optionnellement filtré par connecteur). */
+export declare function buildOrmGraph(connectorFilter?: string): IOrmGraph;
+/**
+ * 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.
+ */
+export declare function buildConnectionHealth(filter?: string): Promise<IConnectionHealth[]>;
+/**
+ * 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).
+ */
+export declare function buildOrmFlow(filter?: string): IOrmFlowReport;
+/**
+ * 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.
+ */
+export declare function toDbml(graph: IOrmGraph): string;
+/** Propriété d'un schéma JSON (scalaire, réf relation, ou tableau de réfs). */
+interface IJsonSchemaProperty {
+    type?: string;
+    format?: string;
+    $ref?: string;
+    items?: {
+        $ref: string;
+    };
+}
+/** Définition d'objet JSON Schema pour une entité. */
+interface IJsonSchemaObject {
+    type: "object";
+    title: string;
+    properties: Record<string, IJsonSchemaProperty>;
+    required?: string[];
+    additionalProperties: false;
+}
+/**
+ * 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é).
+ */
+export declare function toJsonSchema(graph: IOrmGraph): {
+    $schema: string;
+    $defs: Record<string, IJsonSchemaObject>;
+};
+/**
+ * Construit le producteur `IAdminApi` du data plane ORM.
+ *
+ * @returns le `IAdminApi` (namespace `"orm"`).
+ */
+export declare function createOrmAdminApi(): IAdminApi;
+/**
+ * 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")`).
+ */
+export declare function registerOrmAdminApi(registry: IAdminRegistry): void;
+export {};