@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,775 @@
+import { MIGRATE_URL_ENV, MigrationLockTimeoutError, MigrationVerdictError } from "./types.js";
+import { openMigrationDriver } from "./drivers/index.js";
+import { deleteFailed, ensureHistorySchema, finishHistory, forgetEntries, insertHistory, readHistory } from "./history.js";
+import "./paths.js";
+import { createdTables, loadSources } from "./sources.js";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+//#region nodefony/src/migrator/DrizzleMigrator.ts
+/** Délai d'attente du verrou, par défaut. */
+const DEFAULT_LOCK_TIMEOUT_MS = 3e4;
+/** Longueur maximale d'un message d'erreur conservé en base. */
+const ERROR_MAX_LENGTH = 2e3;
+/**
+* Applicateur de migrations de schéma — **le composant qui fait passer une base
+* d'une version à la suivante, et qui garde trace de son passage**.
+*
+* Cinq verbes : {@link DrizzleMigrator.status} (lecture seule),
+* {@link DrizzleMigrator.migrate}, {@link DrizzleMigrator.baseline} (adopter une
+* base déjà peuplée), {@link DrizzleMigrator.repair} (lever un marqueur d'échec
+* après inspection).
+*
+* **Pourquoi un applicateur maison** plutôt que celui de drizzle-orm : ce
+* dernier saute des migrations en silence, ne vérifie jamais les empreintes, ne
+* pose aucun verrou et ne rend aucun état — quatre manques dont chacun se paie
+* en production.
+*
+* **Application par IDENTITÉ, pas par horodatage** : la mise à jour du framework
+* insère des migrations « dans le passé » de l'application, par construction.
+* Un applicateur à repère haut sautrait ces migrations sans un mot ; ici, la
+* liste des restantes est un ENSEMBLE — `(source, tag)` absent de l'historique.
+*
+* @example
+* ```ts
+* const migrator = new DrizzleMigrator({
+*   connector: "default",
+*   dialect: "sqlite",
+*   filename: "var/databases/app.db",
+*   sources: [{ name: "framework", dir: frameworkMigrationsDir, rank: 0 }],
+* });
+* const plan = await migrator.status();
+* if (plan.pending.length) await migrator.migrate();
+* ```
+*/
+/**
+* Ce qu'il faut savoir pour REPRENDRE après une migration en échec.
+*
+* Écrit en toutes lettres parce que son absence a un coût constaté : le
+* message disait vrai — le marqueur bloque la reprise — sans jamais dire que
+* la reprise EXISTE. Un agent qui ne voit pas de sortie s'en invente une, et
+* celle qu'il trouve seul est de recréer la base, ce qui emporte les données.
+*/
+const REPRISE_SANS_DESTRUCTION = "REPRENDRE ne demande PAS de recréer la base. Deux voies, selon ce qui a échoué : corriger le fichier de migration puis lever le marqueur (« orm:migrate:repair ») et reprendre — un fichier corrigé après un échec est rejoué tel quel, son empreinte n'est pas comparée ; ou, si la mise au point demande plusieurs essais, la faire sur une base d'essai en posant « " + MIGRATE_URL_ENV + " », qui détourne la commande vers une AUTRE base et laisse celle-ci intacte — sous PowerShell, poser la variable s'écrit « $env:" + MIGRATE_URL_ENV + " = \"…\" », « env » n'y existant pas. Écrire la migration suivante est toujours préférable à défaire ce qui est déjà appliqué.";
+var DrizzleMigrator = class {
+	#options;
+	#now;
+	/**
+	* @param options - connecteur, cible de connexion et registre de sources.
+	*/
+	constructor(options) {
+		this.#options = options;
+		this.#now = options.now ?? Date.now;
+	}
+	/** Connecteur servi par cet applicateur. */
+	get connector() {
+		return this.#options.connector;
+	}
+	/** Dialecte servi par cet applicateur. */
+	get dialect() {
+		return this.#options.dialect;
+	}
+	/**
+	* État complet de la migration — **lecture seule, sans verrou ni écriture**.
+	*
+	* Sert la ligne de commande, le plan d'administration, la porte d'agent et la
+	* sonde de disponibilité : un seul producteur pour quatre consommateurs. Elle
+	* ne crée pas la table d'historique : une sonde qui écrit dans la base n'est
+	* plus une sonde.
+	*
+	* @returns le plan : appliquées, restantes, dérives, échecs, adoption requise.
+	*/
+	async status() {
+		const driver = await openMigrationDriver(this.#options);
+		try {
+			const history = await driver.tableExists("nodefony_migrations") ? await readHistory(driver) : [];
+			const loaded = await loadSources(this.#options.sources, this.#options.dialect);
+			return await this.#computePlan(driver, loaded.files, history, loaded.absent);
+		} finally {
+			await driver.close();
+		}
+	}
+	/**
+	* Applique les migrations restantes, sous verrou.
+	*
+	* L'ordre : verrou, amorçage de la table d'historique, chargement des
+	* sources, VALIDATION complète, puis application une par une. La validation
+	* précède toute écriture — un refus laisse la base intacte.
+	*
+	* @param options - assouplissements explicites, tous à `false` par défaut.
+	* @returns les migrations effectivement appliquées.
+	* @throws MigrationVerdictError si la validation refuse d'aller plus loin.
+	*/
+	async migrate(options = {}) {
+		const driver = await openMigrationDriver(this.#options);
+		const runId = randomUUID();
+		const applied = [];
+		const isDryRun = options.dryRun === true;
+		try {
+			if (!isDryRun) {
+				await this.#takeLock(driver);
+				await ensureHistorySchema(driver);
+			}
+			const loaded = await loadSources(this.#options.sources, this.#options.dialect);
+			const history = isDryRun && !await driver.tableExists("nodefony_migrations") ? [] : await readHistory(driver);
+			const plan = await this.#computePlan(driver, loaded.files, history, loaded.absent);
+			this.#assertApplicable(plan, loaded.files, options);
+			if (isDryRun) return {
+				runId,
+				applied: []
+			};
+			for (const file of plan.pending) applied.push(await this.#apply(driver, file, runId));
+			return {
+				runId,
+				applied
+			};
+		} finally {
+			await driver.unlock().catch(() => void 0);
+			await driver.close().catch(() => void 0);
+		}
+	}
+	/**
+	* Adopte une base existante : inscrit des migrations **sans exécuter leur SQL**.
+	*
+	* Toujours **explicite**, jamais automatique : une adoption qui se
+	* déclencherait toute seule retirerait le filet qui protège de la pire des
+	* erreurs — se tromper de base. Rejouer l'adoption n'inscrit que ce qui
+	* manque.
+	*
+	* ⚠️ **Cette méthode ne vérifie PAS que la base porte l'état qu'elle
+	* inscrit.** Le contrôle vit chez son appelant (la commande, qui compare la
+	* base au schéma déclaré et refuse `NF_MIGRATE_BASELINE_AMBIGUOUS`). Elle
+	* traverse pourtant la frontière du paquet : un consommateur qui l'appelle
+	* directement DOIT constater l'écart d'abord (`gapAgainstDeclared`), sans
+	* quoi il grave un historique complet devant une base qui ne suit pas — et
+	* plus aucune commande n'offre alors de geste, sinon `repair --forget`.
+	*
+	* @param upTo - dernier tag inscrit (inclus) ; toutes les restantes si omis.
+	* @returns les migrations inscrites.
+	*/
+	/**
+	* Prend le verrou d'applicateur, ou rend un VERDICT plutôt qu'une erreur nue.
+	*
+	* Un verrou tenu n'est pas une panne : c'est le déploiement d'à côté qui
+	* travaille, et la seule bonne réponse est d'attendre puis de reprendre.
+	* C'est précisément ce que le code `NF_MIGRATE_LOCK_TIMEOUT` dit à un
+	* orchestrateur — un code publié dans le contrat, avec sa phrase et son
+	* propre code de sortie, et que POURTANT personne n'émettait : les pilotes
+	* levaient une erreur nue, qui tombait dans le fourre-tout des pannes. Les
+	* branches qui attendaient ce code étaient donc inatteignables.
+	*
+	* @param driver - pilote ouvert sur la base.
+	* @throws MigrationVerdictError si le verrou n'est pas obtenu à temps.
+	*/
+	async #takeLock(driver) {
+		const timeoutMs = this.#options.lockTimeoutMs ?? 3e4;
+		try {
+			await driver.lock(timeoutMs);
+		} catch (e) {
+			if (!(e instanceof MigrationLockTimeoutError)) throw e;
+			throw this.#verdict("NF_MIGRATE_LOCK_TIMEOUT", {
+				facts: { timeoutMs: String(e.timeoutMs) },
+				actions: [{
+					command: `nodefony orm:migrate:status --connector ${this.connector} --json`,
+					args: [
+						"orm:migrate:status",
+						"--connector",
+						this.connector,
+						"--json"
+					]
+				}, {
+					command: `nodefony orm:migrate --connector ${this.connector}`,
+					args: [
+						"orm:migrate",
+						"--connector",
+						this.connector
+					]
+				}]
+			}, e.message);
+		}
+	}
+	/**
+	* Dossier des migrations de l'application, tel qu'on l'écrit dans un GESTE.
+	*
+	* Dérivé du registre de sources, jamais littéral : une application peut
+	* ranger ses migrations ailleurs, et un geste qui nomme un dossier inexistant
+	* est un geste qu'on ne peut pas suivre.
+	*
+	* Écrit avec des barres obliques, toujours : ce chemin VOYAGE — il part dans
+	* une commande que quelqu'un copie, y compris sous Windows, où `git` les
+	* accepte et où le séparateur natif serait une échappée.
+	*
+	* @returns le chemin à citer, terminé par une barre.
+	*/
+	#migrationsPath() {
+		const app = this.#options.sources.find((s) => s.name === "app");
+		if (app === void 0) return "migrations/";
+		return `${path.basename(app.dir).split(path.sep).join("/")}/`;
+	}
+	async baseline(upTo) {
+		const driver = await openMigrationDriver(this.#options);
+		const runId = randomUUID();
+		const adopted = [];
+		try {
+			await this.#takeLock(driver);
+			await ensureHistorySchema(driver);
+			const loaded = await loadSources(this.#options.sources, this.#options.dialect);
+			if (upTo !== void 0) this.#assertKnownTag(upTo, loaded.files);
+			const history = await readHistory(driver);
+			const known = new Set(history.map((row) => identity(row)));
+			for (const file of loaded.files) {
+				const isBoundary = upTo !== void 0 && file.tag === upTo;
+				if (!known.has(identity(file))) {
+					const at = this.#now();
+					await insertHistory(driver, {
+						source: file.source,
+						tag: file.tag,
+						hash: file.hash,
+						runId,
+						startedAt: at,
+						finishedAt: at,
+						executionMs: 0,
+						success: true,
+						error: null,
+						appliedBy: this.#appliedBy()
+					});
+					adopted.push({
+						source: file.source,
+						tag: file.tag,
+						executionMs: 0
+					});
+				}
+				if (isBoundary) break;
+			}
+			return adopted;
+		} finally {
+			await driver.unlock().catch(() => void 0);
+			await driver.close().catch(() => void 0);
+		}
+	}
+	/**
+	* Lève les marqueurs d'échec, **après inspection humaine**.
+	*
+	* Ce n'est pas une reprise : MySQL n'a pas de DDL transactionnel, donc une
+	* migration interrompue y laisse un état partiel que seul un humain peut
+	* qualifier. Réparer dit « j'ai regardé, la base est dans l'état que je
+	* crois » — ensuite seulement la migration se rejoue.
+	*
+	* @param options - source à réparer, et ré-alignement d'empreintes assumé.
+	* @returns ce qui a été levé et ré-aligné.
+	*/
+	async repair(options = {}) {
+		if (options.source !== void 0) this.#assertKnownSource(options.source);
+		for (const target of options.forget ?? []) this.#assertKnownSource(target.source);
+		const driver = await openMigrationDriver(this.#options);
+		try {
+			await this.#takeLock(driver);
+			await ensureHistorySchema(driver);
+			const forgotten = options.forget === void 0 || options.forget.length === 0 ? [] : await forgetEntries(driver, options.forget);
+			const cleared = await deleteFailed(driver, options.source);
+			const rehashed = [];
+			if (options.updateHashes === true) {
+				const loaded = await loadSources(this.#options.sources, this.#options.dialect);
+				const byIdentity = new Map(loaded.files.map((file) => [identity(file), file]));
+				for (const row of await readHistory(driver)) {
+					const file = byIdentity.get(identity(row));
+					if (!file || file.hash === row.hash) continue;
+					await finishHistory(driver, {
+						...row,
+						hash: file.hash
+					});
+					rehashed.push({
+						source: row.source,
+						tag: row.tag
+					});
+				}
+			}
+			return {
+				cleared,
+				rehashed,
+				forgotten
+			};
+		} finally {
+			await driver.unlock().catch(() => void 0);
+			await driver.close().catch(() => void 0);
+		}
+	}
+	/**
+	* Croise fichiers et historique — le calcul commun à `status` et `migrate`.
+	*
+	* @param driver - pilote ouvert (introspection de la garde d'adoption).
+	* @param files - fichiers de toutes les sources présentes.
+	* @param history - lignes de la table d'historique.
+	* @param absent - sources déclarées dont le dossier n'existe pas.
+	* @returns le plan, sans jamais lever : un refus est un CHAMP du plan.
+	*/
+	async #computePlan(driver, files, history, absent) {
+		const byIdentity = new Map(files.map((file) => [identity(file), file]));
+		const declared = new Set(this.#options.sources.map((s) => s.name));
+		const present = new Set(this.#options.sources.filter((s) => !absent.includes(s.name)).map((s) => s.name));
+		const succeeded = /* @__PURE__ */ new Set();
+		const failed = [];
+		const drifted = [];
+		const missing = [];
+		const ignoredSources = /* @__PURE__ */ new Set();
+		for (const row of history) {
+			if (!declared.has(row.source)) {
+				ignoredSources.add(row.source);
+				continue;
+			}
+			if (!row.success || row.finishedAt === null) {
+				failed.push(row);
+				continue;
+			}
+			succeeded.add(identity(row));
+			const file = byIdentity.get(identity(row));
+			if (!file) {
+				if (present.has(row.source)) missing.push({
+					source: row.source,
+					tag: row.tag
+				});
+				continue;
+			}
+			if (file.hash !== row.hash) drifted.push({
+				source: row.source,
+				tag: row.tag,
+				expected: row.hash,
+				actual: file.hash
+			});
+		}
+		const pending = files.filter((file) => !succeeded.has(identity(file)));
+		return {
+			connector: this.#options.connector,
+			dialect: this.#options.dialect,
+			applied: history.filter((row) => row.success && row.finishedAt !== null),
+			pending,
+			drifted,
+			failed,
+			missing,
+			ignoredSources: [...ignoredSources],
+			baselineRequired: history.length === 0 && await hasAnyTable(driver, createdTables(pending))
+		};
+	}
+	/**
+	* Refuse d'appliquer un plan qui ne le permet pas — **fail-loud, avant toute
+	* écriture**.
+	*
+	* @param plan - plan calculé.
+	* @param files - fichiers chargés, qui portent l'index de journal.
+	* @param options - assouplissements explicitement demandés.
+	* @throws MigrationVerdictError portant le verdict structuré.
+	*/
+	#assertApplicable(plan, files, options) {
+		const first = plan.failed[0];
+		if (first) throw this.#verdict("NF_MIGRATE_FAILED_MARKER", {
+			source: first.source,
+			tag: first.tag,
+			facts: {
+				failed: plan.failed.map((row) => `${row.source}/${row.tag}`),
+				error: first.error ?? "interrompue avant la fin"
+			},
+			actions: this.#recoveryActions()
+		}, `La migration « ${first.tag} » (source « ${first.source} ») a échoué ou n'a jamais fini. Inspecter la base, puis réparer avant de reprendre — une reprise aveugle n'est jamais sûre.\n\n${REPRISE_SANS_DESTRUCTION}`);
+		const drift = plan.drifted[0];
+		if (drift) throw this.#verdict("NF_MIGRATE_HASH_MISMATCH", {
+			source: drift.source,
+			tag: drift.tag,
+			facts: {
+				expected: drift.expected,
+				actual: drift.actual
+			},
+			actions: [{
+				command: `git checkout -- ${this.#migrationsPath()}`,
+				args: [
+					"checkout",
+					"--",
+					this.#migrationsPath()
+				]
+			}, {
+				command: `nodefony orm:migrate:repair --update-hashes --connector ${this.connector}`,
+				args: [
+					"orm:migrate:repair",
+					"--update-hashes",
+					"--connector",
+					this.connector
+				]
+			}]
+		}, `Le fichier de la migration « ${drift.tag} » (source « ${drift.source} ») a changé depuis son application. Une migration déjà jouée est immuable : écrire une NOUVELLE migration, ou assumer le ré-alignement.`);
+		const gone = plan.missing[0];
+		if (gone && options.ignoreMissing !== true) throw this.#verdict("NF_MIGRATE_MISSING_FILE", {
+			source: gone.source,
+			tag: gone.tag,
+			facts: { missing: plan.missing.map((m) => `${m.source}/${m.tag}`) },
+			actions: [{
+				command: `nodefony orm:migrate --ignore-missing --connector ${this.connector}`,
+				args: [
+					"orm:migrate",
+					"--ignore-missing",
+					"--connector",
+					this.connector
+				]
+			}]
+		}, `La migration « ${gone.tag} » est enregistrée en base mais son fichier a disparu de la source « ${gone.source} », qui est pourtant installée.`);
+		if (options.outOfOrder !== true) {
+			const outOfOrder = this.#findOutOfOrder(plan, files);
+			if (outOfOrder) throw this.#verdict("NF_MIGRATE_OUT_OF_ORDER", {
+				source: outOfOrder.source,
+				tag: outOfOrder.tag,
+				facts: {
+					idx: outOfOrder.idx,
+					lastApplied: outOfOrder.lastApplied
+				},
+				actions: [{
+					command: `nodefony orm:migrate --out-of-order --connector ${this.connector}`,
+					args: [
+						"orm:migrate",
+						"--out-of-order",
+						"--connector",
+						this.connector
+					]
+				}]
+			}, `La migration « ${outOfOrder.tag} » se range AVANT « ${outOfOrder.lastApplied} », déjà appliquée dans la source « ${outOfOrder.source} ». L'appliquer maintenant produirait une base dont l'histoire n'est pas celle des autres.`);
+		}
+		if (plan.baselineRequired) throw this.#verdict("NF_MIGRATE_BASELINE_REQUIRED", {
+			facts: { pending: plan.pending.map((file) => file.tag) },
+			actions: [{
+				command: `nodefony orm:migrate:baseline --connector ${this.connector}`,
+				args: [
+					"orm:migrate:baseline",
+					"--connector",
+					this.connector
+				]
+			}]
+		}, "Cette base porte déjà les tables du schéma mais n'a aucun historique de migration : elle est antérieure aux migrations. L'adopter explicitement (baseline) avant d'appliquer quoi que ce soit.");
+	}
+	/**
+	* Cherche une migration restante antérieure à la dernière appliquée de SA source.
+	*
+	* Le contrôle est **par source** : la mise à jour du framework insère
+	* légitimement des migrations dans le passé de l'application — c'est
+	* l'intérieur d'une même source qui doit rester ordonné. L'index vient du
+	* JOURNAL, jamais d'une lecture du tag : un tag est une identité, pas un
+	* nombre, et rien n'oblige un module tiers à le préfixer de chiffres.
+	*
+	* @param plan - plan calculé.
+	* @param files - fichiers chargés, qui portent l'index de journal.
+	* @returns la première migration hors ordre, ou `undefined`.
+	*/
+	#findOutOfOrder(plan, files) {
+		const appliedIdentities = new Set(plan.applied.map((row) => identity(row)));
+		const highest = /* @__PURE__ */ new Map();
+		for (const file of files) {
+			if (!appliedIdentities.has(identity(file))) continue;
+			const current = highest.get(file.source);
+			if (!current || file.idx > current.idx) highest.set(file.source, {
+				tag: file.tag,
+				idx: file.idx
+			});
+		}
+		for (const file of plan.pending) {
+			const high = highest.get(file.source);
+			if (high && file.idx < high.idx) return {
+				source: file.source,
+				tag: file.tag,
+				idx: file.idx,
+				lastApplied: high.tag
+			};
+		}
+	}
+	/**
+	* Applique UNE migration, selon ce que le dialecte garantit.
+	*
+	* PostgreSQL et SQLite ont un DDL transactionnel : le schéma et sa trace
+	* entrent ensemble ou pas du tout, et le marqueur d'échec est écrit HORS de
+	* la transaction annulée — sinon il disparaîtrait avec elle. MySQL n'a pas ce
+	* luxe : la trace de début est posée AVANT, et un process tué en plein vol
+	* laisse une ligne sans fin, que la validation refusera au prochain passage.
+	*
+	* @param driver - pilote sous verrou.
+	* @param file - migration à appliquer.
+	* @param runId - identifiant du run.
+	* @returns ce qui a été appliqué, et en combien de temps.
+	*/
+	async #apply(driver, file, runId) {
+		const startedAt = this.#now();
+		const began = performance.now();
+		const row = {
+			source: file.source,
+			tag: file.tag,
+			hash: file.hash,
+			runId,
+			startedAt,
+			finishedAt: null,
+			executionMs: null,
+			success: false,
+			error: null,
+			appliedBy: this.#appliedBy()
+		};
+		if (!driver.transactionalDdl) {
+			await insertHistory(driver, row);
+			try {
+				for (const statement of file.statements) await driver.exec(statement);
+			} catch (e) {
+				await finishHistory(driver, {
+					...row,
+					finishedAt: this.#now(),
+					executionMs: Math.round(performance.now() - began),
+					success: false,
+					error: truncate(e.message)
+				});
+				throw this.#applyFailure(file, e, false);
+			}
+			const executionMs = Math.round(performance.now() - began);
+			await finishHistory(driver, {
+				...row,
+				finishedAt: this.#now(),
+				executionMs,
+				success: true
+			});
+			return {
+				source: file.source,
+				tag: file.tag,
+				executionMs
+			};
+		}
+		await driver.begin();
+		try {
+			if ((await readHistory(driver)).some((r) => r.source === file.source && r.tag === file.tag)) return {
+				source: file.source,
+				tag: file.tag,
+				executionMs: Math.round(performance.now() - began)
+			};
+			for (const statement of file.statements) await driver.exec(statement);
+			const executionMs = Math.round(performance.now() - began);
+			await insertHistory(driver, {
+				...row,
+				finishedAt: this.#now(),
+				executionMs,
+				success: true
+			});
+			await driver.commit();
+			return {
+				source: file.source,
+				tag: file.tag,
+				executionMs
+			};
+		} catch (e) {
+			await driver.rollback().catch(() => void 0);
+			await insertHistory(driver, {
+				...row,
+				finishedAt: this.#now(),
+				executionMs: Math.round(performance.now() - began),
+				success: false,
+				error: truncate(e.message)
+			}).catch(() => void 0);
+			throw this.#applyFailure(file, e, true);
+		}
+	}
+	/**
+	* Habille l'échec d'une migration en VERDICT, plutôt qu'en exception nue.
+	*
+	* C'est le cas d'incident nominal du produit : un travail de déploiement
+	* applique, et la quatrième migration bute sur une contrainte. Laissée nue,
+	* l'erreur tombait dans le fourre-tout des pannes, qui affirme trois choses
+	* fausses au pire moment — que la base n'a pas répondu (elle a très bien
+	* répondu, c'est le SQL qui a échoué), que rien n'a été modifié (le marqueur
+	* d'échec vient d'être posé, les migrations précédentes du même passage sont
+	* appliquées, et sur un moteur sans DDL transactionnel la moitié de la
+	* fautive peut être en place), et en rendant 2 — « la commande n'a pas pu
+	* travailler » — là où la grille range un échec de migration en 1, celui qui
+	* appelle un humain. Un orchestrateur qui réessaie sur 2 rejouait un échec
+	* déterministe.
+	*
+	* @param file - migration qui a échoué.
+	* @param cause - erreur rendue par le moteur.
+	* @param transactionnel - le DDL de ce moteur est-il transactionnel ?
+	* @returns le verdict à lever.
+	*/
+	#applyFailure(file, cause, transactionnel) {
+		const state = transactionnel ? `Cette migration a été ANNULÉE — le schéma de ce moteur entre ou n'entre pas, jamais à moitié. Les migrations appliquées AVANT elle, dans ce même passage, restent en place.` : `Ce moteur n'annule pas le schéma : cette migration peut être appliquée À MOITIÉ. Inspecter la base avant toute reprise — c'est pour cela que la reprise n'est pas automatique.`;
+		return this.#verdict("NF_MIGRATE_FAILED_MARKER", {
+			source: file.source,
+			tag: file.tag,
+			facts: { error: truncate(cause.message) },
+			actions: this.#recoveryActions()
+		}, `La migration « ${file.tag} » (source « ${file.source} ») a échoué : ${truncate(cause.message)}\n\n${state}\n\nSon échec est INSCRIT : le prochain passage refusera de reprendre tant que le marqueur n'aura pas été levé, après inspection.\n\n${REPRISE_SANS_DESTRUCTION}`);
+	}
+	/**
+	* Les gestes qui sortent d'une migration en échec — **sans toucher à la base**.
+	*
+	* Ce refus ne proposait que d'inspecter et de lever le marqueur. Les deux
+	* sont vrais, et aucun ne dit ce qu'il advient du fichier fautif : il est
+	* toujours là, il rééchouera au passage suivant. Mesuré sur le banc de
+	* découvrabilité, un agent placé devant ce message a écrit « je vais
+	* réinitialiser la base et réécrire la migration » — non par désinvolture,
+	* mais parce que **recréer la base était le seul geste de reprise qu'il
+	* voyait**. Une migration qui échoue est pourtant l'incident le plus
+	* ordinaire du métier, et le produit sait en sortir de deux façons.
+	*
+	* Les deux sont donc NOMMÉES, dans l'ordre où on s'en sert : corriger le
+	* fichier puis reprendre — ce qui fonctionne parce qu'une entrée en échec
+	* n'entre jamais dans les fichiers dont l'empreinte est comparée
+	* (`#plan` : `success === false` sort avant le contrôle d'empreinte), donc
+	* un fichier corrigé après un échec est rejoué sans réclamer d'alignement —
+	* et mettre au point sur une base d'essai, ce qui est exactement ce que
+	* {@link MIGRATE_URL_ENV} sert à faire.
+	*
+	* @returns les gestes, du plus direct au plus assumé.
+	*/
+	#recoveryActions() {
+		return [
+			{
+				command: `nodefony orm:migrate:status --connector ${this.connector} --json`,
+				args: [
+					"orm:migrate:status",
+					"--connector",
+					this.connector,
+					"--json"
+				]
+			},
+			{
+				command: `nodefony orm:migrate:repair --connector ${this.connector}`,
+				args: [
+					"orm:migrate:repair",
+					"--connector",
+					this.connector
+				]
+			},
+			{
+				command: `nodefony orm:migrate --connector ${this.connector}`,
+				args: [
+					"orm:migrate",
+					"--connector",
+					this.connector
+				]
+			}
+		];
+	}
+	/**
+	* Fabrique une erreur portant son verdict structuré.
+	*
+	* @param code - code stable du refus.
+	* @param detail - source, tag, faits et actions.
+	* @param message - phrase française pour un humain.
+	* @returns l'erreur, prête à être levée.
+	*/
+	#verdict(code, detail, message) {
+		return new MigrationVerdictError({
+			code,
+			connector: this.connector,
+			source: detail.source,
+			tag: detail.tag,
+			facts: detail.facts,
+			nextActions: detail.actions
+		}, message);
+	}
+	/**
+	* Refuse un `--up-to` qui ne désigne aucune migration connue.
+	*
+	* Sans ce contrôle, la boucle d'adoption ne rencontre jamais sa condition
+	* d'arrêt et inscrit **tout** l'historique : une faute de frappe déclare à
+	* niveau des migrations que la base n'a jamais reçues, et elle ne les
+	* recevra plus jamais. Le geste le plus destructeur de la chaîne est aussi
+	* celui qui se tapait sans filet.
+	*
+	* @param upTo - tag demandé.
+	* @param files - fichiers connus, toutes sources confondues.
+	* @throws MigrationVerdictError quand le tag est inconnu.
+	*/
+	#assertKnownTag(upTo, files) {
+		if (files.some((file) => file.tag === upTo)) return;
+		const tags = files.map((file) => file.tag);
+		const casedTag = tags.find((tag) => tag.toLowerCase() === upTo.toLowerCase());
+		const action = casedTag ?? tags[tags.length - 1];
+		throw this.#verdict("NF_MIGRATE_UNKNOWN_TAG", {
+			tag: upTo,
+			facts: {
+				known: tags,
+				...casedTag ? { caseMismatch: casedTag } : {}
+			},
+			actions: action ? [{
+				command: `nodefony orm:migrate:baseline --connector ${this.connector} --up-to ${action}`,
+				args: [
+					"orm:migrate:baseline",
+					"--connector",
+					this.connector,
+					"--up-to",
+					action
+				]
+			}] : [{
+				command: `nodefony orm:migrate:status --connector ${this.connector}`,
+				args: [
+					"orm:migrate:status",
+					"--connector",
+					this.connector
+				]
+			}]
+		}, casedTag ? `Le tag « ${upTo} » n'existe pas, mais « ${casedTag} » oui : un tag de migration est SENSIBLE à la casse. Sans ce refus, l'adoption ne se serait arrêtée nulle part et aurait déclaré à niveau TOUTES les migrations connues.` : `Le tag « ${upTo} » ne désigne aucune migration connue. L'adoption s'arrête ici plutôt que de déclarer à niveau TOUT l'historique : une base ne reçoit jamais une migration qu'elle croit déjà avoir.`);
+	}
+	/**
+	* Refuse un `--source` que cette application ne déclare pas.
+	*
+	* Le filtre part sinon en SQL sur un nom qui n'existe pas : zéro ligne
+	* touchée, code 0, « Rien à réparer ». L'exploitant croit avoir réparé et
+	* relance une migration qui échouera pour la même raison qu'avant.
+	*
+	* @param source - nom demandé.
+	* @throws MigrationVerdictError quand la source n'est pas déclarée.
+	*/
+	#assertKnownSource(source) {
+		const names = this.#options.sources.map((s) => s.name);
+		if (names.includes(source)) return;
+		const casedTag = names.find((name) => name.toLowerCase() === source.toLowerCase());
+		throw this.#verdict("NF_MIGRATE_UNKNOWN_SOURCE", {
+			source,
+			facts: {
+				known: names,
+				...casedTag ? { caseMismatch: casedTag } : {}
+			},
+			actions: [{
+				command: casedTag ? `nodefony orm:migrate:repair --connector ${this.connector} --source ${casedTag}` : `nodefony orm:migrate:repair --connector ${this.connector}`,
+				args: casedTag ? [
+					"orm:migrate:repair",
+					"--connector",
+					this.connector,
+					"--source",
+					casedTag
+				] : [
+					"orm:migrate:repair",
+					"--connector",
+					this.connector
+				]
+			}]
+		}, casedTag ? `La source « ${source} » n'est pas déclarée, mais « ${casedTag} » oui : un nom de source est SENSIBLE à la casse. Réparer sur un nom inconnu ne touche rien et rend pourtant « rien à réparer ».` : `La source « ${source} » n'est pas déclarée par cette application. Réparer sur un nom inconnu ne touche rien et rend pourtant « rien à réparer » — le marqueur d'échec resterait en place.`);
+	}
+	/** Qui a appliqué — l'hôte du job, sauf indication contraire. */
+	#appliedBy() {
+		return this.#options.appliedBy ?? os.hostname();
+	}
+};
+/** Identité d'une migration : `(source, tag)`, jamais un horodatage. */
+function identity(row) {
+	return `${row.source}\0${row.tag}`;
+}
+/**
+* Au moins une de ces tables existe-t-elle déjà ?
+*
+* @param driver - pilote ouvert.
+* @param tables - tables que les migrations restantes créeraient.
+* @returns `true` dès la première trouvée.
+*/
+async function hasAnyTable(driver, tables) {
+	for (const table of tables) if (await driver.tableExists(table)) return true;
+	return false;
+}
+/**
+* Borne un message d'erreur avant de l'écrire en base.
+*
+* @param message - message brut.
+* @returns le message, tronqué si nécessaire.
+*/
+function truncate(message) {
+	return message.length > ERROR_MAX_LENGTH ? `${message.slice(0, ERROR_MAX_LENGTH)}…` : message;
+}
+//#endregion
+export { DEFAULT_LOCK_TIMEOUT_MS, DrizzleMigrator };