@nodefony/drizzle 10.0.0-alpha.7 → 10.0.0-alpha.9

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

@@ -0,0 +1,96 @@
+/**
+ * Ordre de création des tables, et contraintes qu'il faut renoncer à poser.
+ *
+ * Module **pur** (aucune base, aucun Drizzle) : c'est la seule partie du DDL
+ * dérivé qui demande un raisonnement, donc la seule qui mérite d'être éprouvée
+ * sans serveur — un cycle entre entités ne se reproduit pas à la demande sur une
+ * base réelle.
+ *
+ * Une clé étrangère se déclare **dans** le `CREATE TABLE` : la table visée doit
+ * donc exister AVANT celle qui la désigne. Un ordre quelconque échoue sur la
+ * première relation rencontrée, et l'application ne démarre pas.
+ */
+/**
+ * Une clé étrangère RÉSOLUE en noms SQL — prête à être écrite dans un
+ * `CREATE TABLE`, sans plus aucune référence à un objet Drizzle.
+ */
+export interface IResolvedForeignKey {
+    /** Nom de la contrainte — explicite, car MySQL l'exige unique pour la base. */
+    readonly name: string;
+    /** Colonnes porteuses, côté table courante. */
+    readonly columns: readonly string[];
+    /** Table visée. */
+    readonly foreignTable: string;
+    /** Colonnes visées, dans le même ordre que {@link columns}. */
+    readonly foreignColumns: readonly string[];
+    /** Politique d'effacement du parent (`restrict`, `set null`, `cascade`…). */
+    readonly onDelete?: string;
+    /** Politique de mise à jour de la clé du parent. */
+    readonly onUpdate?: string;
+}
+/** Une table à créer, et les tables que ses clés étrangères désignent. */
+export interface ITableDependency {
+    /** Nom SQL de la table. */
+    readonly name: string;
+    /**
+     * Tables visées par ses clés étrangères, dans l'ordre de déclaration.
+     *
+     * Une table peut y figurer plusieurs fois (deux colonnes vers la même cible) ;
+     * elle peut aussi s'y désigner elle-même, ce qui ne crée aucune dépendance.
+     */
+    readonly references: readonly string[];
+}
+/** Une contrainte qu'on renonce à poser, et la raison qui le commande. */
+export interface IOmittedForeignKey {
+    /** Table qui porte la clé étrangère. */
+    readonly table: string;
+    /** Table visée. */
+    readonly target: string;
+    /**
+     * `cycle` : la cible dépend à son tour de cette table, directement ou non —
+     * aucun ordre de création ne satisfait les deux.
+     * `absent` : la cible n'appartient pas à ce connecteur, donc à cette base.
+     */
+    readonly reason: "cycle" | "absent";
+}
+/** Ordre de création, et ce qu'il a fallu abandonner en chemin. */
+export interface IDdlPlan {
+    /** Noms des tables, dans l'ordre où les créer. */
+    readonly order: readonly string[];
+    /** Clés étrangères non émises — jamais silencieuses, l'appelant les journalise. */
+    readonly omitted: readonly IOmittedForeignKey[];
+}
+/**
+ * Trie les tables pour que chaque cible naisse avant qui la désigne.
+ *
+ * Tri topologique (Kahn) sur le graphe des dépendances, avec deux écarts
+ * assumés au manuel :
+ *
+ * - **l'auto-référence ne compte pas** (`parent:ref:Category` dans `Category`) :
+ *   les trois moteurs acceptent une contrainte qui vise la table en cours de
+ *   création, dans le même `CREATE TABLE` ;
+ * - **un cycle ne fait pas échouer le démarrage**. Il n'y a aucun ordre correct,
+ *   mais refuser de démarrer pour ça serait hors de proportion : on crée les
+ *   tables du cycle dans un ordre stable, et on OMET les contraintes qui
+ *   regardent en arrière. Elles sont rendues à l'appelant pour qu'il les dise —
+ *   une garantie qui disparaît sans un mot est pire que son absence.
+ *
+ * À ordre de sortie stable : les tables prêtes sont prises par ordre
+ * alphabétique, jamais dans l'ordre d'arrivée. Deux démarrages de la même
+ * application produisent donc le même DDL, ce qui rend un journal comparable.
+ *
+ * @param tables - les tables du connecteur et leurs cibles.
+ * @returns l'ordre de création et les contraintes abandonnées.
+ */
+export declare function planTableCreation(tables: readonly ITableDependency[]): IDdlPlan;
+/**
+ * Met en mots les contraintes abandonnées — le message que l'appelant journalise.
+ *
+ * Écrit pour être lu par celui qui découvre le problème dans ses journaux : il
+ * nomme les tables, la cause, et ce qu'il reste à faire. Un avertissement qui ne
+ * dit pas quoi faire se relit deux fois puis s'ignore.
+ *
+ * @param omitted - les contraintes non émises.
+ * @returns le texte à journaliser, ou `null` s'il n'y a rien à dire.
+ */
+export declare function explainOmittedForeignKeys(omitted: readonly IOmittedForeignKey[]): string | null;

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

