@nodefony/orm-core 10.0.0-alpha.8 → 10.0.0-beta.1

package/dist/types/nodefony/src/decorators/entityDecorator.d.ts

@@ -21,7 +21,7 @@ export interface EntityOptions<S = unknown> {
      */
     domain?: string;
     /** Schéma natif du driver (schéma Mongoose, schéma Drizzle...). */
-    schema?: S;
+    schema?: S | undefined;
     /** Relations déclaratives vers d'autres entités. */
     relations?: ReadonlyArray<IEntityRelation>;
 }

package/dist/types/nodefony/src/decorators/metadataStore.d.ts

@@ -17,13 +17,13 @@ export interface EntityMetadata<S = unknown> {
     /** Connexion nommée cible (clé du `ormRegistry`). */
     readonly connector: string;
     /** Module Nodefony propriétaire (regroupement graphe/ERD), si fourni. */
-    readonly module?: string;
+    readonly module?: string | undefined;
     /** Classification (domaine fonctionnel), axe de regroupement distinct du module. */
-    readonly domain?: string;
+    readonly domain?: string | undefined;
     /** Schéma natif du driver (forme libre), si fourni au décorateur. */
-    readonly schema?: S;
+    readonly schema?: S | undefined;
     /** Relations déclaratives vers d'autres entités. */
-    readonly relations?: ReadonlyArray<IEntityRelation>;
+    readonly relations?: ReadonlyArray<IEntityRelation> | undefined;
     /** Constructeur décoré (pour introspection / résolution lazy par le driver). */
     readonly target: DecoratedClass;
 }
@@ -36,7 +36,7 @@ export interface RepositoryMetadata {
     /** Nom logique de l'entité gérée par ce repository. */
     readonly entity: string;
     /** Connecteur cible (lève l'ambiguïté si l'entité existe sur plusieurs connexions). */
-    readonly connector?: string;
+    readonly connector?: string | undefined;
     /** Constructeur décoré. */
     readonly target: DecoratedClass;
 }

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

@@ -60,3 +60,51 @@ export declare class InvalidOrderOption extends Error {
      */
     constructor(entity: string, received: string);
 }
+/**
+ * Levée quand une suppression viserait une entité encore RÉFÉRENCÉE par une
+ * relation obligatoire d'une autre entité.
+ *
+ * C'est le pendant, pour un moteur sans clé étrangère (MongoDB), du `restrict`
+ * que le SQL généré pose sur une colonne de référence obligatoire : le parent
+ * ne part pas tant qu'un enfant le désigne. Sans cette garde, la suppression
+ * passait et `?include=` rendait ensuite `null` à la place du parent — une
+ * application passée du SQL à MongoDB perdait en silence une garantie qu'elle
+ * croyait avoir.
+ *
+ * Erreur de DONNÉES : c'est la surface API qui la projette (le rendu d'erreur
+ * HTTP la reconnaît par son `name` et répond 409).
+ */
+export declare class ReferencedEntityError extends Error {
+    /** Entité dont la suppression est refusée (nom logique). */
+    readonly entity: string;
+    /** Entité qui la référence encore (nom logique). */
+    readonly referencedBy: string;
+    /** Champ de référence de {@link ReferencedEntityError.referencedBy}. */
+    readonly field: string;
+    /**
+     * @param entity - entité dont la suppression est refusée.
+     * @param referencedBy - entité qui la référence encore.
+     * @param field - champ de référence obligatoire qui la désigne.
+     */
+    constructor(entity: string, referencedBy: string, field: string);
+}
+/**
+ * Levée par `ITransaction.savepoint()` / `rollbackTo()` sur un moteur qui ne porte
+ * PAS de savepoints (MongoDB).
+ *
+ * Refuser vaut mieux que se taire : un `rollbackTo()` rendu en no-op laissait
+ * l'appelant croire ses écritures annulées alors qu'elles restaient en base. Le
+ * refus tombe dès `savepoint()`, pas au `rollbackTo()` : le chemin d'erreur, où
+ * l'on annule, est celui qu'on teste le moins — la faute doit se voir au premier
+ * essai. Pour annuler, terminer la transaction entière (`rollback()`, ou laisser
+ * le callback de `IOrm.transaction()` lever).
+ */
+export declare class SavepointNotSupportedError extends Error {
+    /** Moteur qui refuse (valeur de `describeConnection().driver`). */
+    readonly driver: string;
+    /**
+     * @param driver - moteur qui ne porte pas de savepoints.
+     * @param operation - opération refusée (`savepoint` ou `rollbackTo`).
+     */
+    constructor(driver: string, operation: "savepoint" | "rollbackTo");
+}

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

@@ -0,0 +1,16 @@
+import type { PartialInput } from "nodefony";
+/**
+ * Retire les clés qui valent `undefined` d'une donnée d'écriture partielle.
+ *
+ * `undefined` et clé absente veulent dire « ne pas toucher » : Drizzle ignore
+ * déjà une valeur `undefined`, Mongoose (≥ 6) la retire d'une mise à jour. La
+ * règle est posée ICI, une fois, au seuil de la persistance, au lieu d'être
+ * un comportement propre à chaque adaptateur.
+ *
+ * Rend l'objet reçu TEL QUEL quand aucune clé ne vaut `undefined` — le cas
+ * courant d'un corps JSON, qui ne peut pas en porter : aucune allocation.
+ *
+ * @param data - données d'écriture, clés `undefined` admises
+ * @returns les mêmes données, sans aucune clé `undefined`
+ */
+export declare function omitUndefined<T>(data: PartialInput<T>): Partial<T>;

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

