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

package/dist/nodefony/src/migrator/resolve.js

@@ -1,9 +1,11 @@
 import { MIGRATE_URL_ENV } from "./types.js";
 import { resolveConnectorTarget } from "../connectorTarget.js";
-import { defaultMigrationSources } from "./paths.js";
+import { MEMORY_DATABASE } from "../memoryDatabase.js";
+import { connectorMigrationsDir, defaultMigrationSources } from "./paths.js";
 import { DrizzleMigrator } from "./DrizzleMigrator.js";
 import { parseDatabaseUrl, sqliteFilenameFromUrl } from "nodefony";
 import { ormRegistry } from "@nodefony/orm-core";
+import fs from "node:fs";
 import path from "node:path";
 //#region nodefony/src/migrator/resolve.ts
 /**
@@ -52,6 +54,25 @@ function resetAllowed(env) {
 	return env.runtime === "development" && env.nodeEnv !== "test";
 }
 /**
+* `orm:generate --apply` est-il recevable dans cet environnement ?
+*
+* É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 qu'en développement, la migration a été écrite, relue et versionnée
+* en amont : `orm:migrate` l'applique, et lui seul. Aucun drapeau ne lève ce
+* refus, pour la même raison que {@link resetAllowed} n'en a pas.
+*
+* Même forme que `resetAllowed`, et c'est voulu : les deux disent « geste de
+* développement », et deux rédactions de la même condition finiraient par
+* diverger sans que rien ne le signale.
+*
+* @param env - environnement constaté.
+* @returns `true` si l'enchaînement est recevable.
+*/
+function generateApplyAllowed(env) {
+	return env.runtime === "development" && env.nodeEnv !== "test";
+}
+/**
 * Le mode de schéma qui s'applique à un connecteur.
 *
 * Règle des défauts, et son pourquoi : **appliquer des migrations au démarrage
@@ -63,13 +84,89 @@ function resetAllowed(env) {
 * - tout le reste → `none` : personne ne touche au schéma au démarrage, un
 *   travail externe applique les migrations avant que le trafic n'arrive.
 *
+* 🔴 **Une application qui VERSIONNE des migrations bascule en `migrate`, même
+* en développement.** Deux fabricants du même schéma ne s'accordent pas, et
+* rien ne le signale tant qu'on ne les fait pas se rencontrer : le DDL dérivé
+* pose une contrainte d'unicité INLINE et anonyme (`content text NOT NULL
+* UNIQUE`), là où le générateur de migrations raisonne sur un index NOMMÉ
+* (`messages_content_unique`). La migration suivante émet alors un
+* `DROP INDEX` d'un index qui n'a jamais existé, échoue sur `no such index`,
+* inscrit son marqueur — et la réparation ne peut rien y faire, puisque le
+* fichier est inapplicable. Vécu sur un agent tiers : trente-cinq minutes de
+* `repair`/`baseline`/`reset`, deux bases détruites, la boucle brisée à la main.
+* La condition est délibérément « l'application EN A », pas « elle en a en
+* attente » : dès la première migration écrite, le schéma leur appartient.
+* Elle est bornée au développement RÉEL, jamais à `NODE_ENV=test` : une suite
+* lance un exemplaire par worker, et appliquer des migrations depuis plusieurs
+* processus au démarrage est précisément ce que la règle ci-dessus refuse.
+* Un `ddl` écrit dans la configuration gagne toujours — c'est un choix, pas une
+* déduction.
+*
 * @param explicit - valeur écrite dans la configuration du connecteur, si elle l'est.
 * @param env - environnement constaté.
+* 🔴 **Une base VOLATILE (`:memory:`) dérive toujours son schéma**, en
+* production comprise. Rien d'autre ne peut la peupler : elle repart vide à
+* chaque démarrage, et une migration appliquée ne survit pas au processus. En
+* `none`, elle restait vide, le verdict de schéma tombait à `divergent` et la
+* sonde de disponibilité retenait la mise en service (vécu en CI : le connecteur
+* d'un module de banc, ouvert en production sous dérogation).
+*
+* @param appHasMigrations - l'application versionne au moins une migration.
+* @param volatile - la base est en mémoire (`:memory:`).
 * @returns le mode effectif.
 */