@@ -9,3 +9,4 @@ export type { DrizzleOrmOptions } from "./DrizzleOrm.js";
 export { DrizzleRepository } from "./DrizzleRepository.js";
 export type { DrizzleDb, DrizzleTable, DrizzleColumn, DrizzleResolvedRelation, } from "./DrizzleRepository.js";
 export { DrizzleTransaction } from "./DrizzleTransaction.js";
+export { seedEntityRow } from "./seedRow.js";

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

@@ -0,0 +1,23 @@
+import type { IEntity } from "@nodefony/orm-core";
+import type { DrizzleOrm } from "./DrizzleOrm.js";
+/**
+ * Insère une ligne minimale dans la table d'une entité, et rend son identifiant.
+ *
+ * Destiné aux **tests** : dès qu'une entité porte une relation (`author:ref:Author`),
+ * sa colonne est une vraie clé étrangère, et la base REFUSE un identifiant
+ * inventé. La ligne parente doit donc exister avant toute insertion — et c'est
+ * la seule façon d'éprouver la contrainte au lieu de la contourner (débrancher
+ * `foreign_keys` rendrait le test vert sans rien prouver).
+ *
+ * Ce qui est rempli : les colonnes **obligatoires sans valeur par défaut**, avec
+ * une valeur du type que Drizzle déclare. Le reste est laissé au schéma — une
+ * clé primaire auto-générée, un horodatage, un défaut applicatif se posent seuls.
+ *
+ * @param orm - la connexion sur laquelle semer.
+ * @param entity - l'entité cible ; son `schema` est la table Drizzle.
+ * @returns l'identifiant de la ligne créée, à poser dans la colonne qui la désigne.
+ * @throws Si la cible porte elle-même une clé étrangère obligatoire — le semis à
+ *   un seul étage ne sait pas la satisfaire, et le message le dit plutôt que de
+ *   laisser remonter un « FOREIGN KEY constraint failed » sans contexte.
+ */
+export declare function seedEntityRow(orm: DrizzleOrm, entity: IEntity): Promise<string | number>;

package/docs/index.md

@@ -342,10 +342,10 @@ de drizzle qui sert de modèle. Deux fichiers, mêmes noms partout, aucune quest
 | `nodefony/config/config.ts`             | **le QUOI**    | schéma Zod commenté = source **unique** des défauts, matérialisés `parse({})` |
 | `nodefony/config/defineModuleConfig.ts` | **le COMMENT** | builder **pur** : parse → surcharge d'environnement → gel                     |
 
-Concrètement : `drizzleConfigSchema` (`config.ts:79`) porte chaque `.default()` et chaque
+Concrètement : `drizzleConfigSchema` (`config.ts:136`) porte chaque `.default()` et chaque
 `.describe()` — changer un défaut du module, c'est éditer **là et nulle part ailleurs**. Le builder
-`defineDrizzleConfig()` (`defineModuleConfig.ts:58`) ne retape jamais une valeur : il valide, applique
-l'environnement, gèle. Et `drizzleConfigJsonSchema()` (`defineModuleConfig.ts:69`) expose le tout en
+`defineDrizzleConfig()` (`defineModuleConfig.ts:81`) ne retape jamais une valeur : il valide, applique
+l'environnement, gèle. Et `drizzleConfigJsonSchema()` (`defineModuleConfig.ts:99`) expose le tout en
 JSON Schema pour l'écran de configuration de Studio.
 
 Le schéma reste **pur** : il ne lit ni `process.env` ni le kernel. C'est ce qui rend le module