@@ -0,0 +1,38 @@
+import type { IEntity } from "../interfaces/IEntity.js";
+/**
+ * Entités inscrites sur un connecteur qu'aucun ORM n'a ouvert.
+ *
+ * Une telle entité ne sera servie par rien : son dépôt lèvera au premier
+ * appel, loin de sa cause. Vécu : sur une infra MongoDB, le `User` d'une
+ * application restait écrit en table SQL sur `default` — un connecteur que
+ * Drizzle n'ouvre pas sur cette infra — et le boot n'en disait RIEN.
+ *
+ * @param entities - entités inscrites (registre des entités).
+ * @param connectors - connecteurs ouverts (registre des ORM).
+ * @returns les orphelines, dans l'ordre d'inscription.
+ */
+export declare function findOrphanEntities(entities: readonly IEntity[], connectors: readonly string[]): IEntity[];
+/**
+ * La phrase qui NOMME les orphelines et le remède — `null` s'il n'y en a pas.
+ *
+ * @param orphans - entités sans connecteur ouvert.
+ * @param connectors - connecteurs ouverts, cités pour situer la faute.
+ * @param declared - connecteurs DÉCLARÉS par les modules ORM (leur configuration).
+ */
+export declare function describeOrphanEntities(orphans: readonly IEntity[], connectors: readonly string[], declared?: readonly string[]): string | null;
+/**
+ * Signale UNE fois par démarrage les entités orphelines, au moment où tous les
+ * ORM sont ouverts.
+ *
+ * Appelée par chaque module ORM (Drizzle, Mongoose) à `onReady` : la règle vit
+ * ici, une fois, et le premier appel la rend — le second se tait, sans quoi une
+ * application qui charge les deux ORM lirait deux fois le même avertissement.
+ * La garde porte sur le KERNEL et non sur le process : un process qui démarre
+ * plusieurs noyaux (une suite de tests) doit être prévenu à chacun.
+ *
+ * @param log - journal du module appelant.
+ * @param owner - le démarrage concerné (le Kernel), clé de la garde.
+ * @param declared - connecteurs que l'appelant a DÉCLARÉS (sa configuration).
+ * @returns le message rendu, ou `null` (rien à dire, ou déjà dit).
+ */
+export declare function reportOrphanEntities(log: (message: string, severity: "WARNING") => void, owner: object, declared?: readonly string[]): string | null;

package/docs/index.md

@@ -177,7 +177,7 @@ garantit que la dépendance va bien du concret vers l'abstrait, et jamais l'inve
 > [!NOTE]
 > `orm-core` n'est **pas un module bootable** : pas de classe `Module`, rien à mettre dans
 > `modules: [...]`. C'est une bibliothèque pure. Les modules, ce sont les **drivers** — ce sont eux
-> qui s'enregistrent dans `ormRegistry` (`OrmRegistry.ts:88`) à leur démarrage.
+> qui s'enregistrent dans `ormRegistry` (`OrmRegistry.ts:86`) à leur démarrage.
 
 ## La vision Nodefony
 
@@ -377,13 +377,13 @@ sequenceDiagram
   Note over K: onServersReady → récap de boot
 ```
 
-**`entityRegistry`** (`EntityRegistry.ts:147`) indexe les entités à **deux** niveaux — nom puis
+**`entityRegistry`** (`EntityRegistry.ts:145`) indexe les entités à **deux** niveaux — nom puis
 connecteur — parce qu'une même entité logique (`User`) peut vivre sur plusieurs connexions. Demander
 `get("User")` sans préciser le connecteur alors que deux le portent **lève** plutôt que de deviner
 (`EntityRegistry.get()`, `EntityRegistry.ts:54`). Le stockage est un `Object.create(null)` alloué
 **au premier enregistrement** : une application sans base ne paie rien.
 
-**`ormRegistry`** (`OrmRegistry.ts:88`) associe un nom de connexion à son instance `IOrm`. Un doublon
+**`ormRegistry`** (`OrmRegistry.ts:86`) associe un nom de connexion à son instance `IOrm`. Un doublon
 de nom **lève** (`OrmRegistry.register()`, `OrmRegistry.ts:26`) : deux connexions homonymes seraient
 un bug silencieux, jamais une intention.
 
@@ -393,8 +393,8 @@ l'ordre des écouteurs, la table existe ou non. `entities()` s'accroche à `onRe
 (`entitiesDecorator.ts:66`), strictement antérieur — sûr par construction. C'est la différence de
 comportement avec `@controllers`, qui lui reste à `onBoot`.
 