-function resolveDdlMode(explicit, env) {
+function resolveDdlMode(explicit, env, appHasMigrations = false, volatile = false) {
 	if (explicit) return explicit;
-	return env.runtime === "development" || env.nodeEnv === "test" ? "auto" : "none";
+	if (volatile) return "auto";
+	if (env.runtime === "development" || env.nodeEnv === "test") return appHasMigrations && env.nodeEnv !== "test" ? "migrate" : "auto";
+	return "none";
+}
+/**
+* L'application versionne-t-elle au moins une migration ?
+*
+* Lecture SYNCHRONE et bornée à un `readdirSync` par connecteur au démarrage —
+* hors de tout chemin de requête. Elle doit l'être : le mode de schéma se
+* décide avant la connexion, et le rendre asynchrone propagerait un `await`
+* dans toute la chaîne de résolution pour une réponse qui ne change jamais
+* pendant la vie du processus.
+*
+* Un dossier absent, illisible ou vide répond `false` — l'application n'a alors
+* rien à appliquer, et `auto` reste le bon défaut de démarrage rapide.
+*
+* @param dir - dossier de migrations de l'application ({@link appMigrationsDir}).
+* @returns `true` si au moins un fichier `.sql` y est versionné, à un niveau
+*   ou sous un sous-dossier de dialecte (`migrations/postgres/0001_x.sql`).
+*/
+function appVersionsMigrations(dir) {
+	if (!dir) return false;
+	try {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			if (entry.isFile() && entry.name.endsWith(".sql")) return true;
+			if (entry.isDirectory() && entry.name !== "meta") {
+				if (fs.readdirSync(path.join(dir, entry.name)).some((name) => name.endsWith(".sql"))) return true;
+			}
+		}
+	} catch {
+		return false;
+	}
+	return false;
+}
+/**
+* Des migrations versionnées CONCERNENT-elles ce connecteur ?
+*
+* C'est la question que pose la bascule `auto` → `migrate`, et elle n'est pas
+* « l'application versionne-t-elle des migrations ? » : celles de la racine
+* décrivent la base du framework. Posée telle quelle, elle faisait basculer en
+* `migrate` un connecteur secondaire qui n'en recevra jamais une — sa base
+* restait alors sans schéma, ni dérivé ni migré. On regarde donc le dossier
+* DU connecteur ({@link connectorMigrationsDir}).
+*
+* @param connector - nom du connecteur.
+* @param dir - dossier de migrations de l'application ({@link appMigrationsDir}).
+* @returns `true` si le dossier propre au connecteur porte au moins un `.sql`.
+*/
+function connectorVersionsMigrations(connector, dir) {
+	return appVersionsMigrations(connectorMigrationsDir(dir, connector));
 }
 /**
 * La conduite de la sonde de disponibilité face à un schéma en retard.
@@ -88,6 +185,26 @@ function resolveCheckMode(explicit, env) {
 	return env.runtime === "production" ? "fail" : "warn";
 }
 /**
+* En schéma `auto`, faut-il ÉNONCER au démarrage les migrations enregistrées
+* que personne n'a appliquées ?
+*
+* Oui en développement, sauf conduite `off` — c'est ce conseil qui évite de
+* conclure à une base incohérente devant une colonne inconnue. Jamais sur une
+* base `:memory:` : elle repart VIDE à chaque démarrage, son historique aussi,
+* si bien que tout y paraît « à appliquer » à chaque fois — un avertissement
+* permanent qui n'apprend rien (vécu : le connecteur de banc `mediasoup`,
+* une fois déclaré, réclamait à chaque démarrage les migrations du framework
+* et de l'application, qui ne le concernent pas).
+*
+* @param check - conduite résolue ({@link resolveCheckMode}).
+* @param env - environnement constaté.
+* @param filename - fichier sqlite du connecteur, s'il en a un.
+* @returns `true` si le conseil doit être rendu.
+*/
+function adviseMigrations(check, env, filename) {
+	return check !== "off" && env.runtime === "development" && filename !== ":memory:";
+}
+/**
 * Décrit ce qui porte un connecteur, pour le nommer dans un refus.
 *
 * Un message qui dit seulement « ce connecteur ne porte pas de migrations »
@@ -217,7 +334,7 @@ function resolveConnector(connector, config, env, kernel, options = {}) {
 			url: fromMigrateUrl && dialect !== "sqlite" ? parsedUrl.url : base.url
 		},
 		fromMigrateUrl,
-		ddl: resolveDdlMode(declared.ddl, env)
+		ddl: resolveDdlMode(declared.ddl, env, connectorVersionsMigrations(connector, appMigrationsDir(kernel, config.migrations.dir)), declared.filename === MEMORY_DATABASE)
 	};
 }
 /**
@@ -265,7 +382,10 @@ function appMigrationsDir(kernel, dir) {
 */
 async function buildMigrator(resolution, config, kernel) {
 	const appDir = appMigrationsDir(kernel, config.migrations.dir);
-	const sources = await defaultMigrationSources(appDir, { framework: config.frameworkEntities !== false });
+	const sources = await defaultMigrationSources(appDir, {
+		framework: config.frameworkEntities !== false,
+		connector: resolution.connector
+	});
 	return new DrizzleMigrator({
 		connector: resolution.connector,
 		...resolution.target,
@@ -278,4 +398,4 @@ function resolveDivergenceMode(config) {
 	return config.migrations.divergence;
 }
 //#endregion
-export { MIGRATE_URL_ENV, appMigrationsDir, buildMigrator, knownConnectors, readMigrationEnv, resetAllowed, resolveCheckMode, resolveConnector, resolveDdlMode, resolveDivergenceMode };
+export { MEMORY_DATABASE, MIGRATE_URL_ENV, adviseMigrations, appMigrationsDir, appVersionsMigrations, buildMigrator, connectorVersionsMigrations, generateApplyAllowed, knownConnectors, readMigrationEnv, resetAllowed, resolveCheckMode, resolveConnector, resolveDdlMode, resolveDivergenceMode };

package/dist/nodefony/src/orm-core/DrizzleOrm.js

@@ -1,10 +1,12 @@
 import { schemaReader, toDollarParams } from "../migrator/catalog.js";
+import "../memoryDatabase.js";
 import { notConfigured } from "../migrator/refusals.js";
 import { additiveSql, compareSchema, hasGap } from "../migrator/schemaDiff.js";
 import { describeTargetSafely } from "../safeTarget.js";
 import { failureFrom } from "../migrator/status.js";
 import { DrizzleRepository } from "./DrizzleRepository.js";
 import { DrizzleTransaction } from "./DrizzleTransaction.js";
+import { explainOmittedForeignKeys, planTableCreation } from "./ddlPlan.js";
 import { createRequire } from "node:module";
 import { CONNECT_TIMEOUT_MS, Orm, entityRegistry, parseConnectionTarget, withConnectDeadline } from "@nodefony/orm-core";
 import fs from "node:fs";
@@ -15,6 +17,32 @@ import { PgDialect, PgTable, getTableConfig as getTableConfig$1 } from "drizzle-
 import { MySqlDialect, MySqlTable, getTableConfig as getTableConfig$2 } from "drizzle-orm/mysql-core";
 //#region nodefony/src/orm-core/DrizzleOrm.ts
 /**
+* Traduit les clés étrangères d'une table Drizzle en noms SQL émettables.
+*
+* @param foreignKeys - contraintes lues sur la table (`getTableConfig`).
+* @param nameOf - comment lire le nom SQL d'une table du dialecte courant.
+* @param skip - tables visées dont la contrainte doit être ABANDONNÉE (cycle ou
+*   cible absente de cette base) ; l'appelant les a déjà journalisées.
+* @returns les contraintes à écrire dans le `CREATE TABLE`.
+*/
+function resolveForeignKeys(foreignKeys, nameOf, skip) {
+	const resolved = [];
+	for (const fk of foreignKeys) {
+		const reference = fk.reference();
+		const foreignTable = nameOf(reference.foreignTable);
+		if (skip?.has(foreignTable)) continue;
+		resolved.push({
+			name: fk.getName(),
+			columns: reference.columns.map((column) => column.name),
+			foreignTable,
+			foreignColumns: reference.foreignColumns.map((column) => column.name),
+			onDelete: fk.onDelete,
+			onUpdate: fk.onUpdate
+		});
+	}
+	return resolved;
+}
+/**
 * Rend le prédicat d'une contrainte `CHECK` en SQL littéral, avec la grammaire
 * du dialecte demandé.
 *
@@ -155,7 +183,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* @param options - options de connexion (`dialect`, `filename` sqlite, `url` pg).
 	*/
 	constructor(name, options = {}) {
-		super(name);
+		super(name, options.container);
 		this.#dialect = options.dialect ?? "sqlite";
 		this.#deriveSchema = options.deriveSchema !== false;
 		this.#filename = options.filename ?? ":memory:";
@@ -245,7 +273,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* `"…"` (SQL standard, SQLite/PG) vs backtick MySQL (qui ne lit `"…"` qu'en
 	* mode ANSI_QUOTES, jamais garanti). La prod reste pilotée par drizzle-kit.
 	*/
-	#buildCreateTable(name, columns, quote = "\"", checks = [], dialect = "sqlite") {
+	#buildCreateTable(name, columns, quote = "\"", checks = [], dialect = "sqlite", foreignKeys = []) {
 		const defs = columns.map((col) => {
 			const parts = [`${quote}${col.name}${quote}`, col.getSQLType()];
 			if (col.primary) parts.push("PRIMARY KEY");
@@ -258,6 +286,12 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			if (predicate === null) continue;
 			defs.push(`CONSTRAINT ${quote}${check.name}${quote} CHECK (${predicate})`);
 		}
+		for (const fk of foreignKeys) {
+			const source = fk.columns.map((c) => `${quote}${c}${quote}`).join(", ");
+			const target = fk.foreignColumns.map((c) => `${quote}${c}${quote}`).join(", ");
+			const actions = [fk.onDelete ? ` ON DELETE ${fk.onDelete.toUpperCase()}` : "", fk.onUpdate ? ` ON UPDATE ${fk.onUpdate.toUpperCase()}` : ""].join("");
+			defs.push(`CONSTRAINT ${quote}${fk.name}${quote} FOREIGN KEY (${source}) REFERENCES ${quote}${fk.foreignTable}${quote} (${target})${actions}`);
+		}
 		return `CREATE TABLE IF NOT EXISTS ${quote}${name}${quote} (${defs.join(", ")})`;
 	}
 	/**
@@ -273,11 +307,11 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 	* pas. Émis à part, il arrive AUSSI sur une base de développement déjà créée —
 	* ce qu'aucune clause de table ne permettrait.
 	*
-	* Les clés étrangères, elles, ne sont toujours PAS émises : elles se déclarent
-	* DANS le `CREATE TABLE`, donc elles n'atteindraient jamais une base existante,
-	* et elles imposeraient de créer les tables dans l'ordre de leurs dépendances
-	* (indécidable sur un cycle). C'est le travail du DDL de production
-	* (drizzle-kit), pas d'un dérivé de développement.
+	* Les clés étrangères, elles, ne peuvent PAS être émises à part : elles se
+	* déclarent DANS le `CREATE TABLE` (cf `#buildCreateTable`), donc elles
+	* n'atteignent jamais une base déjà créée — c'est le prix assumé, le même que
+	* pour les `CHECK`. Et elles imposent de créer les tables dans l'ordre de
+	* leurs dépendances : cf `#planCreation`, qui porte aussi le cas du cycle.
 	*
 	* @param table - nom de la table portant les index.
 	* @param indexes - index déclarés (`getTableConfig(...).indexes`).
@@ -295,10 +329,43 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		}
 		return statements;
 	}
+	/**
+	* Ordonne les tables pour que chaque cible naisse avant qui la désigne, et dit
+	* ce qu'il a fallu abandonner.
+	*
+	* Le tri lui-même vit à part ({@link planTableCreation}, module pur) ; cette
+	* méthode ne fait que lire les tables du dialecte courant et JOURNALISER.
+	* L'avertissement compte autant que le tri : une contrainte d'intégrité qui
+	* n'est pas posée est une garantie qu'on croit avoir.
+	*
+	* @param entities - les entités de ce connecteur.
+	* @param describe - comment lire le nom d'une table et ses cibles.
+	* @returns les entités dans l'ordre de création, et les cibles à ignorer par table.
+	*/
+	#planCreation(entities, describe) {
+		const described = entities.map((entity) => ({
+			entity,
+			...describe(entity)
+		}));
+		const plan = planTableCreation(described);
+		const skip = /* @__PURE__ */ new Map();
+		for (const entry of plan.omitted) {
+			const targets = skip.get(entry.table) ?? /* @__PURE__ */ new Set();
+			targets.add(entry.target);
+			skip.set(entry.table, targets);
+		}
+		const message = explainOmittedForeignKeys(plan.omitted);
+		if (message) this.log(message, "WARNING");
+		const rank = new Map(plan.order.map((name, index) => [name, index]));
+		return {
+			ordered: [...described].sort((a, b) => (rank.get(a.name) ?? 0) - (rank.get(b.name) ?? 0)).map((entry) => entry.entity),
+			skip
+		};
+	}
 	/** Dérive le `CREATE TABLE` SQLite depuis la table Drizzle (dev/test). */
-	#createTableSQL(table) {
-		const { name, columns, checks } = getTableConfig(table);
-		return this.#buildCreateTable(name, columns, "\"", checks, "sqlite");
+	#createTableSQL(table, skip) {
+		const { name, columns, checks, foreignKeys } = getTableConfig(table);
+		return this.#buildCreateTable(name, columns, "\"", checks, "sqlite", resolveForeignKeys(foreignKeys, (target) => getTableConfig(target).name, skip));
 	}
 	/** Dérive les `CREATE INDEX` SQLite depuis la table Drizzle (dev/test). */
 	#createIndexesSQL(table) {
@@ -306,9 +373,9 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		return this.#buildCreateIndexes(name, indexes);
 	}
 	/** Dérive le `CREATE TABLE` Postgres depuis la table Drizzle (dev/test). */
-	#createTablePgSQL(table) {
-		const { name, columns, checks } = getTableConfig$1(table);
-		return this.#buildCreateTable(name, columns, "\"", checks, "postgres");
+	#createTablePgSQL(table, skip) {
+		const { name, columns, checks, foreignKeys } = getTableConfig$1(table);
+		return this.#buildCreateTable(name, columns, "\"", checks, "postgres", resolveForeignKeys(foreignKeys, (target) => getTableConfig$1(target).name, skip));
 	}
 	/** Dérive les `CREATE INDEX` Postgres depuis la table Drizzle (dev/test). */
 	#createIndexesPgSQL(table) {