@@ -361,11 +361,11 @@ importable et testable sans serveur.
 | `connectors.<n>.url`      | `string`                            | —                  | Chaîne de connexion `postgres://…` / `mysql://…`. **Porte un secret.** |
 | `frameworkEntities`       | `boolean`                           | `true`             | Déclare (ou non) le schéma des huit briques durables sur `default`.    |
 
-Table dérivée de `drizzleConfigSchema` (`config.ts:79`) et de `SQL_DIALECTS` (`config.ts:37`).
+Table dérivée de `drizzleConfigSchema` (`config.ts:136`) et de `SQL_DIALECTS` (`config.ts:37`).
 
 **`filename` est volontairement sans défaut.** Le chemin dépend du kernel, qui n'existe pas quand le
 schéma est évalué. Il est résolu **au démarrage** par `DrizzleService.#defaultFilename()`
-(`DrizzleService.ts:95`) vers `<app>/var/databases/nodefony-<connecteur>.db` — sous `var/`, le dossier
+(`DrizzleService.ts:202`) vers `<app>/var/databases/nodefony-<connecteur>.db` — sous `var/`, le dossier
 commun des données runtime : « où sont mes données ? » a une réponse unique, un seul chemin à
 sauvegarder et à ignorer dans git.
 
@@ -385,9 +385,12 @@ NF_DATABASE_URL=mysql://app:secret@db:3306/prod
 NF_DATABASE_URL=sqlite:/var/lib/app/prod.db
 ```
 
-`applyEnvOverrides()` (`defineModuleConfig.ts:20`) lit l'infra, en déduit le dialecte depuis le
-_scheme_, et pose `filename` ou `url` sur le connecteur primaire. Une URL `mongodb://` est **ignorée
-ici** : elle appartient alors à `@nodefony/mongoose`.
+`applyEnvOverrides()` (`defineModuleConfig.ts:32`) lit l'infra, en déduit le dialecte depuis le
+_scheme_, et pose `filename` ou `url` sur le connecteur primaire. Une URL `mongodb://` n'est **pas
+lue ici** : elle appartient à `@nodefony/mongoose`. Drizzle en tire aussi la conséquence — il ne crée
+**pas** le connecteur `default` que ses défauts posent, donc aucune base SQLite parallèle et aucun
+schéma du framework en double. Un `default` que l'application écrit elle-même dans
+`use("@nodefony/drizzle", { connectors: { default: … } })` est gardé, comme tout autre connecteur.
 
 **Situation 3 — plusieurs bases.** Un connecteur par base. Seul `default` porte le schéma du framework ;
 les autres sont à toi.