-**`Orm.connect()`** (`Orm.ts:54`) est une **template method** : elle mesure la latence, alimente le
-moniteur de connexion, puis émet `onOrmReady`. Un adapter surcharge `onConnect()` (`Orm.ts:74`), et
+**`Orm.connect()`** (`Orm.ts:118`) est une **template method** : elle mesure la latence, alimente le
+moniteur de connexion, puis émet `onOrmReady`. Un adapter surcharge `onConnect()` (`Orm.ts:363`), et
 **jamais** `connect()` — sinon l'événement et l'instrumentation disparaissent.
 
 ## 🧰 Les contrats — la surface publique
@@ -412,35 +412,37 @@ transaction (`IOrm.transaction()`, `IOrm.ts:41`) et expose la trappe native
 
 Quatre méthodes sont **optionnelles** — un adapter qui ne les implémente pas dégrade proprement au
 lieu d'échouer : `describeEntity()` (`IOrm.ts:78`, colonnes pour l'ERD), `describeConnection()`
-(`IOrm.ts:71`, driver et cible **sans credential**), `ping()` (`IOrm.ts:82`, aller-retour réel) et
-`probe()` (`IOrm.ts:92`, métriques driver, qui ne doit **jamais** lever).
+(`IOrm.ts:88`, driver et cible **sans credential**), `ping()` (`IOrm.ts:109`, aller-retour réel) et
+`probe()` (`IOrm.ts:119`, métriques driver, qui ne doit **jamais** lever).
 
 ### [`IRepository`](tutorial-entity.md) — les quinze verbes
 
 `IRepository<T>` (`IRepository.ts:197`) est la seule surface que ton métier devrait connaître. Les
 verbes se choisissent sur **la garantie** qu'ils apportent, pas sur leur nom.
 
-| Verbe                 | Ce qu'il garantit                                                    | Ancre                        |
-| --------------------- | -------------------------------------------------------------------- | ---------------------------- |
-| `find` / `findOne`    | lecture filtrée + eager-load + tri + bornes                          | `IRepository.ts:213`         |
-| `count` / `exists`    | compter, ou juste savoir s'il y en a un (sans charger de colonne)    | `IRepository.ts:378`, `:335` |
-| `create`              | insertion d'une ligne, rend la version persistée (id, défauts)       | `IRepository.ts:240`         |
-| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots       | `IRepository.ts:252`         |
-| `updateOne`           | met à jour **au plus une** ligne, **atomiquement**, et la rend       | `IRepository.ts:269`         |
-| `updateMany`          | met à jour toutes les lignes du critère, rend le **nombre**          | `IRepository.ts:312`         |
-| `upsert`              | insère **ou** met à jour sur conflit de clé, en **une** instruction  | `IRepository.ts:296`         |
-| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, rate-limit             | `IRepository.ts:287`         |
-| `delete`              | supprime tout ce qui matche, rend le nombre                          | `IRepository.ts:298`         |
-| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                      | `IRepository.ts:328`         |
-| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, outbox, `pop` atomique | `IRepository.ts:355`         |
-| `withTransaction(tx)` | une **vue** du repository liée à une transaction                     | `IRepository.ts:406`         |
+| Verbe                 | Ce qu'il garantit                                                         | Ancre                |
+| --------------------- | ------------------------------------------------------------------------- | -------------------- |
+| `find` / `findOne`    | lecture filtrée + eager-load + tri + bornes                               | `IRepository.ts:230` |
+| `count`               | compter les entités qui correspondent au critère                          | `IRepository.ts:362` |
+| `exists`              | savoir s'il y en a au moins un, sans charger de colonne                   | `IRepository.ts:395` |
+| `countDistinct`       | compter les valeurs DISTINCTES et non nulles d'un champ, sans les charger | `IRepository.ts:381` |
+| `create`              | insertion d'une ligne, rend la version persistée (id, défauts)            | `IRepository.ts:240` |
+| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots            | `IRepository.ts:252` |
+| `updateOne`           | met à jour **au plus une** ligne, **atomiquement**, et la rend            | `IRepository.ts:269` |
+| `updateMany`          | met à jour toutes les lignes du critère, rend le **nombre**               | `IRepository.ts:312` |
+| `upsert`              | insère **ou** met à jour sur conflit de clé, en **une** instruction       | `IRepository.ts:296` |
+| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, rate-limit                  | `IRepository.ts:287` |
+| `delete`              | supprime tout ce qui matche, rend le nombre                               | `IRepository.ts:336` |
+| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                           | `IRepository.ts:345` |
+| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, outbox, `pop` atomique      | `IRepository.ts:355` |
+| `withTransaction(tx)` | une **vue** du repository liée à une transaction                          | `IRepository.ts:406` |
 
 > [!IMPORTANT]
 > `updateOne` est atomique **par construction** : une seule requête (`UPDATE … RETURNING` en SQL,
 > `findOneAndUpdate` en Mongo), jamais un `UPDATE` suivi d'une relecture. La différence n'est pas
 > cosmétique : la relecture rendrait `null` **à tort** dès que le critère porte sur un champ qu'on
 > vient de modifier — `updateOne({ status: "pending" }, { status: "done" })` ne retrouve plus rien
-> après coup (`IRepository.ts:221`).
+> après coup (`IRepository.ts:269`).
 
 Quelques usages, un par garantie :
 