@@ -316,9 +383,9 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 		return this.#buildCreateIndexes(name, indexes);
 	}
 	/** Dérive le `CREATE TABLE` MySQL depuis la table Drizzle (dev/test). */
-	#createTableMysqlSQL(table) {
-		const { name, columns, checks } = getTableConfig$2(table);
-		return this.#buildCreateTable(name, columns, "`", checks, "mysql");
+	#createTableMysqlSQL(table, skip) {
+		const { name, columns, checks, foreignKeys } = getTableConfig$2(table);
+		return this.#buildCreateTable(name, columns, "`", checks, "mysql", resolveForeignKeys(foreignKeys, (target) => getTableConfig$2(target).name, skip));
 	}
 	/**
 	* Dérive les `CREATE INDEX` MySQL depuis la table Drizzle (dev/test).
@@ -411,6 +478,7 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			client.pragma("journal_mode = WAL");
 			client.pragma("synchronous = NORMAL");
 		}
+		client.pragma("foreign_keys = ON");
 		this.#client = client;
 		const db = sqliteDrizzle(client);
 		this.#db = db;
@@ -440,8 +508,19 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			const table = entity.schema;
 			this.#tables[entity.name] = table;
 			entity.model = table;
-			if (!this.#deriveSchema) continue;
-			client.exec(this.#createTableSQL(table));
+		}
+		if (!this.#deriveSchema) return;
+		const plan = this.#planCreation(entities, (entity) => {
+			const config = getTableConfig(entity.schema);
+			return {
+				name: config.name,
+				references: config.foreignKeys.map((fk) => getTableConfig(fk.reference().foreignTable).name)
+			};
+		});
+		for (const entity of plan.ordered) {
+			const table = entity.schema;
+			const name = getTableConfig(table).name;
+			client.exec(this.#createTableSQL(table, plan.skip.get(name)));
 		}
 	}
 	/**
@@ -671,8 +750,19 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			const table = entity.schema;
 			this.#tables[entity.name] = table;
 			entity.model = table;
-			if (!this.#deriveSchema) continue;
-			await pool.query(this.#createTablePgSQL(table));
+		}
+		if (!this.#deriveSchema) return;
+		const plan = this.#planCreation(entities, (entity) => {
+			const config = getTableConfig$1(entity.schema);
+			return {
+				name: config.name,
+				references: config.foreignKeys.map((fk) => getTableConfig$1(fk.reference().foreignTable).name)
+			};
+		});
+		for (const entity of plan.ordered) {
+			const table = entity.schema;
+			const name = getTableConfig$1(table).name;
+			await pool.query(this.#createTablePgSQL(table, plan.skip.get(name)));
 		}
 	}
 	/**
@@ -849,8 +939,19 @@ var DrizzleOrm = class DrizzleOrm extends Orm {
 			const table = entity.schema;
 			this.#tables[entity.name] = table;
 			entity.model = table;
-			if (!this.#deriveSchema) continue;
-			await pool.query(this.#createTableMysqlSQL(table));
+		}
+		if (!this.#deriveSchema) return;
+		const plan = this.#planCreation(entities, (entity) => {
+			const config = getTableConfig$2(entity.schema);
+			return {
+				name: config.name,
+				references: config.foreignKeys.map((fk) => getTableConfig$2(fk.reference().foreignTable).name)
+			};
+		});
+		for (const entity of plan.ordered) {
+			const table = entity.schema;
+			const name = getTableConfig$2(table).name;
+			await pool.query(this.#createTableMysqlSQL(table, plan.skip.get(name)));
 		}
 	}
 	async disconnect() {

package/dist/nodefony/src/orm-core/ddlPlan.js

@@ -0,0 +1,95 @@
+//#region nodefony/src/orm-core/ddlPlan.ts
+/**
+* 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.
+*/
+function planTableCreation(tables) {
+	const known = new Set(tables.map((table) => table.name));
+	const omitted = [];
+	/** Dépendances RÉELLES : cible connue, et différente de la table elle-même. */
+	const dependencies = /* @__PURE__ */ new Map();
+	for (const table of tables) {
+		const deps = /* @__PURE__ */ new Set();
+		for (const target of table.references) {
+			if (target === table.name) continue;
+			if (!known.has(target)) {
+				omitted.push({
+					table: table.name,
+					target,
+					reason: "absent"
+				});
+				continue;
+			}
+			deps.add(target);
+		}
+		dependencies.set(table.name, deps);
+	}
+	const order = [];
+	const placed = /* @__PURE__ */ new Set();
+	const remaining = new Set(known);
+	for (;;) {
+		const ready = [...remaining].filter((name) => {
+			const deps = dependencies.get(name);
+			return !deps || [...deps].every((dep) => placed.has(dep));
+		}).sort();
+		if (ready.length === 0) break;
+		for (const name of ready) {
+			order.push(name);
+			placed.add(name);
+			remaining.delete(name);
+		}
+	}
+	for (const name of [...remaining].sort()) {
+		order.push(name);
+		placed.add(name);
+	}
+	const rank = new Map(order.map((name, index) => [name, index]));
+	for (const name of order) for (const target of dependencies.get(name) ?? []) if ((rank.get(target) ?? 0) > (rank.get(name) ?? 0)) omitted.push({
+		table: name,
+		target,
+		reason: "cycle"
+	});
+	return {
+		order,
+		omitted
+	};
+}
+/**
+* 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.
+*/
+function explainOmittedForeignKeys(omitted) {
+	if (omitted.length === 0) return null;
+	const cycles = omitted.filter((entry) => entry.reason === "cycle");
+	const absent = omitted.filter((entry) => entry.reason === "absent");
+	const parts = [];
+	if (cycles.length > 0) parts.push(`cycle entre entités — contrainte(s) NON posée(s) : ${cycles.map((c) => `${c.table} → ${c.target}`).join(", ")}. Aucun ordre de création ne satisfait les deux sens ; une migration (\`orm:generate\`) les ajoute après coup par \`ALTER TABLE\`.`);
+	if (absent.length > 0) parts.push(`cible hors de cette base — contrainte(s) NON posée(s) : ${absent.map((a) => `${a.table} → ${a.target}`).join(", ")}. L'entité visée est déclarée sur un autre connecteur : l'intégrité référentielle ne traverse pas deux bases.`);
+	return parts.join(" ");
+}
+//#endregion
+export { explainOmittedForeignKeys, planTableCreation };