@@ -403,13 +406,13 @@ use("@nodefony/drizzle", {
 
 > [!WARNING]
 > Une URL de connexion **porte un mot de passe**. Le module ne la journalise jamais telle quelle :
-> `redactUrl()` (`DrizzleService.ts:68`) remplace le mot de passe par `***` avant tout log de
+> `redactUrl()` (`DrizzleService.ts:86`) remplace le mot de passe par `***` avant tout log de
 > démarrage, et la sonde d'administration applique la même règle.
 
 ### Quand la connexion échoue, le démarrage échoue
 
 Un connecteur **déclaré** qui ne se connecte pas lève une `BootConfigurationError`
-(`DrizzleService.ts:244`) — en développement **comme** en production. Ce n'est pas une sévérité
+(`DrizzleService.ts:340`) — en développement **comme** en production. Ce n'est pas une sévérité
 gratuite : une infrastructure déclarée mais injoignable ne se répare pas en continuant. Un serveur qui
 démarrerait « vivant » avec ses stores morts accepterait des requêtes pour échouer plus tard, la cause
 noyée dans un avertissement. Le message d'erreur nomme le connecteur, le dialecte, la cible rédigée et
@@ -417,7 +420,7 @@ la piste à vérifier.
 
 Pour les dialectes réseau, la connexion fait un **ping réel** au démarrage : les pools `pg` et `mysql2`
 sont paresseux, sans ce `SELECT 1` une base morte « se connecterait » et n'échouerait qu'à la première
-requête métier (`#connectPostgres()`, `DrizzleOrm.ts:998` · `#connectMysql()`, `DrizzleOrm.ts:1296`).
+requête métier (`#connectPostgres()`, `DrizzleOrm.ts:1193` · `#connectMysql()`, `DrizzleOrm.ts:1504`).
 
 ## Dialectes — une base par déploiement, un seul code
 
@@ -464,7 +467,7 @@ En MySQL, les verbes « qui rendent la ligne écrite » (`create`, `updateOne`,
 `findOneAndDelete`) se décomposent en sélection de la cible → mutation bornée par la clé primaire **avec
 le critère revérifié dans le `WHERE`** → relecture. Deux à trois allers-retours au lieu d'un : c'est le
 prix du dialecte, payé **uniquement** en MySQL. Une course perdue rend `null`, jamais une mutation hors
-critère (`#mysqlInsertReturning()`, `DrizzleRepository.ts:1138`).
+critère (`#mysqlInsertReturning()`, `DrizzleRepository.ts:1149`).
 
 Le SQL brut nécessaire aux entités du framework est lui aussi routé par dialecte, dans un seul fichier
 (`queryKit.ts`) : recherche dans une colonne JSON (`findUserIdBySocialProvider()`, `queryKit.ts:76`),
@@ -504,7 +507,7 @@ connexion**, donc leurs tables sont créées au moment où l'ORM s'ouvre.
 | Pièce                  | Rôle                                                                   | Ancre                                                        |
 | ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
 | `Drizzle` (le module)  | valide la config, déclare le schéma framework, monte le data plane     | `index.ts` du module                                         |
-| `DrizzleService`       | ouvre un ORM par connecteur au boot, ferme tout à l'arrêt              | `connectAll()`, `DrizzleService.ts:148`                      |
+| `DrizzleService`       | ouvre un ORM par connecteur au boot, ferme tout à l'arrêt              | `connectAll()`, `DrizzleService.ts:186`                      |
 | `DrizzleOrm`           | la connexion : DDL dérivé, repositories, transactions, sonde           | `DrizzleOrm.ts:214`                                          |
 | `DrizzleRepository<T>` | le CRUD portable, les opérateurs riches, l'eager-load                  | `DrizzleRepository.ts:146`                                   |
 | `DrizzleTransaction`   | `BEGIN`/`COMMIT`/`ROLLBACK` pilotés à la main, sur les trois dialectes | `DrizzleTransaction.ts:70`                                   |
@@ -515,7 +518,7 @@ connexion**, donc leurs tables sont créées au moment où l'ORM s'ouvre.
 ### Le DDL dérivé — comment les tables apparaissent
 
 Drizzle ne « synchronise » pas un schéma. L'adapter dérive lui-même un `CREATE TABLE IF NOT EXISTS`
-depuis chaque table déclarée (`#buildCreateTable()`, `DrizzleOrm.ts:400`) et l'exécute à la connexion.
+depuis chaque table déclarée (`#buildCreateTable()`, `DrizzleOrm.ts:509`) et l'exécute à la connexion.
 Trois conséquences à connaître **avant** de dépendre de ce mécanisme :
 
 1. il **crée**, il ne **modifie** pas — aucun `ALTER` n'est émis ;
@@ -571,7 +574,7 @@ Deux points de comportement qui évitent des surprises :
   `UPDATE` (`#pickOne()`, `DrizzleRepository.ts:259`). C'est ce qui rend ces verbes portables — MySQL
   interdit la forme naïve.
 - **l'eager-load est manuel** : une requête `IN (…)` par relation déclarée, puis regroupement en
-  mémoire (`#populate()`, `DrizzleRepository.ts:683`). Choix assumé — pas de couche de relations à
+  mémoire (`#populate()`, `DrizzleRepository.ts:694`). Choix assumé — pas de couche de relations à
   déclarer une seconde fois, et le comportement est le même sur les trois dialectes.
 
 ### Transactions — une connexion dédiée, jamais le pool
@@ -600,7 +603,7 @@ Le mécanisme diffère par dialecte, sans que ton code le voie : en PostgreSQL/M
 emprunte une connexion **dédiée** au pool, rendue au commit — et **détruite** si celui-ci échoue,
 jamais recyclée dans un état inconnu. En SQLite la connexion est unique, donc c'est un pool de taille 1 :
 les transactions concurrentes sont **sérialisées par une file d'attente** (`#sqliteTxGate`,
-`DrizzleOrm.ts:267`), sinon deux requêtes HTTP simultanées émettraient deux `BEGIN` sur la même
+`DrizzleOrm.ts:360`), sinon deux requêtes HTTP simultanées émettraient deux `BEGIN` sur la même
 connexion et la seconde échouerait.
 
 Les points de sauvegarde sont disponibles (`savepoint()`, `DrizzleTransaction.ts:123`) ; le nom est