@@ -472,11 +474,13 @@ atomique sur les quatre backends.
 
 ### [`IEntity`](tutorial-entity.md) — la description d'une table
 
-`IEntity` (`IEntity.ts:37`) porte un nom logique, un `connector` (le nom d'une **connexion**, jamais
+`IEntity` (`IEntity.ts:51`) porte un nom logique, un `connector` (le nom d'une **connexion**, jamais
 d'un moteur), un `schema` natif du driver, et des `relations` déclaratives (`IEntityRelation`,
 `IEntity.ts:4`). Deux champs facultatifs servent la lisibilité d'un gros modèle : `module` (qui
-apporte l'entité) et `domain` (`IEntity.ts:58`, la classification métier — l'axe qui rend navigable
-une base de plusieurs centaines de tables).
+apporte l'entité) et `domain` (`IEntity.ts:72`, la classification métier — l'axe qui rend navigable
+une base de plusieurs centaines de tables). Un troisième, `indexes` (`IEntityIndex`), déclare les
+index COMPOSITES qu'un adaptateur ne sait pas exprimer dans son schéma : Mongoose les applique
+(`schema.index()`), Drizzle les ignore, puisqu'il les déclare dans sa table.
 
 Dans une application, on ne construit pas un `IEntity` à la main : on écrit un `IEntityDefinition`
 (`defineEntity.ts:15`) — le même objet **sans** `connector`, justement parce que le connecteur est
@@ -555,7 +559,7 @@ Deux décisions le rendent utilisable sur une grosse table :
    `false`. C'est la distinction « Page » (avec total) et « Slice » (sans), reprise de Spring Data.
 
 Les bornes sont normalisées plutôt que propagées : un `limit` de `0` ou un `offset` négatif est
-ramené dans le domaine valide (`paginate.ts:28`) — un `find({ limit: 0 })` a un comportement qui
+ramené dans le domaine valide (`paginate.ts:56`) — un `find({ limit: 0 })` a un comportement qui
 dépend du dialecte, donc on ne le laisse pas sortir.
 
 Le contrat de page lui-même (`IPage`, `IPageQuery`) vit dans le **cœur**