package/dist/nodefony/src/orm-core/index.js

@@ -1,4 +1,5 @@
 import { DrizzleRepository } from "./DrizzleRepository.js";
 import { DrizzleTransaction } from "./DrizzleTransaction.js";
 import { DrizzleOrm } from "./DrizzleOrm.js";
-export { DrizzleOrm, DrizzleRepository, DrizzleTransaction };
+import { seedEntityRow } from "./seedRow.js";
+export { DrizzleOrm, DrizzleRepository, DrizzleTransaction, seedEntityRow };

package/dist/nodefony/src/orm-core/seedRow.js

@@ -0,0 +1,65 @@
+import { getTableColumns } from "drizzle-orm";
+//#region nodefony/src/orm-core/seedRow.ts
+/**
+* Compteur de semis — il rend chaque ligne semée DISTINCTE.
+*
+* Une entité cible porte souvent une colonne unique (un courriel, une
+* référence). Semer deux fois la même valeur violerait sa contrainte, et le test
+* échouerait sur son propre décor plutôt que sur ce qu'il éprouve.
+*/
+let seedCounter = 0;
+/**
+* Valeur plausible pour une colonne, dérivée de ce que Drizzle en dit.
+*
+* On lit `dataType`, la classification **générique** de Drizzle (commune aux
+* trois dialectes), et non `columnType`, qui nomme l'implémentation (`SQLiteText`,
+* `PgVarchar`) et obligerait à connaître chaque moteur.
+*/
+function sampleForColumn(column, n) {
+	if (column.enumValues?.length) return column.enumValues[0];
+	switch (column.dataType) {
+		case "number": return n;
+		case "bigint": return BigInt(n);
+		case "boolean": return true;
+		case "date": return /* @__PURE__ */ new Date();
+		case "json": return {};
+		case "buffer": return Buffer.from(`seed-${n}`);
+		default: return `seed-${n}`;
+	}
+}
+/**
+* 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.
+*/
+async function seedEntityRow(orm, entity) {
+	const n = ++seedCounter;
+	const columns = getTableColumns(entity.schema);
+	const row = {};
+	for (const [name, column] of Object.entries(columns)) {
+		if (!column.notNull || column.hasDefault || column.primary) continue;
+		row[name] = sampleForColumn(column, n);
+	}
+	try {
+		return (await orm.getRepository(entity.name).create(row)).id;
+	} catch (cause) {
+		throw new Error(`seedEntityRow : impossible de semer une ligne de « ${entity.name} ». Si cette entité porte elle-même une relation obligatoire, sème d'abord sa cible. Cause : ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+//#endregion
+export { seedEntityRow };

package/dist/nodefony/src/safeTarget.js

@@ -1,3 +1,4 @@
+import "./memoryDatabase.js";
 import path from "node:path";
 //#region nodefony/src/safeTarget.ts
 /**

package/dist/types/index.d.ts

@@ -48,7 +48,7 @@ export { DrizzleMigrator, DEFAULT_LOCK_TIMEOUT_MS, openMigrationDriver, framewor
 export { MIGRATION_FORMAT_VERSION, EXIT, buildReport, verdictOf, exitCodeOf, meaningOf, renderStatus, renderRefusal, styleFor, action, type IMigrationReport, type IMigrationSourceReport, type IReportContext, type MigrationVerdictName, type IStyle, } from "./nodefony/src/migrator/explain.js";
 export { MIGRATE_URL_ENV, readMigrationEnv, resolveDdlMode, resolveCheckMode, resetAllowed, resolveConnector, resolveDivergenceMode, knownConnectors, appMigrationsDir, buildMigrator, type IMigrationEnv, type IConnectorResolution, } from "./nodefony/src/migrator/resolve.js";
 export { DDL_MODES, MIGRATION_CHECK_MODES, DIVERGENCE_MODES, type DdlMode, type MigrationCheckMode, type DivergenceMode, } from "./nodefony/config/config.js";
-export { DrizzleOrm, DrizzleRepository, DrizzleTransaction, } from "./nodefony/src/orm-core/index.js";
+export { DrizzleOrm, DrizzleRepository, DrizzleTransaction, seedEntityRow, } from "./nodefony/src/orm-core/index.js";
 export type { DrizzleOrmOptions, DrizzleDb, DrizzleResolvedRelation, } from "./nodefony/src/orm-core/index.js";
 export { userTable, createUserTable, createUserEntity, registerUserEntity, } from "./nodefony/entity/userTable.js";
 export type { UserRow } from "./nodefony/entity/userTable.js";

package/dist/types/nodefony/command/migrateShared.d.ts

@@ -107,6 +107,16 @@ export declare abstract class OrmMigrateCommand extends Command {
         }>;
         config: IDrizzleConfig;
     } | null;
+    /**
+     * Arrête une commande qui ÉCRIRAIT une migration pour un connecteur
+     * secondaire dont le nom est celui d'un dossier de dialecte — son dossier
+     * propre se confondrait avec celui des migrations du framework.
+     *
+     * @param connector - connecteur résolu.
+     * @param json - mode machine.
+     * @returns `true` si la commande est arrêtée.
+     */
+    protected refuseReservedConnector(connector: string, json?: boolean): boolean;
     /**
      * Construit l'applicateur d'un connecteur résolu.
      *

package/dist/types/nodefony/command/orm-generate.d.ts

@@ -5,6 +5,7 @@ interface IGenerateOptions extends IMigrateSharedOptions {
     name?: string;
     custom?: boolean;
     allowDestructive?: boolean;
+    apply?: boolean;
 }
 /**
  * `nodefony orm:generate` — écrit la migration qui fera passer la base au
@@ -39,6 +40,17 @@ interface IGenerateOptions extends IMigrateSharedOptions {
  * nodefony orm:migrate        # ou : le travail de déploiement
  * ```
  *
+ * @example En développement — écrire ET appliquer en un seul geste
+ * ```bash
+ * nodefony orm:generate --name ajout_du_titre --apply
+ * ```
+ * `--apply` n'est rien d'autre qu'un `orm:migrate` enchaîné : la commande
+ * DÉLÈGUE, elle ne rejoue pas l'application pour son compte. Toutes les gardes
+ * du verbe d'application valent donc à l'identique — refus du destructif sans
+ * `--allow-destructive`, verrou, historique. Refusé hors développement : un
+ * déploiement n'écrit pas ses migrations au moment de les appliquer, il
+ * applique celles que la revue de code a validées.
+ *
  * @example Ce que le modèle déclaratif ne peut pas déduire
  * ```bash
  * nodefony orm:generate --custom --name vue_des_ventes

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -13,10 +13,14 @@ import type { IDrizzleConfig, IDrizzleConfigInput } from "../interfaces/IDrizzle
  * au boot — cf audit config ORM 2026-06 §3.2.
  *
  * @param config - configuration brute (sections omises = défauts sûrs).
+ * @param declared - ce que l'APPLICATION a écrit elle-même. Au boot, `config`
+ *   arrive déjà fusionné avec les défauts du module (`config.ts`) : on ne peut
+ *   plus y distinguer un `default` demandé d'un `default` posé par défaut. Omis,
+ *   `config` fait foi (appel direct, tests).
  * @returns config validée, surchargée par l'env, et gelée.
  * @throws ZodError si la config est invalide.
  */
-export declare function defineDrizzleConfig(config?: IDrizzleConfigInput): IDrizzleConfig;
+export declare function defineDrizzleConfig(config?: IDrizzleConfigInput, declared?: IDrizzleConfigInput): IDrizzleConfig;
 /**
  * JSON Schema introspectable de la config Drizzle — destiné au formulaire
  * d'édition Studio (futur) et à la documentation générée.