@@ -624,7 +627,7 @@ const rows = await db.all(sql`
 `);
 ```
 
-C'est l'**anti-blocage** du modèle Repository (`getNativeConnection()`, `DrizzleOrm.ts:1524`) : CTE,
+C'est l'**anti-blocage** du modèle Repository (`getNativeConnection()`, `DrizzleOrm.ts:1745`) : CTE,
 fonctions de fenêtre, sous-requêtes corrélées, jointures arbitraires. Deux contreparties assumées :
 ce SQL n'est plus portable entre dialectes, et il **ne passe pas** par la sonde de profilage des
 requêtes.
@@ -653,7 +656,7 @@ ou l'idempotence (`createIdempotencyTable`, `idempotencyEntity.ts:85`).
 ### Comment ça s'active — la réponse est : tout seul
 
 Chaque brique choisit son backend par une option `store`, dont le **défaut est `"auto"`**. La
-résolution automatique (`resolveAutoStore()`, `infra.ts:241`) applique cette préférence :
+résolution automatique (`resolveAutoStore()`, `infra.ts:297`) applique cette préférence :
 
 1. une infra `database` déclarée (`NF_DATABASE_URL`) → **`drizzle`** (ou `mongoose` si l'URL est Mongo) ;
 2. sinon, un backend local persistant réellement chargé → **`drizzle`**, c'est-à-dire SQLite ;
@@ -714,8 +717,8 @@ construction : ils la résolvent à chaque appel. C'est nécessaire parce que l'
 le framework résout ses stores avant que l'ORM ne soit connecté — et parce que l'ORM se **déconnecte à
 l'arrêt** avant que les serveurs HTTP n'aient fini de vider leurs requêtes en vol. Handle absent =
 dégradation annoncée, pas un plantage : le `SessionStorage` rend une session vide et ignore les
-écritures (`#repo()`, `SessionStorage.ts:65`), le store d'idempotence laisse passer la mutation sans
-dédup (`begin()`, `DrizzleIdempotencyStore.ts:200`).
+écritures (`#repo()`, `SessionStorage.ts:86`), le store d'idempotence laisse passer la mutation sans
+dédup (`begin()`, `DrizzleIdempotencyStore.ts:220`).
 
 **SQL n'a pas de TTL.** Contrairement à Redis, rien n'expire tout seul : chaque store expose un `gc()`
 applicatif qui supprime les lignes échues, déclenché par un minuteur hors du chemin chaud —
@@ -732,7 +735,7 @@ c'est ce qui interdit de conclure « nouvelle mutation » hors d'une réservatio
 en deux instructions au verdict non ambigu (`reserveIdempotencyKeyMysql()`, `queryKit.ts:152`).
 
 **Le journal d'audit** pagine par un curseur **composite auto-portant** `<horodatage>:<id>` sur un ordre
-total, plutôt que par un identifiant seul (`listPage()`, `DrizzleAuditStore.ts:154`). Deux gains : plus
+total, plutôt que par un identifiant seul (`listPage()`, `DrizzleAuditStore.ts:169`). Deux gains : plus
 d'aller-retour pour résoudre le curseur, et une pagination qui ne rembobine pas à la première page si
 l'événement de référence a été purgé entre deux appels.
 
@@ -772,8 +775,8 @@ entités que le DDL dérivé, et un banc vérifie sur les trois dialectes qu'une
 identique à une base **dérivée** — colonne par colonne, index compris. Sans cette preuve, les deux
 chemins divergeraient en silence.
 
-Les appliquer, les adopter, les réparer et surveiller leur état est le travail de cinq commandes
-`nodefony orm:migrate*` — avec leur verrou, leur historique et leur branchement sur la sonde de
+Les écrire, les appliquer, les adopter, les réparer, surveiller leur état et repartir d'une base
+vide est le travail de six commandes — `orm:generate`, les quatre `orm:migrate*` et `orm:reset` — avec leur verrou, leur historique et leur branchement sur la sonde de
 disponibilité. Tout est dans **[Migrations de schéma](migrations.md)**, qui porte aussi le patron de
 déploiement sans interruption et les droits du compte qui migre.
 
