@nodefony/mongoose 10.0.0-alpha.8 → 10.0.0-beta.1

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:104`)) et referme tout à l'arrêt
+(`MongooseService.disconnectAll()` (`MongooseService.ts:210`)). 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:256`)) : 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
@@ -527,26 +539,28 @@ drivers. Les signatures exactes vivent dans le graphe généré
 | `delete` / `deleteOne` | supprimer | `deleteMany` / `deleteOne` |
 | `findOneAndDelete` | supprimer **et** récupérer le document | `findOneAndDelete` |
 | `count` / `exists` | compter / tester l'existence | `countDocuments` / `exists` |
+| `countDistinct` | compter les valeurs distinctes et non nulles d'un champ | agrégation `$match` → `$group` → `$count` |
 | `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:422`),
+`MongooseRepository.increment()` (`MongooseRepository.ts:507`)) : 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 +589,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 +630,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.
@@ -613,13 +658,16 @@ contrat est importé en `import type` (effacé à la compilation), et c'est le d
 auprès du module consommateur. Le module met en place tout ce câblage à son enregistrement, avant que
 la connexion ne s'ouvre.
 
-| Store        | Contrat                    | Comment le choisir                  | Collections                                        |
-| ------------ | -------------------------- | ----------------------------------- | -------------------------------------------------- |
-| Sessions     | `ISessionStorage` (http)   | `session: { store: "mongoose" }`    | `session`                                          |
-| Utilisateurs | `IUserRepository` (user)   | via `provisionUsers` de ton app     | `User`                                             |
-| Jetons       | `ITokenStore` (security)   | `tokenStore: { store: "mongoose" }` | `access_token`, `denied_jti`, `subject_revocation` |
-| Passkeys     | `IWebAuthnCredentialStore` | `passkeys: { store: "mongoose" }`   | `webauthn_credential`                              |
-| Webhooks     | `IWebhookStore`            | `webhooks: { store: "mongoose" }`   | `webhook_endpoint`                                 |
+| Store        | Contrat                       | Comment le choisir                               | Collections                                        |
+| ------------ | ----------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| Sessions     | `ISessionStorage` (http)      | `session: { store: "mongoose" }`                 | `session`                                          |
+| Utilisateurs | `IUserRepository` (user)      | via `provisionUsers` de ton app                  | `User`                                             |
+| Jetons       | `ITokenStore` (security)      | `tokenStore: { store: "mongoose" }`              | `access_token`, `denied_jti`, `subject_revocation` |
+| Passkeys     | `IWebAuthnCredentialStore`    | `passkeys: { store: "mongoose" }`                | `webauthn_credential`                              |
+| Webhooks     | `IWebhookStore`               | `webhooks: { store: "mongoose" }`                | `webhook_endpoint`                                 |
+| 2FA (TOTP)   | `ITotpSecretStore` (security) | `totp: { store: "mongoose" }`                    | `totp_secret`                                      |
+| Audit        | `IAuditStore` (security)      | `audit: { store: "mongoose" }`                   | `audit_event`                                      |
+| Idempotence  | `IIdempotencyStore` (cœur)    | `idempotency: { store: "mongoose" }` (framework) | `idempotency_key`                                  |
 
 L'auto-enregistrement peut être coupé (`frameworkEntities: false` (`config.ts:102`)) : le module
 devient alors un pur driver de données, sans schéma framework.
@@ -632,18 +680,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:163`)) :
   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,15 +699,15 @@ 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:238`)) :
   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.
-- **listing paginé** (`MongooseUserRepository.listPage()` (`MongooseUserRepository.ts:299`)) : requête
+- **listing paginé** (`MongooseUserRepository.listPage()` (`MongooseUserRepository.ts:281`)) : requête
   native bornée (`skip`/`limit + 1`), tri sur liste blanche, `_id` en départage. Une page est une page,
   jamais la collection entière rapatriée en mémoire.
 
-Le comptage des administrateurs actifs (`MongooseUserRepository.countActiveAdmins()` (`MongooseUserRepository.ts:354`))
+Le comptage des administrateurs actifs (`MongooseUserRepository.countActiveAdmins()` (`MongooseUserRepository.ts:328`))
 compte côté serveur — c'est le garde-fou qui empêche de supprimer le dernier administrateur.
 
 ### Jetons