@@ -588,7 +592,7 @@ export class ArticleService extends AbstractCrudService<ArticleRow> {
 - **Lectures** (`find`, `findOne`, `findById`, `count`, `findPage`) — **délégation pure**. Aucun
   hook, aucun événement : c'est le chemin chaud, il ne doit rien payer.
 - **Mutations** (`create`, `updateOne`, `delete`) — encadrées par des hooks _template method_
-  (`beforeCreate`, `AbstractCrudService.ts:185`, et ses six frères) puis un événement de cycle de vie
+  (`beforeCreate`, `AbstractCrudService.ts:212`, et ses six frères) puis un événement de cycle de vie
   `onCreated` / `onUpdated` / `onDeleted`, **émis seulement si la mutation a eu lieu**
   (`AbstractCrudService.ts:167`). L'audit, l'invalidation de cache ou une notification Studio s'y
   abonnent sans toucher au service.
@@ -606,21 +610,22 @@ d'administration : elle ne charge qu'une page, quelle que soit la taille de la t
 
 Deux drivers implémentent les contrats. Le contrat `IRepository` est tenu **en entier** par les
 deux : les quinze verbes existent des deux côtés — par exemple l'upsert, avec
-`DrizzleRepository.upsert()` (`DrizzleRepository.ts:868`) et `MongooseRepository.upsert()`
-(`MongooseRepository.ts:343`).
-
-| Capacité                               | `@nodefony/drizzle`                 | `@nodefony/mongoose`               |
-| -------------------------------------- | ----------------------------------- | ---------------------------------- |
-| Moteurs                                | SQLite, PostgreSQL, MySQL / MariaDB | MongoDB                            |
-| Contrat `IRepository` (15 verbes)      | complet                             | complet                            |
-| Eager-load `{ relations }`             | oui                                 | oui (`populate`)                   |
-| Transactions + savepoints              | oui                                 | oui (replica set requis par Mongo) |
-| Colonnes pour l'ERD (`describeEntity`) | oui (`DrizzleOrm.ts:1593`)          | oui (`MongooseOrm.ts:558`)         |
-| Sonde de flux (requêtes/s, lentes)     | oui — alimente `queryFlowMonitor`   | non câblée                         |
-| Sonde profonde (`probe`)               | oui (`DrizzleOrm.ts:1614`)          | oui (`MongooseOrm.ts:529`)         |
-
-**Les « stores » du framework, eux, ne sont pas alignés — et c'est un choix.** Un adapter déclare ce
-qu'il porte dans son `package.json`, clé `nodefony.stores` :
+`DrizzleRepository.upsert()` (`DrizzleRepository.ts:866`) et `MongooseRepository.upsert()`
+(`MongooseRepository.ts:422`).
+
+| Capacité                               | `@nodefony/drizzle`                 | `@nodefony/mongoose`                         |
+| -------------------------------------- | ----------------------------------- | -------------------------------------------- |
+| Moteurs                                | SQLite, PostgreSQL, MySQL / MariaDB | MongoDB                                      |
+| Contrat `IRepository` (15 verbes)      | complet                             | complet                                      |
+| Eager-load `{ relations }`             | oui                                 | oui (`populate`)                             |
+| Transactions                           | oui                                 | oui (replica set requis par Mongo)           |
+| Savepoints (rollback partiel)          | oui                                 | non — refusés (`SavepointNotSupportedError`) |
+| Colonnes pour l'ERD (`describeEntity`) | oui (`DrizzleOrm.ts:1971`)          | oui (`MongooseOrm.ts:649`)                   |
+| Sonde de flux (requêtes/s, lentes)     | oui — alimente `queryFlowMonitor`   | non câblée                                   |
+| Sonde profonde (`probe`)               | oui (`DrizzleOrm.ts:1873`)          | oui (`MongooseOrm.ts:617`)                   |
+
+**Les « stores » du framework** : chaque adapter déclare ce qu'il porte dans son `package.json`, clé
+`nodefony.stores`. Les deux backends durables portent les huit :
 
 | Store         | drizzle | mongoose |
 | ------------- | ------- | -------- |
@@ -629,22 +634,21 @@ qu'il porte dans son `package.json`, clé `nodefony.stores` :
 | `tokens`      | ✅      | ✅       |
 | `passkeys`    | ✅      | ✅       |
 | `webhooks`    | ✅      | ✅       |
-| `totp`        | ✅      | —        |
-| `audit`       | ✅      | —        |
-| `idempotency` | ✅      | —        |
+| `totp`        | ✅      | ✅       |
+| `audit`       | ✅      | ✅       |
+| `idempotency` | ✅      | ✅       |
 
 > [!NOTE]
-> La couverture est **adaptée à la nature de chaque backend**, ce n'est pas une parité SQL × NoSQL à
-> atteindre. Un store d'idempotence veut une contrainte d'unicité et un `ON CONFLICT` — le terrain du
-> SQL. Lire ce tableau comme « mongoose est incomplet » serait un contresens : il porte exactement ce
-> qu'un déploiement Mongo attend de lui. La liste fait autorité côté code
-> (`@nodefony/drizzle/package.json`, clé `nodefony.stores`) — elle n'est pas un commentaire.
+> La couverture est **adaptée à la nature de chaque backend** : c'est `@nodefony/redis`, un cache,
+> qui s'arrête à quatre stores (`session`, `tokens`, `passkeys`, `idempotency`) — il ne garde ni
+> comptes ni journal. La liste fait autorité côté code (`nodefony.stores` du `package.json` de chaque
+> adapter) — elle n'est pas un commentaire.
 
 ## 🧩 Extension — brancher son propre driver
 
 Le contrat minimal tient en peu de choses, parce que `orm-core` fournit déjà la plomberie.
 
-1. **Étendre `Orm`** (`Orm.ts:29`) : implémenter `onConnect()`, `disconnect()`, `isConnected()`,
+1. **Étendre `Orm`** (`Orm.ts:46`) : implémenter `onConnect()`, `disconnect()`, `isConnected()`,
    `getRepository()`, `transaction()`, `getNativeConnection()`. L'enregistrement dans `ormRegistry`
    est fait par le constructeur de base — il n'y a rien à écrire. **Ne jamais surcharger
    `connect()`** : c'est la template method qui émet `onOrmReady` et instrumente la latence.
@@ -672,10 +676,10 @@ la santé ne doit pas coûter le débit, et observer le débit ne doit pas réve
 
 **`connectionMonitor`** (`ConnectionMonitor.ts:197`) suit le **cycle de vie** d'une connexion :
 première connexion, reconnexions, erreurs récentes, et une fenêtre de latence de ping
-(`ConnectionMonitor.recordPing()`, `ConnectionMonitor.ts:106`). Il est alimenté par `Orm.connect()`
+(`ConnectionMonitor.recordPing()`, `ConnectionMonitor.ts:136`). Il est alimenté par `Orm.connect()`
 sans que l'adapter ait à y penser.
 
-**`queryFlowMonitor`** (`QueryFlowMonitor.ts:146`) suit le **débit** : total de requêtes, latence
+**`queryFlowMonitor`** (`QueryFlowMonitor.ts:144`) suit le **débit** : total de requêtes, latence
 moyenne et EWMA, pire latence, et un anneau borné à vingt requêtes lentes. Trois propriétés le
 rendent sûr en production :
 
@@ -687,7 +691,7 @@ rendent sûr en production :
   observe, et le débit par seconde est **dérivé côté lecteur** (delta entre deux relevés), donc rien
   n'est muté à la lecture.
 
-Le data plane `/nodefony/orm/api/*` (`createOrmAdminApi()`, `OrmAdminApi.ts:421`) expose huit points
+Le data plane `/nodefony/orm/api/*` (`createOrmAdminApi()`, `OrmAdminApi.ts:541`) expose huit points
 d'entrée, tous filtrables par `?connector=` :
 
 | Point d'entrée      | Ce qu'il rend                                                     |
@@ -695,11 +699,11 @@ d'entrée, tous filtrables par `?connector=` :
 | `orms`              | les connecteurs, leur état, leur nombre d'entités                 |
 | `entities`          | le modèle complet : colonnes + relations                          |
 | `entity/{name}`     | une entité (404 si inconnue)                                      |
-| `graph`             | le graphe canonique (`buildOrmGraph()`, `OrmAdminApi.ts:184`)     |
+| `graph`             | le graphe canonique (`buildOrmGraph()`, `OrmAdminApi.ts:227`)     |
 | `counts`            | le nombre de lignes par entité — un `COUNT(*)` par table          |
 | `connection/health` | état, latence, erreurs, reconnexions, sondes                      |
-| `flow`              | débit et requêtes lentes (`buildOrmFlow()`, `OrmAdminApi.ts:310`) |
-| `export/{format}`   | `dbml` (`toDbml()`, `OrmAdminApi.ts:345`) ou `jsonschema`         |
+| `flow`              | débit et requêtes lentes (`buildOrmFlow()`, `OrmAdminApi.ts:360`) |
+| `export/{format}`   | `dbml` (`toDbml()`, `OrmAdminApi.ts:395`) ou `jsonschema`         |
 
 Ce graphe canonique est **la pièce maîtresse**, pas le diagramme : c'est une donnée sérialisable qui
 sert à la fois l'ERD de Studio, un export vers un outil tiers, et le contexte d'un agent IA
@@ -730,14 +734,14 @@ deux, et pas de course).
 | Symptôme                                                      | Cause                                                                                              | Correction                                                                                  |
 | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | « no entity registered under "X" » au premier appel           | l'entité n'a jamais été inscrite (fichier importé mais `defineEntity` est sans effet de bord)      | l'ajouter à `@entities([...])` sur le module (`entitiesDecorator.ts:56`)                    |
