@nodefony/drizzle 10.0.0-alpha.6 → 10.0.0-alpha.8

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

@@ -5,6 +5,7 @@ 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 +16,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é.
 *
@@ -245,7 +272,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 +285,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 +306,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 +328,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 +372,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 +382,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 +477,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 +507,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 +749,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 +938,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/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/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/src/migrator/destructive.d.ts

@@ -62,6 +62,42 @@ export interface IDestructiveFinding {
     /** L'instruction elle-même, bornée pour rester lisible. */
     statement: string;
 }
+/**
+ * Les tables qu'une migration RECONSTRUIT, par la ronde que SQLite impose.
+ *
+ * 🔴 **La convention de nommage n'est PAS la règle.** La version précédente
+ * cherchait le préfixe `__new_` que produit l'outil de génération : elle ne
+ * reconnaissait donc une reconstruction que si c'est LUI qui l'avait écrite.
+ * Une migration reprise à la main — cas courant, et mesuré sur un agent réel
+ * qui avait nommé sa table d'étape `articles_new` — retombait sur
+ * « supprime une table et TOUTES ses lignes », sur un SQL qui ne perd rien.
+ *
+ * Ce qui fait une reconstruction, c'est la RONDE, quels que soient les noms :
+ * une table d'étape est créée, les lignes de la table visée y sont recopiées,
+ * la visée est supprimée, et l'étape prend sa place. Les quatre doivent être
+ * présentes dans le même fichier, et se RÉPONDRE — c'est le renommage final
+ * qui dit quelle table d'étape appartient à quelle table visée.
+ *
+ * ⚠️ Ce n'est pas une garantie que rien n'est perdu : si une colonne n'apparaît
+ * pas dans le `INSERT … SELECT`, ses données disparaissent bel et bien. La
+ * reconstruction reste donc SIGNALÉE, avec le geste — lire le SQL —, et
+ * seulement déclassée en avertissement.
+ *
+ * @param sql - les instructions de la migration, ou le fichier entier.
+ * @returns les tables reconstruites, en minuscules ; vide s'il n'y en a aucune.
+ */
+export declare function rebuiltTables(sql: readonly string[] | string): ReadonlySet<string>;
+/**
+ * Les tables qu'un SQL SUPPRIME, dans l'ordre où il les nomme.
+ *
+ * Exportée pour que l'audit de génération et celui d'application lisent la
+ * MÊME chose : deux extractions écrites séparément divergeraient, et l'une des
+ * deux surfaces se mettrait à refuser ce que l'autre laisse passer.
+ *
+ * @param sql - les instructions de la migration, ou le fichier entier.
+ * @returns les noms supprimés, en minuscules.
+ */
+export declare function droppedTables(sql: readonly string[] | string): string[];
 /**
  * Cherche, dans les migrations en attente, ce qui détruit ou casse.
  *

package/dist/types/nodefony/src/migrator/explain.d.ts

@@ -422,3 +422,22 @@ export declare function refusalInMode(code: IMigrationVerdict["code"], ddl: stri
     meaning: string;
     actions: IMigrationAction[];
 } | null;
+/**
+ * L'échec vient-il de ce que la base est DÉJÀ dans l'état que la migration vise ?
+ *
+ * Le cas est fréquent et sa sortie n'était nommée nulle part : le message de
+ * reprise proposait de corriger le fichier ou de travailler sur une base
+ * d'essai, deux voies qui ne mènent à rien quand le fichier est juste et la
+ * base déjà conforme. Un agent placé devant ce refus tourne alors en rond
+ * — `repair` lève le marqueur, `migrate` rejoue, le moteur redit la même
+ * chose — puis finit par recréer la base, ce qui emporte les données.
+ *
+ * Constaté sur un agent tiers : un `DROP INDEX messages_content_unique` sur une
+ * base dont l'unicité avait été posée INLINE par le DDL de démarrage, donc sans
+ * index nommé. Trente-cinq minutes, deux bases détruites, la boucle brisée à la
+ * main.
+ *
+ * @param message - le message d'erreur rendu par le moteur.
+ * @returns `true` si l'échec dit « c'est déjà ainsi ».
+ */
+export declare function alreadyInTargetState(message: string): boolean;

package/dist/types/nodefony/src/migrator/resolve.d.ts

@@ -50,6 +50,23 @@ export declare function readMigrationEnv(kernel: Kernel | null): IMigrationEnv;
  * @returns `true` si `orm:reset` est recevable.
  */
 export declare function resetAllowed(env: IMigrationEnv): boolean;
+/**
+ * `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.
+ */
+export declare function generateApplyAllowed(env: IMigrationEnv): boolean;
 /**
  * Le mode de schéma qui s'applique à un connecteur.
  *
@@ -62,11 +79,47 @@ export declare function resetAllowed(env: IMigrationEnv): boolean;
  * - 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é.
+ * @param appHasMigrations - l'application versionne au moins une migration.
  * @returns le mode effectif.
  */
-export declare function resolveDdlMode(explicit: DdlMode | undefined, env: IMigrationEnv): DdlMode;
+export declare function resolveDdlMode(explicit: DdlMode | undefined, env: IMigrationEnv, appHasMigrations?: boolean): DdlMode;
+/**
+ * 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`).
+ */
+export declare function appVersionsMigrations(dir: string | undefined): boolean;
 /**
  * La conduite de la sonde de disponibilité face à un schéma en retard.
  *

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;