@@ -667,25 +715,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:356`)), 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,18 +741,18 @@ 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.
 
 ## 🗃 Ce qui est stocké
 
-Les cinq schémas portés par le module. Les collections sont créées à la volée par MongoDB — il n'y a
+Les schémas portés par le module — dix collections. Les collections sont créées à la volée par MongoDB — il n'y a
 ni migration ni DDL à jouer, ce qui est l'un des vrais conforts du modèle documentaire.
 
 > ⚠️ **Le revers de ce confort : ce qui n'est pas déclaré est JETÉ, sans un mot.** Mongoose valide en
@@ -719,15 +767,18 @@ ni migration ni DDL à jouer, ce qui est l'un des vrais conforts du modèle docu
 > partagé (`USER_COLUMNS`), et le module en dérive un schéma Mongoose. Un champ métier que tu ajoutes
 > à ton utilisateur suit le même chemin — déclaré, donc écrit ; oublié, donc perdu en silence.
 
-| Collection            | Clé primaire (`_id`)         | Contenu                                                            | Horodatages        |
-| --------------------- | ---------------------------- | ------------------------------------------------------------------ | ------------------ |
-| `session`             | `ObjectId` (auto)            | identifiant de session, contenu, messages flash, méta, utilisateur | nombres (ms)       |
-| `User`                | `ObjectId` (auto)            | identifiant, mot de passe haché, rôles, comptes sociaux, méta      | gérés par Mongoose |
-| `access_token`        | le `jti` (texte)             | type, porteur, périmètres, empreinte du secret, révocation         | nombres (ms)       |
-| `denied_jti`          | le `jti` (texte)             | expiration                                                         | nombres (ms)       |
-| `subject_revocation`  | le porteur (texte)           | seuil `invalidBefore`                                              | nombres (ms)       |
-| `webauthn_credential` | l'identifiant du credential  | clé publique, compteur, transports, état de sauvegarde             | nombres (ms)       |
-| `webhook_endpoint`    | l'identifiant `wh_…` (texte) | URL, secret chiffré, événements, état des livraisons               | nombres (ms)       |
+| Collection            | Clé primaire (`_id`)                   | Contenu                                                                              | Horodatages        |
+| --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
+| `session`             | `ObjectId` (auto)                      | identifiant de session, contenu, messages flash, méta, utilisateur                   | nombres (ms)       |
+| `User`                | `ObjectId` (auto)                      | identifiant, mot de passe haché, rôles, comptes sociaux, méta                        | gérés par Mongoose |
+| `access_token`        | le `jti` (texte)                       | type, porteur, périmètres, empreinte du secret, révocation                           | nombres (ms)       |
+| `denied_jti`          | le `jti` (texte)                       | expiration                                                                           | nombres (ms)       |
+| `subject_revocation`  | le porteur (texte)                     | seuil `invalidBefore`                                                                | nombres (ms)       |
+| `webauthn_credential` | l'identifiant du credential            | clé publique, compteur, transports, état de sauvegarde                               | nombres (ms)       |
+| `webhook_endpoint`    | l'identifiant `wh_…` (texte)           | URL, secret chiffré, événements, état des livraisons                                 | nombres (ms)       |
+| `totp_secret`         | l'identifiant de l'utilisateur (texte) | secret chiffré, algorithme, chiffres, période, codes de secours, dernier pas utilisé | nombres (ms)       |
+| `audit_event`         | l'identifiant d'événement (texte)      | catégorie, action, issue, acteur, ressource, raison, IP, requête                     | nombre (`ts`, ms)  |
+| `idempotency_key`     | la clé d'idempotence (texte)           | empreinte de la requête, état, réponse rejouée                                       | expiration (ms)    |
 
 Deux choix structurants s'y lisent :
 
@@ -740,7 +791,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 +808,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 +836,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 +854,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 +878,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                                |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/mongoose",
-  "version": "10.0.0-alpha.8",
+  "version": "10.0.0-beta.1",
   "description": "Moteur MongoDB de Nodefony sur Mongoose : dépôts typés conformes au contrat orm-core",
   "nodefony": {
     "storeKind": "durable",
@@ -9,7 +9,10 @@
       "user",
       "tokens",
       "passkeys",
-      "webhooks"
+      "totp",
+      "audit",
+      "webhooks",
+      "idempotency"
     ]
   },
   "contributors": [],
@@ -25,9 +28,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"
@@ -47,27 +50,28 @@
   ],
   "dependencies": {
     "mongodb": "7.6.0",
-    "mongoose": "9.10.1",
+    "mongoose": "9.10.2",
     "tslib": "2.8.1",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.8",
-    "@nodefony/orm-core": "^10.0.0-alpha.8",
-    "@nodefony/security": "^10.0.0-alpha.8",
-    "@nodefony/user": "^10.0.0-alpha.8",
-    "@types/node": "26.6.2",
-    "mongodb-memory-server": "11.2.0",
-    "nodefony": "^10.0.0-alpha.8",
-    "rimraf": "6.1.3",
-    "vitest": "5.0.1"
+    "@nodefony/framework": "^10.0.0-beta.1",
+    "@nodefony/http": "^10.0.0-beta.1",
+    "@nodefony/orm-core": "^10.0.0-beta.1",
+    "@nodefony/security": "^10.0.0-beta.1",
+    "@nodefony/user": "^10.0.0-beta.1",
+    "@types/node": "26.6.3",
+    "mongodb-memory-server": "11.3.0",
+    "nodefony": "^10.0.0-beta.1",
+    "vitest": "5.0.2"
   },
   "peerDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.8",
-    "@nodefony/orm-core": "^10.0.0-alpha.8",
-    "@nodefony/security": "^10.0.0-alpha.8",
-    "@nodefony/user": "^10.0.0-alpha.8",
-    "nodefony": "^10.0.0-alpha.8"
+    "@nodefony/framework": "^10.0.0-beta.1",
+    "@nodefony/http": "^10.0.0-beta.1",
+    "@nodefony/orm-core": "^10.0.0-beta.1",
+    "@nodefony/security": "^10.0.0-beta.1",
+    "@nodefony/user": "^10.0.0-beta.1",
+    "nodefony": "^10.0.0-beta.1"
   },
   "repository": {
     "type": "git",