-| La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec `connect()`                                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts:66`)        |
+| La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec `connect()`                                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts:56`)        |
 | « entity "User" exists on multiple connectors … specify one » | la même entité vit sur plusieurs connecteurs                                                       | préciser le connecteur : `entityRegistry.get("User", "analytics")` (`EntityRegistry.ts:54`) |
 | Un filtre « champ vide » ne remonte jamais rien               | `colonne = NULL` est toujours faux en SQL                                                          | `{ champ: { $null: true } }` ou la valeur nue `{ champ: null }` (`IRepository.ts:65`)       |
 | `UnknownCriteriaField` sur un champ qui existe « pourtant »   | faute de frappe, ou champ calculé absent du schéma                                                 | lire les champs connus dans le message ; pour du natif, passer par `getNativeConnection()`  |
-| `updateOne` rend `null` alors que la ligne a bien changé      | ancien réflexe `UPDATE` + relecture (le critère porte sur le champ modifié)                        | utiliser `updateOne`, atomique par construction (`IRepository.ts:252`)                      |
+| `updateOne` rend `null` alors que la ligne a bien changé      | ancien réflexe `UPDATE` + relecture (le critère porte sur le champ modifié)                        | utiliser `updateOne`, atomique par construction (`IRepository.ts:269`)                      |
 | Un `upsert` écrase une valeur qui devait progresser           | le `DO UPDATE` est inconditionnel (contrainte MySQL)                                               | poser la condition **dans** la valeur : `{ seuil: { $max: v } }` (`IRepository.ts:94`)      |
 | Un objet de critère est pris pour une égalité (colonne JSON)  | comportement **voulu** : une valeur n'est un filtre que si **toutes** ses clés sont des opérateurs | c'est la protection ; pour filtrer dedans, passer au natif (`criteria.ts:42`)               |
-| `onOrmReady` ne part plus après un ajout dans l'adapter       | `connect()` a été surchargé                                                                        | surcharger `onConnect()` (`Orm.ts:74`), jamais `connect()`                                  |
+| `onOrmReady` ne part plus après un ajout dans l'adapter       | `connect()` a été surchargé                                                                        | surcharger `onConnect()` (`Orm.ts:363`), jamais `connect()`                                 |
 | Une entité déclarée dans un module reste invisible            | le module embarque sa **propre copie** du registre (singleton dédoublé)                            | externaliser `@nodefony/orm-core` dans le `rolldown.config.ts` du module                    |
 | Rien dans `flow` alors que la base travaille                  | la sonde est éteinte hors développement, ou le driver n'a pas de tap                               | `NF_ORM_FLOW=1` (`ormWiring.ts:96`) ; le tap n'est câblé que côté Drizzle                   |
 

package/docs/tutorial-entity.md

@@ -88,7 +88,7 @@ battre contre le cadre.
 
 **1. Le connecteur est une donnée de configuration, jamais de code.** C'est pourquoi le
 descripteur qu'on écrit (`IEntityDefinition`, `defineEntity.ts:15`) est un `IEntity`
-(`IEntity.ts:37`) **privé de son `connector`** : celui-ci est résolu au démarrage, avec `"default"`
+(`IEntity.ts:51`) **privé de son `connector`** : celui-ci est résolu au démarrage, avec `"default"`
 pour valeur de repli (`DEFAULT_CONNECTOR`, `entitiesDecorator.ts:12`). Figer la connexion dans le
 fichier d'entité interdirait de servir la même table depuis une base différente selon
 l'environnement.
