@nodefony/mongoose 10.0.0-alpha.8 → 10.0.0-alpha.9

package/dist/types/nodefony/src/orm-core/MongooseTransaction.d.ts

@@ -8,8 +8,8 @@ import type { ITransaction } from "@nodefony/orm-core";
  * MongoDB **exigent un replica set** (un standalone ne les supporte pas).
  *
  * MongoDB n'a **pas de savepoints** : {@link MongooseTransaction.savepoint} /
- * {@link MongooseTransaction.rollbackTo} sont des no-op documentés (limite du
- * driver, prévue par le contrat).
+ * {@link MongooseTransaction.rollbackTo} les REFUSENT (`SavepointNotSupportedError`).
+ * Un no-op laissait croire un rollback partiel qui n'annulait rien.
  */
 export declare class MongooseTransaction implements ITransaction {
     #private;
@@ -28,9 +28,17 @@ export declare class MongooseTransaction implements ITransaction {
     commit(): Promise<void>;
     /** Annule la transaction (no-op si déjà terminée — idempotent). */
     rollback(): Promise<void>;
-    /** No-op : MongoDB ne gère pas les savepoints. */
+    /**
+     * Refusé : MongoDB n'a pas de savepoints.
+     *
+     * @throws SavepointNotSupportedError toujours.
+     */
     savepoint(_name: string): Promise<void>;
-    /** No-op : MongoDB ne gère pas les savepoints. */
+    /**
+     * Refusé : MongoDB n'a pas de savepoints.
+     *
+     * @throws SavepointNotSupportedError toujours.
+     */
     rollbackTo(_name: string): Promise<void>;
     /** Expose la `ClientSession` native (trappe bas niveau). */
     getNative<C = unknown>(): C;

package/docs/configuration.md

@@ -105,7 +105,7 @@ mêmes noms partout — pour qu'on ne se pose jamais la question de savoir où r
 | `nodefony/config/config.ts`             | **Le QUOI**    | Le schéma Zod commenté, source unique des défauts, et le type TS qui en dérive |
 | `nodefony/config/defineModuleConfig.ts` | **Le COMMENT** | Le builder : valide → applique l'environnement → gèle. Plus le JSON Schema.    |
 
-Le schéma (`mongooseConfigSchema` (`config.ts:83`)) porte les valeurs d'usine sous forme de
+Le schéma (`mongooseConfigSchema` (`config.ts:98`)) porte les valeurs d'usine sous forme de
 `.default(…)`, et chaque champ son `.describe(…)`. Les défauts effectifs du module ne sont pas
 retapés à la main : ils sont **matérialisés depuis le schéma lui-même**
 (`mongooseConfigSchema.parse({})` (`config.ts:122`)). Changer un défaut = changer le `.default()`,
@@ -134,11 +134,11 @@ qui collisionnerait à l'import). Trois écarts réels, tous **assumés et véri
    Ce n'est pas de la fantaisie : les entités sont indexées par `(connecteur, nom)` dans un registre
    **global au processus**, donc deux drivers avec le même nom de connecteur feraient collision sur
    leurs entités `session` homonymes. Un nom distinct règle le problème par construction
-   (`FRAMEWORK_CONNECTOR` (`registerStores.ts:49`)).
+   (`FRAMEWORK_CONNECTOR` (`registerStores.ts:77`)).
 2. **Mongoose expose deux variables dédiées** (`MONGODB_URI`, `NF_MONGODB_DEBUG`) là où Drizzle ne lit
    que l'infra déclarée. C'est un héritage de convention du driver Mongo, conservé parce qu'il est
    universellement connu — mais l'infra déclarée reste le chemin recommandé.
-3. **`options` n'est pas re-modélisé** (`options` (`config.ts:71`)) : c'est un dictionnaire libre
+3. **`options` n'est pas re-modélisé** (`options` (`config.ts:86`)) : c'est un dictionnaire libre
    passé tel quel à Mongoose. Re-décrire les dizaines de `ConnectOptions` en Zod produirait une
    deuxième vérité, condamnée à diverger de la bibliothèque à chaque version. Le prix à payer est
    assumé : une faute de frappe dans `options` n'est pas attrapée par Zod, elle l'est par Mongoose
@@ -232,7 +232,7 @@ export default defineConfig(() => ({
 ```
 
 Si `NF_DATABASE_URL` pointe déjà sur du `mongodb://`, tu peux laisser **tous** ces champs sur leur
-défaut `auto` : la résolution suit l'infra déclarée (`resolveAutoStore()` (`infra.ts:241`)) et
+défaut `auto` : la résolution suit l'infra déclarée (`resolveAutoStore()` (`infra.ts:297`)) et
 journalise sa raison. Détail dans le hub, section
 [Ce qui se passe quand tu ne choisis rien](./index.md#ce-qui-se-passe-quand-tu-ne-choisis-rien).
 
@@ -260,14 +260,14 @@ Et six champs par connecteur :
 
 ### `connectors` — une ou plusieurs bases
 
-Chaque entrée de `connectors` (`config.ts:93`) devient une **connexion isolée** ouverte au démarrage,
+Chaque entrée de `connectors` (`config.ts:108`) devient une **connexion isolée** ouverte au démarrage,
 puis un ORM inscrit sous ce nom. Deux entrées = deux connexions, deux ORM, deux jeux d'entités : c'est
 ainsi qu'une application lit une base métier et écrit dans une base d'archives sans les mélanger.
 
 L'adresse se donne de deux façons, jamais les deux à la fois utilement :
 
 - **En pièces détachées** — `host`, `port`, `dbname` : lisible, adapté au développement. Le service
-  les assemble en `mongodb://hôte:port/base` (`MongooseService.buildUri()` (`MongooseService.ts:94`)).
+  les assemble en `mongodb://hôte:port/base` (`MongooseService.buildUri()` (`MongooseService.ts:102`)).
 - **En une URI** — `uri` (`config.ts:41`) : la seule forme capable d'exprimer un replica set, un
   `mongodb+srv`, des options de requête. **Dès qu'`uri` est présent, les trois autres champs ne sont
   plus lus du tout.**
@@ -287,15 +287,15 @@ publique** de ton application : le changer déplace des entités.
 
 > [!WARNING]
 > Le connecteur nommé `nodefony` a un statut particulier : c'est **lui** qui porte le schéma du
-> framework (`FRAMEWORK_CONNECTOR` (`registerStores.ts:49`)) et le stockage de session
+> framework (`FRAMEWORK_CONNECTOR` (`registerStores.ts:77`)) et le stockage de session
 > (`SESSION_CONNECTOR` (`sessionEntity.ts:5`)). Le renommer ou le supprimer sans le remplacer casse
 > les stores framework — ils cherchent un ORM `nodefony` connecté et échouent franchement s'il manque
-> (`resolveConnectedOrm()` (`registerStores.ts:64`)).
+> (`resolveConnectedOrm()` (`registerStores.ts:92`)).
 
 ### `options` — ce que Mongoose sait faire et Nodefony ne re-décrit pas
 
-`options` (`config.ts:71`) est transmis tel quel au driver
-(`MongooseService.#connectOne()` (`MongooseService.ts:87`)). On y met tout ce qui touche au
+`options` (`config.ts:86`) est transmis tel quel au driver
+(`MongooseService.#connectOne()` (`MongooseService.ts:141`)). On y met tout ce qui touche au
 **transport** plutôt qu'à l'adresse : taille du pool, délais, TLS, identifiants séparés.
 
 ```typescript
@@ -320,7 +320,7 @@ description des options du driver.
 
 ### `debug` — voir passer les requêtes
 
-`debug` (`config.ts:85`) active la trace intégrée de Mongoose (`connectAll()` (`MongooseService.ts:81`)).
+`debug` (`config.ts:100`) active la trace intégrée de Mongoose (`connectAll()` (`MongooseService.ts:81`)).
 Chaque opération part sur la sortie standard, avec sa collection, son filtre et ses champs.
 
 C'est un **réglage de processus, pas de connecteur** : il vaut pour toutes les connexions à la fois.
@@ -330,7 +330,7 @@ détaillée dans la section [Observabilité](#-observabilité--studio).
 
 ### `frameworkEntities` — le module pose-t-il le schéma du framework ?
 
-C'est le champ le plus discret et le plus structurant (`frameworkEntities` (`config.ts:102`)). Sur son
+C'est le champ le plus discret et le plus structurant (`frameworkEntities` (`config.ts:117`)). Sur son
 défaut `true`, le module fait deux choses de plus qu'ouvrir des connexions, dès son enregistrement et
 **avant** que la connexion ne s'ouvre (`Mongoose.onKernelRegister()` (`mongoose/index.ts:65`)) :
 
@@ -338,7 +338,7 @@ défaut `true`, le module fait deux choses de plus qu'ouvrir des connexions, dè
    pour que leurs modèles soient compilés au moment de la connexion ;
 2. il **enregistre les fabriques** correspondantes dans les registres de `@nodefony/security`, ce qui
    rend le nom `"mongoose"` sélectionnable dans `tokenStore`, `passkeys`, `webhooks`
-   (`registerMongooseFrameworkStores()` (`registerStores.ts:94`)).
+   (`registerMongooseFrameworkStores()` (`registerStores.ts:126`)).
 
 Le passer à `false` transforme le module en **pur driver de données** : tes entités à toi, rien
 d'autre. Les stores framework Mongo deviennent alors introuvables — les sélectionner échoue
@@ -405,7 +405,7 @@ NF__MONGOOSE__CONNECTORS__NODEFONY__DBNAME=recette    # champ imbriqué
 NF__MONGOOSE__CONNECTORS__NODEFONY__PORT=27018        # coercé en nombre
 ```
 
-Ces overrides sont posés **avant** la validation Zod (`Kernel.applyEnvConfigOverrides()` (`Kernel.ts:1708`)) :
+Ces overrides sont posés **avant** la validation Zod (`Kernel.applyEnvConfigOverrides()` (`Kernel.ts:1807`)) :
 une valeur aberrante est donc rejetée comme si tu l'avais écrite dans ton fichier. C'est voulu — un
 réglage d'environnement invalide doit casser aussi fort qu'un réglage de code.
 
@@ -436,7 +436,7 @@ De la plus faible à la plus forte priorité :
 
 1. **Les défauts du schéma** — `localhost:27017/nodefony`, `debug: false`, `frameworkEntities: true`.
 2. **Ta config d'app** — `use("@nodefony/mongoose", { … })`, fusionnée en profondeur sous les défauts
-   (`Kernel.loadModulesFromManifest()` (`Kernel.ts:1600`)).
+   (`Kernel.loadModulesFromManifest()` (`Kernel.ts:1656`)).
 3. **Un override venu d'un autre module** — la clé `module-mongoose` dans la config d'un module tiers.
 4. **`NF__MONGOOSE__…`** — l'override générique d'environnement.
 5. **La validation Zod** — types, bornes, défauts des champs restés absents.
@@ -550,8 +550,8 @@ use("@nodefony/mongoose", {
 
 Les deux connexions s'ouvrent en série au démarrage, dans l'ordre de déclaration
 (`connectAll()` (`MongooseService.ts:81`)), et se ferment toutes à l'arrêt
-(`disconnectAll()` (`MongooseService.ts:181`)). Un service peut demander l'une ou l'autre par son nom
-(`getOrm()` (`MongooseService.ts:189`)), mais l'usage courant reste le registre d'ORM.
+(`disconnectAll()` (`MongooseService.ts:195`)). Un service peut demander l'une ou l'autre par son nom
+(`getOrm()` (`MongooseService.ts:203`)), mais l'usage courant reste le registre d'ORM.
 
 ## 🔐 Le secret de connexion
 
@@ -561,10 +561,10 @@ données d'un coup. La règle est donc sans nuance.
 - **Jamais dans le dépôt.** Ni dans `nodefony.config.ts`, ni dans un fichier d'exemple, ni « juste
   pour le développement ». Le secret arrive par `MONGODB_URI` ou `NF_DATABASE_URL`.
 - **Ni dans les journaux, ni dans Studio.** L'URI est systématiquement nettoyée de tout
-  `utilisateur:motdepasse@` avant d'être affichée (`MongooseOrm.safeTarget()` (`MongooseOrm.ts:595`)),
+  `utilisateur:motdepasse@` avant d'être affichée (`MongooseOrm.safeTarget()` (`MongooseOrm.ts:688`)),
   y compris pour les URI multi-hôtes que l'analyseur d'URL standard ne sait pas découper. C'est cette
   cible nettoyée que voit le plan d'administration
-  (`MongooseOrm.describeConnection()` (`MongooseOrm.ts:583`)) et le message de connexion au démarrage.
+  (`MongooseOrm.describeConnection()` (`MongooseOrm.ts:676`)) et le message de connexion au démarrage.
 - **Les identifiants passés par `options`** (`user`, `pass`) suivent la même règle : ils viennent de
   l'environnement, pas du fichier. Le framework rédige d'ailleurs la valeur de tout override
   d'environnement dont le chemin ressemble à un secret, avant de le journaliser
@@ -665,7 +665,7 @@ coûteux à diagnostiquer qu'un serveur qui refuse de démarrer.
 
 Le cas courant : la config est parfaite, mais Mongo n'est pas joignable — conteneur pas encore prêt,
 réseau coupé, identifiants périmés. Le comportement **dépend de l'environnement**, arbitré par la
-politique de boot du cœur (`Kernel.isBootErrorFatal()` (`Kernel.ts:2843`)) :
+politique de boot du cœur (`Kernel.isBootErrorFatal()` (`Kernel.ts:3130`)) :
 
 | Environnement       | Ce qui se passe                                                                        |
 | ------------------- | -------------------------------------------------------------------------------------- |
@@ -688,7 +688,7 @@ tomber pour le relancer, et c'est le modèle cloud-native que le framework appli
 
 À l'arrêt, les connexions se ferment alors que des requêtes peuvent encore être en vol. Le stockage de
 session **dégrade gracieusement** plutôt que de lever une exception
-(`SessionStorage.#repo()` (`SessionStorage.ts:45`)) : une session non persistée le temps de l'arrêt
+(`SessionStorage.#repo()` (`SessionStorage.ts:66`)) : une session non persistée le temps de l'arrêt
 vaut mieux qu'une erreur 500 et un rejet non capturé. À l'inverse, une entité absente sur un ORM
 **connecté** est une vraie erreur de configuration : celle-là est levée sans ménagement.
 
@@ -718,7 +718,7 @@ frontière du plan d'administration.
 | `NF_DATABASE_URL` est bien posée, Mongo n'est pas utilisé                 | L'URL est de famille SQL : elle appartient à `@nodefony/drizzle`                     | Une URL `mongodb://`/`mongodb+srv://`, ou passer par `MONGODB_URI`                           |
 | Le démarrage échoue sur le schéma de l'URL                                | Schéma inconnu (`mongo://`, faute de frappe) — refus délibéré, jamais de repli       | Corriger le schéma : `mongodb://` ou `mongodb+srv://`                                        |
 | `Transaction numbers are only allowed on a replica set…`                  | Serveur isolé : pas de transactions                                                  | Un replica set, même à un nœud (`?replicaSet=rs0&directConnection=true`)                     |
-| `ORM "nodefony" introuvable` au montage d'un store                        | `@nodefony/security` chargé **avant** `@nodefony/mongoose`                           | Placer le driver **avant** dans `modules` (`resolveConnectedOrm()` (`registerStores.ts:64`)) |
+| `ORM "nodefony" introuvable` au montage d'un store                        | `@nodefony/security` chargé **avant** `@nodefony/mongoose`                           | Placer le driver **avant** dans `modules` (`resolveConnectedOrm()` (`registerStores.ts:92`)) |
 | Le store `mongoose` est introuvable pour les jetons                       | `frameworkEntities: false` — le module est en mode données seules                    | Repasser à `true`, ou choisir un backend qui porte la brique                                 |
 | `session: { store: "mongoose" }` marche malgré `frameworkEntities: false` | Attendu : la session s'enregistre à l'import, pas via ce champ                       | Rien à corriger — voir l'avertissement de la section `frameworkEntities`                     |
 | Une option de `options` n'a aucun effet                                   | Elle n'est pas validée par Zod ; Mongoose l'a ignorée ou refusée                     | Vérifier son nom exact dans les `ConnectOptions` de la version de Mongoose installée         |

package/docs/index.md

@@ -192,11 +192,11 @@ des connexions, la compilation des schémas, et présente le tout derrière le c
 
 Nodefony ne demande pas à chaque backend de tout savoir faire. **Chaque adapter déclare ce qu'il
 implémente**, dans son `package.json` (clé `nodefony.stores`), et le framework lit cette déclaration
-à chaud (`readAdapterManifest()` (`KernelAdminApi.ts:84`)). Rien n'est curaté dans le cœur : la
+à chaud (`readAdapterManifest()` (`KernelAdminApi.ts:93`)). Rien n'est curaté dans le cœur : la
 source de vérité, c'est l'adapter lui-même — ce qui vaut aussi pour un adapter tiers.
 
-Ce que `@nodefony/mongoose` déclare : `session`, `user`, `tokens`, `passkeys`, `webhooks`, avec la
-nature `durable`. Comparé aux deux autres adapters officiels :
+Ce que `@nodefony/mongoose` déclare : les huit briques — `session`, `user`, `tokens`, `passkeys`,
+`totp`, `audit`, `webhooks`, `idempotency` — avec la nature `durable`. Comparé aux deux autres adapters officiels :
 
 <!-- prettier-ignore -->
 | Brique | `@nodefony/drizzle` (SQL) | `@nodefony/mongoose` (Mongo) | `@nodefony/redis` (cache) |
@@ -206,24 +206,16 @@ nature `durable`. Comparé aux deux autres adapters officiels :
 | `tokens` | ✅ | ✅ | ✅ |
 | `passkeys` | ✅ | ✅ | ✅ |
 | `webhooks` | ✅ | ✅ | — |
-| `totp` | ✅ | — | — |
-| `audit` | ✅ | — | — |
-| `idempotency` | ✅ | — | ✅ |
+| `totp` | ✅ | ✅ | — |
+| `audit` | ✅ | ✅ | — |
+| `idempotency` | ✅ | ✅ | ✅ |
 | Nature | durable | durable | cache |
 
 > [!IMPORTANT]
-> **Ces trois cases vides sont un manque, et il sera comblé.** L'objectif est qu'une application
-> puisse tourner **entièrement sur MongoDB, sans charger `@nodefony/drizzle`** — donc mongoose à 8/8
-> Le raisonnement « ces briques-là appellent d'autres propriétés »
-> décrit une préférence technique, pas ce que vit l'utilisateur : **tu choisis une base de données, tu
-> ne choisis pas de perdre le 2FA, la traçabilité ou la déduplication.**
->
-> En attendant, ces trois briques se résolvent ailleurs **et te le disent** (repli annoncé au boot,
-> avertissement en production) — mais mesure ce que le repli coûte : secrets TOTP perdus au
-> redémarrage (utilisateurs verrouillés hors de leur second facteur), journal d'audit volatil,
-> idempotence sans effet entre pods. La parade immédiate tient en une ligne : charger
-> `@nodefony/drizzle` à côté de Mongo, **même en SQLite local** — les deux modules cohabitent, chaque
-> brique choisit son store.
+> **Une application tourne entièrement sur MongoDB, sans charger `@nodefony/drizzle`.** Les huit
+> briques y ont leur store, et ce n'est pas qu'une déclaration : `npm run test:all -- --mongo`
+> démarre l'application sur MongoDB et rejoue toute la passe d'intégration, et chaque store joue le
+> même banc de contrat que son jumeau SQL — cf [Parité des adaptateurs](../../../../../docs/guides/parite-des-adaptateurs.md).
 >
 > La colonne `redis` obéit à une autre logique : elle gagnera `totp` (au régime opt-in de ses jetons
 > et passkeys, jamais choisi par `auto`), mais pas `user`, `audit` ni `webhooks` — non parce que
@@ -233,7 +225,7 @@ nature `durable`. Comparé aux deux autres adapters officiels :
 ### Ce qui se passe quand tu ne choisis rien
 
 Chaque brique a une clé `store` dont le défaut est `"auto"`. La résolution
-(`resolveAutoStore()` (`infra.ts:241`)) suit l'infrastructure **déclarée**, bornée aux backends
+(`resolveAutoStore()` (`infra.ts:297`)) suit l'infrastructure **déclarée**, bornée aux backends
 réellement chargés :
 
 | Ta situation                                            | Ce que `auto` choisit                                    |
@@ -323,6 +315,9 @@ const ArticleEntity = defineEntity({
   module: "blog",
   schema: articleSchema,
   timestamps: true, // Mongoose gère createdAt / updatedAt
+  // Index COMPOSITE : un schéma plat n'en exprime que par champ. Sans lui, un
+  // tri sur deux champs parcourt la collection puis trie en mémoire.
+  indexes: [{ fields: { views: -1, createdAt: -1 } }], // « les plus lus, récents d'abord »
 });
 
 // ── 2. Le controller : le repository se demande au registre ─────────────────
@@ -362,6 +357,23 @@ class Blog extends Module {
 export default Blog;
 ```
 
+### Le raccourci — `nodefony create entity`
+
+Dans une application MongoDB (`create app --database mongodb`), tout ce qui précède se génère,
+avec la même grammaire de champs qu'en SQL :
+
+```bash
+npx nodefony create entity Post title:string(120) body:text? views:int=0 author:ref:User
+```
+
+La commande écrit le schéma Mongoose (`nodefony/entity/Post.ts`), les schémas de validation, un
+service CRUD, un controller REST + WebSocket et les tests, puis câble `@entities([...])` et
+`@controllers([...])`. L'entité se pose sur le connecteur `nodefony` ; une référence est un
+`ObjectId` indexé, que le schéma d'entrée exige bien formé (24 caractères hexadécimaux, sinon 422).
+Les options propres au SQL (`--table`, `--column-case`, `--id-name`, `--dialect`, `--id`,
+`--index`, `--unique`) sont refusées en le disant ; l'entité `User` ne se régénère pas, elle
+s'étend dans `nodefony/entity/User.ts`.
+
 ### 3. Ce qu'on observe
 
 ```bash
@@ -387,7 +399,7 @@ INFO  mongoose  Mongoose ORM "nodefony" connected (127.0.0.1:27017/blog)
 
 Une fois le driver chargé, les stores Mongo deviennent **sélectionnables par leur nom**, sans aucun
 câblage : le module les enregistre lui-même à son démarrage
-(`registerMongooseFrameworkStores()` (`registerStores.ts:94`)).
+(`registerMongooseFrameworkStores()` (`registerStores.ts:126`)).
 
 ```typescript
 // nodefony.config.ts — sessions, jetons, passkeys et webhooks dans Mongo
@@ -472,7 +484,7 @@ sequenceDiagram
 
 L'ordre n'est pas cosmétique. Les entités sont déclarées à `onKernelRegister`, **strictement avant**
 le `connect` de `onBoot` : les modèles sont compilés à la connexion
-(`MongooseOrm.onConnect()` (`MongooseOrm.ts:74`)), donc une entité déclarée trop tard n'existe tout
+(`MongooseOrm.onConnect()` (`MongooseOrm.ts:137`)), donc une entité déclarée trop tard n'existe tout
 simplement pas. C'est aussi pour ça que `@entities` s'exécute à la phase `onRegister` et non `onBoot`.
 
 Chaque connecteur ouvre une **connexion isolée** (`mongoose.createConnection`), pas le singleton
@@ -480,8 +492,8 @@ global de Mongoose : c'est ce qui permet à plusieurs bases — voire plusieurs
 le même processus.
 
 Le service orchestre ce cycle de bout en bout : il ouvre une connexion par connecteur déclaré au
-démarrage (`MongooseService.connectAll()` (`MongooseService.ts:63`)) et referme tout à l'arrêt
-(`MongooseService.disconnectAll()` (`MongooseService.ts:178`)). Le module se déclare **non critique**
+démarrage (`MongooseService.connectAll()` (`MongooseService.ts:89`)) et referme tout à l'arrêt
+(`MongooseService.disconnectAll()` (`MongooseService.ts:195`)). Le module se déclare **non critique**
 (`Mongoose.critical` (`mongoose/index.ts:48`)) : une base injoignable ne tue pas le processus —
 l'application monte quand même, l'échec est journalisé, et c'est l'orchestrateur qui relèvera Mongo.
 
@@ -490,15 +502,15 @@ l'application monte quand même, l'échec est journalisé, et c'est l'orchestrat
 > indexées par `(connecteur, nom)` dans un registre **global au processus**. Si Drizzle (dont le
 > connecteur par défaut est `default`) et Mongoose tournaient ensemble avec le même nom, leurs deux
 > entités `session` entreraient en collision. Un nom distinct par driver règle le problème par
-> construction (`FRAMEWORK_CONNECTOR` (`registerStores.ts:49`)).
+> construction (`FRAMEWORK_CONNECTOR` (`registerStores.ts:77`)).
 
 ### Le trajet d'une requête
 
 `repo.find({ views: { $gte: 10 } }, { limit: 20 })` traverse quatre étapes :
 
-1. **Traduction du critère** (`MongooseRepository.#filter()` (`MongooseRepository.ts:184`)) : chaque
+1. **Traduction du critère** (`MongooseRepository.#filter()` (`MongooseRepository.ts:244`)) : chaque
    champ est résolu (`id` devient `_id`), chaque opérateur portable est converti.
-2. **Validation du champ** (`MongooseRepository.#resolveField()` (`MongooseRepository.ts:162`)) : un
+2. **Validation du champ** (`MongooseRepository.#resolveField()` (`MongooseRepository.ts:222`)) : un
    champ absent du schéma lève `UnknownCriteriaField` — plutôt que de renvoyer zéro résultat sans
    rien dire, ce qui est la pire façon d'échouer.
 3. **Exécution** : la requête Mongoose est construite (session transactionnelle, `populate`, `skip`,
@@ -506,7 +518,7 @@ l'application monte quand même, l'échec est journalisé, et c'est l'orchestrat
 4. **Sérialisation** : chaque document sort en objet plat, **virtuels compris** — c'est là que `id`
    apparaît.
 
-Une sonde facultative encadre l'opération (`MongooseRepository.#prof()` (`MongooseRepository.ts:79`)) :
+Une sonde facultative encadre l'opération (`MongooseRepository.#prof()` (`MongooseRepository.ts:118`)) :
 voir [Performance et mémoire](#-performance-et-mémoire).
 
 ## 🧰 Le repository portable — l'API que tu utilises vraiment
@@ -530,23 +542,24 @@ drivers. Les signatures exactes vivent dans le graphe généré
 | `withTransaction` | rejouer les mêmes opérations dans une transaction | ajoute la `session` à chaque opération |
 
 Les écritures qui « lisent puis écrivent » sont **atomiques par construction**
-(`MongooseRepository.upsert()` (`MongooseRepository.ts:343`),
-`MongooseRepository.increment()` (`MongooseRepository.ts:429`)) : un seul aller-retour, la
+(`MongooseRepository.upsert()` (`MongooseRepository.ts:405`),
+`MongooseRepository.increment()` (`MongooseRepository.ts:491`)) : un seul aller-retour, la
 comparaison est faite par le serveur. Ce n'est pas une optimisation cosmétique — c'est ce qui évite
 que deux requêtes simultanées lisent le même état et s'écrasent mutuellement.
 
 ### Les critères et leurs opérateurs
 
 Les opérateurs portables sont ceux d'[`orm-core`](../../orm-core/docs/index.md), et la plupart sont
-natifs en Mongo. Deux méritent une explication (`MongooseRepository.#mongoOps()` (`MongooseRepository.ts:127`)) :
+natifs en Mongo. Deux méritent une explication (`MongooseRepository.#mongoOps()` (`MongooseRepository.ts:173`)) :
 
-| Opérateur portable          | Côté Mongo                | Remarque                                                            |
-| --------------------------- | ------------------------- | ------------------------------------------------------------------- |
-| `$eq $ne $gt $gte $lt $lte` | identiques                | natifs                                                              |
-| `$in` / `$nin`              | identiques                | natifs                                                              |
-| `$like: "ab%"`              | `$regex` **ancrée**       | motif SQL traduit (`sqlLikeToRegex()` (`MongooseRepository.ts:25`)) |
-| `$null: true` / `false`     | `$eq: null` / `$ne: null` | en Mongo, `null` couvre aussi le champ **absent**                   |
-| `$max` / `$min` (écriture)  | `$max` / `$min` natifs    | l'équivalent du `GREATEST(col, ?)` SQL                              |
+| Opérateur portable         | Côté Mongo                | Remarque                                                            |
+| -------------------------- | ------------------------- | ------------------------------------------------------------------- |
+| `$eq $gt $gte $lt $lte`    | identiques                | natifs                                                              |
+| `$ne` / `$nin`             | `$nin` + `null`           | comme en SQL, jamais un champ absent (un `$nin` vide reste neutre)  |
+| `$in`                      | identique                 | natif                                                               |
+| `$like: "ab%"`             | `$regex` **ancrée**       | motif SQL traduit (`sqlLikeToRegex()` (`MongooseRepository.ts:25`)) |
+| `$null: true` / `false`    | `$eq: null` / `$ne: null` | en Mongo, `null` couvre aussi le champ **absent**                   |
+| `$max` / `$min` (écriture) | `$max` / `$min` natifs    | l'équivalent du `GREATEST(col, ?)` SQL                              |
 
 ```typescript
 await articles.find({ tags: "nodefony" }); // tableau : appartenance native
@@ -575,6 +588,36 @@ Le chargement se demande à la lecture : `find(criteria, { relations: ["comments
 `populate`. Le refus du `many-to-many` est volontaire : il n'a pas de traduction unique en Mongo
 (tableau de références ? collection de liaison ?), et un choix imposé serait un mauvais choix.
 
+**L'adapter tient la politique d'effacement du SQL généré.** Au `connect()`, il relève tout
+champ `ObjectId` qui porte un `ref` vers une entité de la même connexion, et chaque suppression
+d'un parent (`delete`, `deleteOne`, `findOneAndDelete`) la consulte :
+
+| La référence est…              | Supprimer le parent…                                                       |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| obligatoire (`required: true`) | est **refusé** : `ReferencedEntityError`, que le rendu HTTP traduit en 409 |
+| facultative                    | passe, et la référence de l'enfant est **remise à `null`**                 |
+
+Une entité que personne ne référence ne paie rien. Une **auto-référence** (`Category.parent`) ne
+retient pas un parent dont l'enfant part dans le même appel : l'arbre entier se supprime d'un coup.
+Une référence **sans index** est signalée au `connect()` (`WARNING`, champ nommé) : sans lui,
+chaque suppression du parent parcourt toute la collection de l'enfant. Quatre limites, à connaître :
+
+- **Hors transaction, contrôle et suppression sont deux opérations** : un enfant créé entre les
+  deux n'est pas vu. Le SQL, lui, est atomique ; dans `withTransaction`, les deux partagent la
+  session.
+- **Un tableau de références** (`[{ type: ObjectId, ref }]`) n'est pas gardé : retirer l'élément
+  n'a pas d'équivalent dans `restrict` / `set null`.
+- **La suppression douce** (`deletedAt`) est une mise à jour : elle ne déclenche rien — en SQL
+  non plus.
+- **La connexion native** (`getNativeConnection()`) contourne la garde, comme toute requête brute.
+  Et une suppression en masse charge tous les `_id` visés : c'est ce qui permet à un seul parent
+  retenu de bloquer le lot entier.
+
+> [!WARNING]
+> L'**insertion** n'est pas gardée : un enfant qui désigne un parent inexistant est accepté, et
+> `populate` rend alors `null` à sa place. Le contrat d'entrée vérifie la forme de l'identifiant,
+> pas l'existence du parent.
+
 ### Transactions
 
 ```typescript
@@ -586,22 +629,23 @@ await orm.transaction(async (tx) => {
 }); // commit si la fonction résout, annulation si elle échoue
 ```
 
-`MongooseOrm.transaction()` (`MongooseOrm.ts:483`) s'appuie sur les sessions Mongo « managées »
+`MongooseOrm.transaction()` (`MongooseOrm.ts:571`) s'appuie sur les sessions Mongo « managées »
 (commit, annulation et **reprises** gérées par le driver).
 
 > [!IMPORTANT]
 > **Les transactions exigent un replica set.** Un serveur MongoDB isolé (`mongod` seul, l'installation
 > par défaut) ne les supporte pas. En développement, démarre un replica set à un nœud ; en production,
 > Atlas et la plupart des services managés en fournissent un d'office. Les points de sauvegarde
-> intermédiaires (`savepoint`) n'existent pas en Mongo : ce sont des opérations neutres.
+> intermédiaires n'existent pas en Mongo : `savepoint()` et `rollbackTo()` lèvent
+> `SavepointNotSupportedError` — pour annuler, c'est la transaction entière qu'on abandonne.
 
 ### La trappe native — quand le contrat ne suffit plus
 
-`MongooseOrm.getNativeConnection()` (`MongooseOrm.ts:501`) rend la connexion Mongoose telle quelle :
+`MongooseOrm.getNativeConnection()` (`MongooseOrm.ts:589`) rend la connexion Mongoose telle quelle :
 agrégations, `$or`, index, `$text`, `bulkWrite`, changements de flux. Le module lui-même s'en sert
 là où le contrat portable ne suffit pas — par exemple pour la recherche texte du listing des
 webhooks, qui a besoin d'un `$or` sur deux champs
-(`MongooseWebhookStore.#listFilter()` (`MongooseWebhookStore.ts:167`)).
+(`MongooseWebhookStore.#listFilter()` (`MongooseWebhookStore.ts:195`)).
 
 C'est un **anti-blocage assumé** : le contrat portable couvre le quotidien, la trappe couvre le reste.
 Le code qui l'emprunte cesse d'être portable, et ça se voit — ce qui est exactement le but.
@@ -632,18 +676,18 @@ devient alors un pur driver de données, sans schéma framework.
 
 Trois comportements valent d'être connus :
 
-- **Purge à deux bornes** — `idleTimeoutS` et `absoluteTimeoutS` (`SessionStorage.gc()` (`SessionStorage.ts:156`)) :
+- **Purge à deux bornes** — `idleTimeoutS` et `absoluteTimeoutS` (`SessionStorage.gc()` (`SessionStorage.ts:32`)) :
   l'inactivité (depuis la dernière activité) et l'âge absolu (depuis la création, **jamais prolongé** —
   la ré-authentification finit par être imposée, conformément aux recommandations NIST/OWASP).
-- **Prolongation sans réécriture** (`SessionStorage.touch()` (`SessionStorage.ts:174`)) : rafraîchir
+- **Prolongation sans réécriture** (`SessionStorage.touch()` (`SessionStorage.ts:195`)) : rafraîchir
   l'activité ne réécrit pas le contenu de la session, juste son horodatage.
-- **Écran d'administration redacté par construction** (`SessionStorage.listPage()` (`SessionStorage.ts:277`)) :
+- **Écran d'administration redacté par construction** (`SessionStorage.listPage()` (`SessionStorage.ts:286`)) :
   le contenu applicatif et les messages flash **ne sortent pas de la base**. Studio affiche qui est
   connecté, jamais ce qu'il y a dans sa session.
 
 Quand l'ORM n'est plus connecté — typiquement pendant l'arrêt du serveur, alors que des requêtes sont
 encore en vol — le store dégrade **gracieusement** au lieu de lever une exception
-(`SessionStorage.#repo()` (`SessionStorage.ts:45`)). Une session non persistée le temps de l'arrêt
+(`SessionStorage.#repo()` (`SessionStorage.ts:66`)). Une session non persistée le temps de l'arrêt
 vaut mieux qu'une erreur 500 et un rejet non capturé.
 
 ### Utilisateurs
@@ -651,7 +695,7 @@ vaut mieux qu'une erreur 500 et un rejet non capturé.
 `MongooseUserRepository` rend des objets `BaseUser` (avec leur comportement : rôles, actif, verrouillé),
 pas des documents nus. Deux recherches lui sont propres :
 
-- **par compte social lié** (`MongooseUserRepository.findBySocialProvider()` (`MongooseUserRepository.ts:256`)) :
+- **par compte social lié** (`MongooseUserRepository.findBySocialProvider()` (`MongooseUserRepository.ts:264`)) :
   un `$elemMatch` sur un tableau libre de fournisseurs — le pendant Mongo du parcours JSON en SQL.
   C'est ce qui porte le motif « Shadow User » d'OAuth (un compte créé à la volée au premier login social),
   **sans colonne par fournisseur** : ajouter GitHub demain n'est pas une migration.
@@ -667,25 +711,25 @@ compte côté serveur — c'est le garde-fou qui empêche de supprimer le dernie
 Trois collections : les jetons eux-mêmes, la denylist de `jti`, les seuils de révocation par porteur.
 Deux invariants de sécurité sont tenus **par la requête**, pas par du code JavaScript entre deux appels :
 
-- **Révocation idempotente** (`MongooseTokenStore.revoke()` (`MongooseTokenStore.ts:215`)) : la
+- **Révocation idempotente** (`MongooseTokenStore.revoke()` (`MongooseTokenStore.ts:275`)) : la
   condition « pas encore révoqué » est dans le filtre. Deux révocations simultanées ne se recouvrent
   pas ; la première date et la première raison sont conservées.
-- **Seuil monotone** (`MongooseTokenStore.revokeAllForSubject()` (`MongooseTokenStore.ts:297`)) : le
+- **Seuil monotone** (`MongooseTokenStore.revokeAllForSubject()` (`MongooseTokenStore.ts:334`)) : le
   « déconnecte-moi de partout » utilise `$max`. Avec une lecture suivie d'une écriture, deux
   déconnexions simultanées pourraient reposer un seuil **plus ancien** — et des jetons révoqués
   redeviendraient valides. Ici, c'est structurellement impossible.
 
-La purge, bornée par `retentionRevokedMs` (`MongooseTokenStore.gc()` (`MongooseTokenStore.ts:313`)), s'appuie sur une particularité utile
+La purge, bornée par `retentionRevokedMs` (`MongooseTokenStore.gc()` (`MongooseTokenStore.ts:350`)), s'appuie sur une particularité utile
 de Mongo : une comparaison numérique **ignore** les documents dont le champ est `null`. Les jetons sans
 expiration ne sont donc jamais balayés par erreur ; ils partent par une règle de rétention distincte.
 
 ### Passkeys
 
 Une collection, l'identifiant du credential en clé primaire. L'enregistrement passe par un `upsert`
-atomique (`MongooseWebAuthnCredentialStore.save()` (`MongooseWebAuthnCredentialStore.ts:94`)) : deux
+atomique (`MongooseWebAuthnCredentialStore.save()` (`MongooseWebAuthnCredentialStore.ts:109`)) : deux
 enregistrements concurrents de la même passkey ne peuvent pas produire de collision de clé.
 
-Le listing d'administration (`MongooseWebAuthnCredentialStore.listPage()` (`MongooseWebAuthnCredentialStore.ts:158`))
+Le listing d'administration (`MongooseWebAuthnCredentialStore.listPage()` (`MongooseWebAuthnCredentialStore.ts:173`))
 projette **sans la clé publique** — elle ne franchit jamais la frontière du store. La recherche libre
 est un **préfixe ancré**, pas une expression régulière fournie par l'appelant : une recherche
 utilisateur n'est jamais interprétée comme du code.
@@ -693,12 +737,12 @@ utilisateur n'est jamais interprétée comme du code.
 ### Webhooks
 
 Registre **durable** des destinations à notifier, par opposition au store mémoire qui disparaît au
-redémarrage. Le listing paginé (`MongooseWebhookStore.listPage()` (`MongooseWebhookStore.ts:188`))
+redémarrage. Le listing paginé (`MongooseWebhookStore.listPage()` (`MongooseWebhookStore.ts:227`))
 lit `limit + 1` documents pour savoir s'il existe une page suivante — sans second comptage — et
 échappe les métacaractères de la recherche texte.
 
 Détail révélateur de la doctrine du framework : si le store est construit sans modèle natif, le
-listing paginé **refuse** de répondre (`MongooseWebhookStore.#nativeModel()` (`MongooseWebhookStore.ts:151`))
+listing paginé **refuse** de répondre (`MongooseWebhookStore.#nativeModel()` (`MongooseWebhookStore.ts:179`))
 au lieu de retomber sur un chargement complet de la collection. Une garantie silencieusement trahie
 serait pire qu'une erreur.
 
@@ -740,7 +784,7 @@ natif.
 **Les horodatages sont des nombres, pas des dates.** Les contrats du framework portent des `number`
 (millisecondes depuis l'époque) : les stocker tels quels garde la logique de purge **strictement
 identique** à celle de l'adapter SQL. Seule l'entité `User` utilise la gestion automatique de Mongoose
-(`createUserEntity()` (`userEntity.ts:90`)), parce que son contrat porte des dates.
+(`createUserEntity()` (`userEntity.ts:104`)), parce que son contrat porte des dates.
 
 Le contrat expose partout `id: string`, jamais un `ObjectId` : le champ virtuel `id` est activé à la
 sérialisation, sur toutes les entités compilées par l'adapter.
@@ -757,7 +801,7 @@ heures plus tard.
 | `debug`             | trace toutes les opérations Mongoose (développement)           | `false`                                 |
 | `frameworkEntities` | déclare le schéma framework et rend ses stores sélectionnables | `true`                                  |
 
-Les valeurs font foi dans le schéma (`mongooseConfigSchema` (`config.ts:83`)) ; la surcharge par
+Les valeurs font foi dans le schéma (`mongooseConfigSchema` (`config.ts:98`)) ; la surcharge par
 l'environnement est appliquée **après** la validation
 (`applyEnvOverrides()` (`defineModuleConfig.ts:22`)), ce qui garde le schéma pur et publiable en
 JSON Schema pour Studio.
@@ -785,15 +829,15 @@ Schema). Le module fournit les sondes correspondantes :
 
 | Sonde                  | Ce qu'elle renvoie                                                          |
 | ---------------------- | --------------------------------------------------------------------------- |
-| `ping()`               | un aller-retour réel vers la base (`MongooseOrm.ts:515`)                    |
-| `probe()`              | les connexions du serveur et sa version (`MongooseOrm.ts:529`)              |
-| `describeEntity()`     | les champs d'une entité, depuis le schéma compilé (`MongooseOrm.ts:558`)    |
-| `describeConnection()` | le pilote, la cible et la version de la bibliothèque (`MongooseOrm.ts:583`) |
+| `ping()`               | un aller-retour réel vers la base (`MongooseOrm.ts:603`)                    |
+| `probe()`              | les connexions du serveur et sa version (`MongooseOrm.ts:617`)              |
+| `describeEntity()`     | les champs d'une entité, depuis le schéma compilé (`MongooseOrm.ts:649`)    |
+| `describeConnection()` | le pilote, la cible et la version de la bibliothèque (`MongooseOrm.ts:676`) |
 
 > [!IMPORTANT]
 > **Aucun identifiant ne sort jamais.** La cible affichée est nettoyée de tout `utilisateur:mot de
 passe@` avant d'atteindre le plan d'administration ou les journaux
-> (`MongooseOrm.safeTarget()` (`MongooseOrm.ts:432`)), y compris pour les URI multi-hôtes que
+> (`MongooseOrm.safeTarget()` (`MongooseOrm.ts:688`)), y compris pour les URI multi-hôtes que
 > l'analyseur d'URL standard ne sait pas découper.
 
 ## ⚡ Performance et mémoire
@@ -803,10 +847,10 @@ Le module suit la règle de fond du framework : **ce qui n'est pas observé ne c
 - **Instrumentation à coût nul hors observation.** Chaque opération peut alimenter deux sondes (le
   profil par requête de la barre de debug, et le flux agrégé). Les deux drapeaux sont lus **avant**
   toute allocation, et la description de la requête n'est construite que si l'on regarde
-  (`MongooseRepository.#prof()` (`MongooseRepository.ts:79`)). En production, le chemin est celui d'un
+  (`MongooseRepository.#prof()` (`MongooseRepository.ts:118`)). En production, le chemin est celui d'un
   appel direct.
 - **Repositories alloués à la demande.** Le cache est créé au premier accès, pas à la connexion
-  (`MongooseOrm.getRepository()` (`MongooseOrm.ts:465`)).
+  (`MongooseOrm.getRepository()` (`MongooseOrm.ts:548`)).
 - **Un aller-retour par écriture.** Les opérations « lire puis écrire » sont exprimées en une seule
   requête atomique — moins de latence _et_ pas de course.
 - **Le comptage reste côté serveur.** Les listings paginés lisent `limit + 1` documents pour savoir
@@ -827,7 +871,7 @@ Le module suit la règle de fond du framework : **ce qui n'est pas observé ne c
 | `many-to-many non portable`                                  | Refus explicite : pas de traduction unique en Mongo                           | Déclarer la relation via la connexion native                                      |
 | Les sessions disparaissent au redémarrage                    | `session.store` resté sur `memory`                                            | `session: { store: "mongoose" }`, ou déclarer `NF_DATABASE_URL` et laisser `auto` |
 | `audit store "mongoose" inconnu` — boot avorté en production | Brique **non portée** par Mongo, sélectionnée explicitement                   | Laisser `auto` (repli annoncé) ou choisir un backend qui la porte                 |
-| Les comptes ne survivent pas au redémarrage                  | `provisionUsers` toujours branché sur l'annuaire mémoire                      | Câbler `MongooseUserRepository.from(orm)` (`MongooseUserRepository.ts:74`)        |
+| Les comptes ne survivent pas au redémarrage                  | `provisionUsers` toujours branché sur l'annuaire mémoire                      | Câbler `MongooseUserRepository.from(orm)` (`MongooseUserRepository.ts:89`)        |
 | Un champ écrit se relit `undefined`, sans aucune erreur      | Il n'est pas dans le **schéma** : Mongoose est strict et l'écarte en silence  | L'ajouter au schéma de l'entité — le type TypeScript seul ne suffit pas           |
 | Le premier `npm test` du module met une éternité             | Le serveur Mongo de test télécharge son binaire (une seule fois)              | Définir `NF_MONGO_TEST_URI` sur un conteneur Mongo                                |