@@ -831,7 +834,7 @@ faire lui-même).
 Côté écrans : **Database**, **ORM (vue d'ensemble et par entité)** et **Stores** — ce dernier répond à
 la question « où sont écrites mes données ? » pour chaque brique.
 
-La sonde d'un connecteur s'adapte au dialecte (`probe()`, `DrizzleOrm.ts:1614`) :
+La sonde d'un connecteur s'adapte au dialecte (`probe()`, `DrizzleOrm.ts:1835`) :
 
 - **SQLite** → `storage` : taille du fichier, mode de journal, pages libres (lus par `PRAGMA`) ;
 - **PostgreSQL / MySQL** → `pool` : taille, connexions libres, empruntées, en attente — **compteurs en
@@ -843,7 +846,7 @@ que promettre en silence — c'est le principe « superviser sans peser sur la p
 
 Chaque store expose aussi son **emplacement physique** pour l'écran Stores : le chemin du fichier
 SQLite, relativisé (anti-fuite d'information), et `undefined` pour un backend réseau — dont
-l'emplacement **est** l'infra déclarée, déjà affichée ailleurs (`location`, `DrizzleOrm.ts:415`).
+l'emplacement **est** l'infra déclarée, déjà affichée ailleurs (`location`, `DrizzleOrm.ts:481`).
 
 ## ⚡ Performance & mémoire
 

package/docs/migrations.md

@@ -80,7 +80,7 @@ D'où **trois modes**, un par connecteur, réglés par la clé `ddl` :
 
 ## 🚀 Démarrage rapide
 
-Cinq verbes, et un seul à retenir pour le quotidien du développement.
+Six verbes, et un seul à retenir pour le quotidien du développement.
 
 ```bash
 # Ce que la base a reçu, ce qui reste, et ce qu'il faut taper. N'écrit rien.
@@ -117,6 +117,34 @@ Toutes acceptent `--connector <nom>` (défaut : `default`) et `--json`. Le flux
 Les migrations du **framework** sont livrées dans le paquet : vous n'avez pas à les produire. Celles
 de votre **application**, vous les écrivez avec `orm:generate` — voir la section suivante.
 
+Ces deux familles de migrations appartiennent au **seul connecteur `default`**, celui qui porte les
+briques du framework : le dossier `migrations/<dialecte>` décrit sa base, et aucune autre.
+
+Un **connecteur secondaire** (une base d'analyse, la base d'un module, un second PostgreSQL) a ses
+**propres** migrations, dans son sous-dossier :
+
+```text
+migrations/
+├── sqlite/                 ← connecteur « default » (framework + application)
+└── analytics/
+    └── postgres/           ← connecteur « analytics », et lui seul
+```
+
+```bash
+nodefony orm:generate --connector analytics --name init   # écrit sous migrations/analytics/<dialecte>
+nodefony orm:migrate  --connector analytics                # l'applique à la base d'« analytics »
+```
+
+Chaque base ne reçoit que son dossier : `default` ne voit pas les migrations d'`analytics`, et
+inversement. `orm:generate --connector analytics` ne décrit que les tables des entités déclarées sur
+ce connecteur (`@entity({ connector: "analytics" })`) ; une table qu'aucune entité ne réclame reste
+à `default`. Tant qu'un secondaire n'a rien versionné, rien ne change : en développement son schéma
+est dérivé du code. Dès son premier fichier, il bascule en `migrate` comme `default`.
+
+Un connecteur secondaire ne peut pas s'appeler `sqlite`, `postgres`, `mysql` ni `meta` : son dossier
+serait celui d'un dialecte de `default`. Les commandes qui écriraient une migration le refusent
+(`NF_MIGRATE_SECONDARY_CONNECTOR`) — renommez le connecteur, son nom ne sert qu'à le désigner.
+
 Côté configuration, il n'y a rien à écrire pour le cas courant : le mode se résout par
 environnement. Ne le déclarer que pour s'en écarter — un serveur unique qui migre au démarrage :
 
@@ -162,6 +190,34 @@ Le dialecte est celui de votre connecteur : vos entités sont du Drizzle **natif
 un moteur. C'est ce qui vous laisse toute la puissance du moteur dans une entité — et ce qui fait
 qu'une migration vaut pour lui seul.
 
+### En développement : écrire et appliquer d'un seul geste — `--apply`
+
+```bash
+nodefony orm:generate --name ajout_du_titre --apply
+```
+
+Vous éditez votre entité, vous tapez **une** commande, la colonne est en base. C'est le geste
+quotidien du développement, et il ne vous demande pas de retenir un second verbe.
+
+`--apply` n'invente rien : il **enchaîne `orm:migrate`**. Toutes ses gardes valent donc à
+l'identique — une migration qui supprime des données reste refusée sans `--allow-destructive`, le
+verrou est pris, l'historique est écrit. En sortie machine (`--json`), un seul document est produit,
+celui de l'application : c'est lui qui porte le verdict.
+
+> **Le drapeau n'existe qu'en développement**, et aucun autre drapeau ne le déverrouille. Écrire une
+> migration et l'appliquer dans le même souffle suppose qu'on relit le SQL produit entre les deux —
+> ce que personne ne fait sur un serveur. Ailleurs, la migration a été écrite, relue et versionnée
+> ailleurs : c'est `orm:migrate` qui l'applique, et lui seul.
+
+> **Et le mode de schéma bascule tout seul.** Dès que votre application versionne sa première
+> migration, le démarrage cesse de dériver les tables depuis le code (`ddl: "auto"`) et applique vos
+> migrations (`ddl: "migrate"`) — même en développement. Deux fabricants du même schéma ne
+> s'accordent pas : le DDL dérivé pose une unicité **collée à la colonne** (`content text NOT NULL
+UNIQUE`), le générateur de migrations raisonne sur un **index nommé** (`messages_content_unique`),
+> et la première migration qui tente de retirer la seconde échoue sur un objet qui n'a jamais existé.
+> Un `ddl` écrit dans votre configuration gagne toujours ; et sous `NODE_ENV=test`, rien ne change
+> (une suite lance un exemplaire par worker, et ses bases partent vides).
+
 ### Ce que la commande refuse, et pourquoi c'est une bonne nouvelle
 
 **Une migration est immuable dès qu'une base l'a reçue.** Une migration à laquelle il manque une
@@ -196,12 +252,21 @@ dépendances de développement (`--omit=dev`, une image de production). Le refus
 geste ; il ne parle pas de votre base, qui n'y est pour rien — appliquer des migrations, lui, ne
 réclame aucun outil tiers.
 
+Un cinquième tient à la forme d'un fichier d'entité : **un `await` de premier niveau**
+(`NF_GENERATE_TOP_LEVEL_AWAIT`). Votre application est ESM et démarre très bien avec lui, mais
+l'outil qui écrit les migrations relit les fichiers de schéma de son côté, en CommonJS, où cette
+construction n'existe pas. Le refus nomme le fichier et la ligne. Un fichier d'entité **déclare**
+une table : ce qui se décide à l'exécution — choisir une entité selon l'infrastructure, importer
+un module à la demande — se place dans l'`index.ts` du module, dont `@entities([...])` accepte une
+liste calculée.
+
 ### Une entité qui pointe vers une table du framework
 
 Déclarer une référence vers une table du framework (`session`, `audit_event`…) est légitime : ce
 qui est refusé, c'est de **ré-exporter** cette table depuis vos fichiers. Les tables du framework
 sont exclues du plan de votre application — elles ont leurs propres migrations, appliquées avant les
-vôtres. Pour une vraie clé étrangère SQL, écrivez une migration libre.
+vôtres. La contrainte, elle, est bien écrite dans votre migration : elle désigne une table que le
+framework a déjà créée.
 
 > [!IMPORTANT]
 > **`User` n'en fait PAS partie.** L'identité est du domaine : la table `User` appartient à votre
@@ -361,7 +426,7 @@ Trois propriétés en découlent, et elles valent d'être nommées :
 - **Rien n'est appliqué deux fois.** L'historique (`nodefony_migrations`, `types.ts:23`) est écrit
   dans la même transaction que le DDL, là où le moteur le permet.
 - **Un pod en retard ne reçoit pas de trafic.** En `none` comme en `migrate`, l'état du schéma est
-  publié à la sonde de disponibilité (`#publishReadiness()`, `DrizzleService.ts:445`) : `/readyz`
+  publié à la sonde de disponibilité (`#publishReadiness()`, `DrizzleService.ts:527`) : `/readyz`
   répond 503, l'orchestrateur sort l'exemplaire du répartiteur de charge, et l'ancien continue de
   servir. `/livez` n'est jamais touché — un schéma en retard n'est pas un processus malade, et le
   redémarrer ne réparerait rien. La vérification est rejouée toutes les 15 secondes : dès que le
@@ -425,7 +490,7 @@ qui la prend. Un outil qui prétendrait la préparer tout seul inviterait à ne
 Ce que l'outil fait à la place, et qui vaut mieux :
 
 - **il refuse d'appliquer sans que vous sachiez.** Le SQL en attente est examiné avant la moindre
-  écriture (`scanDestructive()`, `destructive.ts:184`) : une suppression de données est refusée hors
+  écriture (`scanDestructive()`, `destructive.ts:282`) : une suppression de données est refusée hors
   développement, en nommant l'instruction et ce qui disparaît. Il faut `--allow-destructive` pour
   passer outre, et **au démarrage il n'y a aucun drapeau pour lever le refus** — un exemplaire qui
   redémarre ne supprime jamais de colonne de lui-même, parce que personne ne regarde à ce

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/drizzle",
-  "version": "10.0.0-alpha.7",
+  "version": "10.0.0-alpha.9",
   "description": "Moteur SQL de Nodefony sur Drizzle ORM (SQLite, PostgreSQL, MySQL) : dépôts typés, migrations de schéma et adoption d'une base existante",
   "nodefony": {
     "storeKind": "durable",
@@ -28,8 +28,8 @@
   },
   "scripts": {
     "start": "node dist/index.js",
-    "build": "rimraf dist && rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
-    "clean": "rimraf dist",
+    "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "generate:migrations": "tsx scripts/generate-migrations.ts",
     "check:migrations": "tsx scripts/check-migrations-drift.ts",
     "dev": "rolldown -c rolldown.config.ts --watch",
@@ -55,35 +55,34 @@
     "esm"
   ],
   "dependencies": {
-    "drizzle-orm": "0.45.2",
+    "drizzle-orm": "0.45.3",
     "tslib": "2.8.1",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-alpha.7",
-    "@nodefony/http": "^10.0.0-alpha.7",
-    "@nodefony/orm-core": "^10.0.0-alpha.7",
-    "@nodefony/security": "^10.0.0-alpha.7",
-    "@nodefony/user": "^10.0.0-alpha.7",
+    "@nodefony/framework": "^10.0.0-alpha.9",
+    "@nodefony/http": "^10.0.0-alpha.9",
+    "@nodefony/orm-core": "^10.0.0-alpha.9",
+    "@nodefony/security": "^10.0.0-alpha.9",
+    "@nodefony/user": "^10.0.0-alpha.9",
     "@types/better-sqlite3": "9.6.0",
-    "@types/node": "26.6.1",
+    "@types/node": "26.6.2",
     "@types/pg": "8.23.1",
     "better-sqlite3": "13.0.3",
-    "drizzle-kit": "0.31.10",
+    "drizzle-kit": "0.31.11",
     "mysql2": "3.24.4",
-    "nodefony": "^10.0.0-alpha.7",
-    "pg": "8.23.0",
-    "rimraf": "6.1.3"
+    "nodefony": "^10.0.0-alpha.9",
+    "pg": "8.23.0"
   },
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-alpha.7",
-    "@nodefony/http": "^10.0.0-alpha.7",
-    "@nodefony/orm-core": "^10.0.0-alpha.7",
-    "@nodefony/security": "^10.0.0-alpha.7",
-    "@nodefony/user": "^10.0.0-alpha.7",
+    "@nodefony/framework": "^10.0.0-alpha.9",
+    "@nodefony/http": "^10.0.0-alpha.9",
+    "@nodefony/orm-core": "^10.0.0-alpha.9",
+    "@nodefony/security": "^10.0.0-alpha.9",
+    "@nodefony/user": "^10.0.0-alpha.9",
     "better-sqlite3": "^13.0.0",
     "mysql2": "^3.24.0",
-    "nodefony": "^10.0.0-alpha.7",
+    "nodefony": "^10.0.0-alpha.9",
     "pg": "^8.23.0"
   },
   "repository": {