@@ -303,7 +303,7 @@ Cette absence d'effet de bord est délibérée : elle permet d'importer une enti
 un script ou un autre module **sans** déclencher son inscription dans un singleton global.
 
 Les champs facultatifs qui servent tôt : `module` (qui apporte l'entité) et `domain`
-(`IEntity.ts:58`), l'axe de classification qui rend navigable une base de plusieurs centaines de
+(`IEntity.ts:72`), l'axe de classification qui rend navigable une base de plusieurs centaines de
 tables dans l'ERD Studio.
 
 ### Étape 4 — brancher l'entité au module
@@ -318,7 +318,7 @@ d'être connues :
    être instancié deux fois : tests, rechargement). Une vraie collision, elle, lève
    (`EntityRegistry.register()`, `EntityRegistry.ts:24`).
 3. **Connecteur commun** — `entities([...], { connector: "analytics" })` pose toute la liste sur
-   une autre base ; une entité qui porte son propre `connector` (`IEntity.ts:42`) garde le sien.
+   une autre base ; une entité qui porte son propre `connector` (`IEntity.ts:56`) garde le sien.
 
 ### Le raccourci — `nodefony create entity`
 
@@ -339,32 +339,35 @@ que l'import plus la ligne du décorateur.
 > [!WARNING]
 > La commande refuse de générer si aucun module ORM n'est déclaré dans l'application. C'est
 > volontaire : une entité sans driver produit du code mort qui ne compile même pas. Ajoute
-> `use("@nodefony/drizzle", …)` au manifeste `modules`, puis relance.
+> `"@nodefony/drizzle"` (SQL) ou `"@nodefony/mongoose"` (MongoDB) au manifeste `modules`, puis
+> relance. Sur MongoDB, la même commande écrit un schéma Mongoose au lieu d'une table.
 
 ## 🧰 Lire et écrire — le contrat complet
 
 Le repository porte **quinze verbes**, pas cinq. Ils se choisissent sur la **garantie** qu'ils
 apportent, jamais sur leur nom.
 
-| Verbe                 | Ce qu'il garantit                                                  | Ancre                        |
-| --------------------- | ------------------------------------------------------------------ | ---------------------------- |
-| `find` / `findOne`    | lecture filtrée, avec tri, bornes et eager-load                    | `IRepository.ts:213`, `:192` |
-| `create`              | insère une ligne et rend sa version persistée (id, défauts)        | `IRepository.ts:240`         |
-| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots     | `IRepository.ts:252`         |
-| `updateOne`           | modifie **au plus une** ligne, **atomiquement**, et la rend        | `IRepository.ts:269`         |
-| `updateMany`          | modifie toutes les lignes du critère, rend le **nombre**           | `IRepository.ts:312`         |
-| `upsert`              | insère **ou** met à jour sur conflit de clé, en une instruction    | `IRepository.ts:296`         |
-| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, limitation de débit  | `IRepository.ts:287`         |
-| `delete`              | supprime tout ce qui matche, rend le nombre                        | `IRepository.ts:298`         |
-| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                    | `IRepository.ts:328`         |
-| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, `pop` atomique       | `IRepository.ts:355`         |
-| `count` / `exists`    | compter, ou juste savoir s'il y en a une (sans charger de colonne) | `IRepository.ts:378`, `:335` |
-| `withTransaction(tx)` | une **vue** du repository liée à une transaction                   | `IRepository.ts:406`         |
+| Verbe                 | Ce qu'il garantit                                                         | Ancre                        |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------- |
+| `find` / `findOne`    | lecture filtrée, avec tri, bornes et eager-load                           | `IRepository.ts:230`, `:192` |
+| `create`              | insère une ligne et rend sa version persistée (id, défauts)               | `IRepository.ts:240`         |
+| `createMany`          | N lignes en **une** requête — seed, import, ingestion par lots            | `IRepository.ts:252`         |
+| `updateOne`           | modifie **au plus une** ligne, **atomiquement**, et la rend               | `IRepository.ts:269`         |
+| `updateMany`          | modifie toutes les lignes du critère, rend le **nombre**                  | `IRepository.ts:312`         |
+| `upsert`              | insère **ou** met à jour sur conflit de clé, en une instruction           | `IRepository.ts:296`         |
+| `increment`           | `SET f = f + ?` atomique — compteurs, quotas, limitation de débit         | `IRepository.ts:287`         |
+| `delete`              | supprime tout ce qui matche, rend le nombre                               | `IRepository.ts:336`         |
+| `deleteOne`           | supprime **au plus une** ligne, rend un booléen                           | `IRepository.ts:345`         |
+| `findOneAndDelete`    | supprime **et rend** la ligne — file de jobs, `pop` atomique              | `IRepository.ts:355`         |
+| `count`               | compter les entités qui correspondent au critère                          | `IRepository.ts:362`         |
+| `exists`              | savoir s'il y en a au moins une, sans charger de colonne                  | `IRepository.ts:395`         |
+| `countDistinct`       | compter les valeurs DISTINCTES et non nulles d'un champ, sans les charger | `IRepository.ts:381`         |
+| `withTransaction(tx)` | une **vue** du repository liée à une transaction                          | `IRepository.ts:406`         |
 
 > [!IMPORTANT]
 > **Il n'existe pas de méthode `update()`.** Le choix est explicite et il est intentionnel :
 > `IRepository.updateOne()` (`IRepository.ts:269`) pour une ligne — atomique, et elle **rend** la
-> ligne modifiée —, `IRepository.updateMany()` (`IRepository.ts:274`) pour un lot — qui rend le
+> ligne modifiée —, `IRepository.updateMany()` (`IRepository.ts:312`) pour un lot — qui rend le
 > **nombre** de lignes touchées. Un verbe unique masquerait cette différence de garantie, qui est
 > précisément ce qu'on veut choisir en connaissance de cause.
 
@@ -393,7 +396,7 @@ await orm.transaction(async (tx) => {
 ```
 
 Deux réflexes de performance, dès le premier jour : préférer `IRepository.exists()`
-(`IRepository.ts:335`) à `findOne(...) !== null` — aucune colonne n'est chargée —, et
+(`IRepository.ts:395`) à `findOne(...) !== null` — aucune colonne n'est chargée —, et
 `IRepository.increment()` (`IRepository.ts:325`) à une lecture suivie d'une écriture : une requête
 au lieu de deux, et pas de course.
 
@@ -471,7 +474,7 @@ champs connus — le diagnostic d'une faute de frappe est immédiat.
 
 ## 📄 Pager les résultats
 
-`find()` avec `limit`/`offset`/`order` (`RepositoryReadOptions`, `IRepository.ts:153`) suffit pour
+`find()` avec `limit`/`offset`/`order` (`RepositoryReadOptions`, `IRepository.ts:174`) suffit pour
 une tranche. Pour une vraie page — celle qui sait s'il y a une suite — utilise `paginate()`
 (`paginate.ts:47`) :
 
@@ -524,9 +527,9 @@ d'administration, la primitive est `AbstractCrudService.findPage()` (`AbstractCr
 
 | Symptôme                                                      | Cause                                                                                            | Correction                                                                                               |
 | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `posts.update is not a function`                              | la méthode `update()` n'existe pas dans le contrat                                               | `updateOne` pour une ligne (`IRepository.ts:269`), `updateMany` pour un lot (`IRepository.ts:274`)       |
+| `posts.update is not a function`                              | la méthode `update()` n'existe pas dans le contrat                                               | `updateOne` pour une ligne (`IRepository.ts:269`), `updateMany` pour un lot (`IRepository.ts:312`)       |
 | « no entity registered under "Post" » au premier appel        | le fichier d'entité est importé, mais `defineEntity()` est **sans effet de bord**                | ajouter l'entité à `@entities([...])` sur le module (`entitiesDecorator.ts:56`)                          |
-| La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec l'ouverture du connecteur                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts:66`)                     |
+| La table n'existe pas alors que l'entité est déclarée         | inscription faite à `onBoot` → course avec l'ouverture du connecteur                             | inscrire à `onRegister` — c'est ce que fait `entities()` (`entitiesDecorator.ts:56`)                     |
 | Une colonne ajoutée au schéma reste absente de la table       | le DDL du boot est un `CREATE TABLE IF NOT EXISTS` : aucun `ALTER` n'est émis                    | supprimer la base de développement et redémarrer, ou passer par une migration                            |
 | Un `DEFAULT` SQL ou un index déclaré n'apparaît pas           | le DDL dérivé ne les émet pas                                                                    | poser le défaut côté JavaScript (`$defaultFn`) ; créer l'index par migration                             |
 | Un filtre « champ vide » ne remonte jamais rien               | `colonne = NULL` est toujours faux en SQL                                                        | `{ champ: { $null: true } }` ou la valeur nue `{ champ: null }` (`IRepository.ts:65`)                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/orm-core",
-  "version": "10.0.0-alpha.8",
+  "version": "10.0.0-beta.1",
   "description": "Un contrat de dépôt de données pour Nodefony, plusieurs moteurs : interfaces, registre et classes de base pour le support multi-ORM",
   "contributors": [],
   "type": "module",
@@ -8,6 +8,7 @@
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "nodefony-source": "./index.ts",
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
@@ -15,9 +16,9 @@
   },
   "scripts": {
     "start": "node dist/index.js",
-    "build": "rimraf dist && rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
     "dev": "rolldown -c rolldown.config.ts --watch",
-    "clean": "rimraf dist",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
     "typecheck": "tsgo --noEmit -p tsconfig.json && tsgo --noEmit -p tsconfig.tests.json"
@@ -36,13 +37,12 @@
     "esm"
   ],
   "peerDependencies": {
-    "nodefony": "^10.0.0-alpha.8"
+    "nodefony": "^10.0.0-beta.1"
   },
   "devDependencies": {
-    "@types/node": "26.6.2",
-    "nodefony": "^10.0.0-alpha.8",
-    "rimraf": "6.1.3",
-    "vitest": "5.0.1"
+    "@types/node": "26.6.3",
+    "nodefony": "^10.0.0-beta.1",
+    "vitest": "5.0.2"
   },
   "repository": {
     "type": "git",