@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,139 @@
+import type { SqlDialect } from "../../config/config.js";
+import { type IAppliedMigration, type IMigrationDriver } from "./types.js";
+/**
+ * Table d'historique : sa création, son amorçage, et sa lecture.
+ *
+ * 🔴 **La table qui sert à migrer doit savoir se migrer ELLE-MÊME.** Un
+ * `CREATE TABLE IF NOT EXISTS` seul ne fait pas évoluer un schéma, et le jour
+ * où une version ultérieure veut une colonne de plus, elle ne peut pas passer
+ * par une migration ordinaire : l'applicateur LIT cette table avant d'appliquer
+ * quoi que ce soit — il planterait sur une base ancienne avant d'avoir pu se
+ * réparer. Œuf et poule.
+ *
+ * D'où un amorçage interne versionné, HORS du flux des migrations : la table
+ * est créée au format d'origine, puis une liste d'`ALTER` ordonnés est
+ * appliquée selon ce que l'introspection trouve. **Pas de colonne de version** :
+ * la PRÉSENCE des colonnes EST la version — deux mécanismes pour une seule
+ * question, ce serait zéro mécanisme.
+ */
+/**
+ * Étape d'amorçage : une colonne ajoutée après le format d'origine.
+ *
+ * L'ordre du tableau fait foi et ne se réarrange pas : c'est lui qui garantit
+ * qu'une base restée trois versions en arrière rattrape le même état qu'une
+ * base neuve.
+ */
+export interface IHistoryStep {
+    /** Colonne dont la présence atteste que l'étape est faite. */
+    column: string;
+    /** DDL à exécuter, par dialecte. */
+    ddl: Record<SqlDialect, string>;
+}
+/**
+ * Étapes d'amorçage postérieures au format d'origine.
+ *
+ * **Vide dans cette version** — l'étape 0 est le `CREATE` lui-même. Ce tableau
+ * est le point d'extension : ajouter une colonne à l'historique, aujourd'hui ou
+ * dans cinq versions, se fait ICI et nulle part ailleurs.
+ */
+export declare const HISTORY_STEPS: readonly IHistoryStep[];
+/**
+ * Le moteur se plaint-il d'une COLONNE d'historique qu'il ne trouve pas ?
+ *
+ * Reconnaît la table d'historique d'une AUTRE provenance : la table porte le
+ * bon nom, elle n'a pas les bonnes colonnes. `CREATE TABLE IF NOT EXISTS` ne
+ * la répare pas — elle existe —, et la première lecture échoue sur un message
+ * de moteur brut, que le fourre-tout des pannes habille alors de deux causes
+ * FAUSSES : « la base n'a pas répondu » et « les droits manquent ». Mesuré au
+ * banc : c'est ce message qui a renvoyé un agent détruire une base de
+ * production après qu'il eut pourtant suivi le conseil de travailler sur une
+ * copie — copie qu'il avait dû fabriquer à la main, avec un historique inventé.
+ *
+ * PURE, et une grammaire par moteur : les trois formulent la même panne dans
+ * trois langues, et un motif écrit pour l'une est muet pour les deux autres.
+ * Bornée aux colonnes que ce fichier déclare : une colonne APPLICATIVE
+ * manquante est un tout autre incident, qui a déjà sa voie.
+ *
+ * @param message - message d'erreur rendu par le pilote.
+ * @returns la colonne d'historique introuvable, ou `null`.
+ */
+export declare function missingHistoryColumn(message: string): string | null;
+/**
+ * Crée la table d'historique si besoin, puis l'amène au format courant.
+ *
+ * À appeler **juste après le verrou et AVANT la moindre lecture** : c'est
+ * l'ordre qui rend l'évolution de la table possible sans outil de conversion
+ * chez l'utilisateur.
+ *
+ * @param driver - pilote à connexion unique, verrou déjà tenu.
+ * @returns les colonnes ajoutées par l'amorçage (vide dans le cas courant).
+ */
+export declare function ensureHistorySchema(driver: IMigrationDriver): Promise<string[]>;
+/**
+ * Lit l'historique complet, **colonnes nommées une par une**.
+ *
+ * Jamais `SELECT *` : c'est ce qui rend l'ajout d'une colonne inoffensif pour
+ * un applicateur plus ancien, qui continue de lire exactement ce qu'il connaît.
+ *
+ * @param driver - pilote à connexion unique.
+ * @returns les lignes, dans leur ordre d'insertion.
+ */
+export declare function readHistory(driver: IMigrationDriver): Promise<IAppliedMigration[]>;
+/**
+ * `INSERT` d'une ligne d'historique — **jamais positionnel**.
+ *
+ * @param driver - pilote à connexion unique.
+ * @param row - ligne à écrire.
+ */
+export declare function insertHistory(driver: IMigrationDriver, row: IAppliedMigration): Promise<void>;
+/**
+ * Marque une ligne d'historique terminée (chemin MySQL, DDL non transactionnel).
+ *
+ * @param driver - pilote à connexion unique.
+ * @param row - ligne dont le résultat est connu.
+ */
+export declare function finishHistory(driver: IMigrationDriver, row: IAppliedMigration): Promise<void>;
+/**
+ * Supprime les marqueurs d'échec d'une source, ou de toutes.
+ *
+ * @param driver - pilote à connexion unique.
+ * @param source - source à réparer ; toutes si omise.
+ * @returns les migrations dont le marqueur a été levé.
+ */
+export declare function deleteFailed(driver: IMigrationDriver, source?: string): Promise<{
+    source: string;
+    tag: string;
+}[]>;
+/**
+ * Désinscrit UNE entrée nommée de l'historique, quel que soit son état.
+ *
+ * ## Pourquoi ce geste existe, alors qu'un interdit dit de ne pas y toucher
+ *
+ * L'interdit porte sur la modification À LA MAIN, dans un client SQL, sans
+ * trace. Il existait pourtant un état dont AUCUNE commande ne sortait : une
+ * migration inscrite `success` que personne n'a jamais exécutée — une adoption
+ * mal bornée, une base héritée d'une version antérieure aux gardes. Le
+ * générateur disait « c'est l'historique qu'il faut reprendre » et renvoyait
+ * vers la réparation, qui ne sait lever que des marqueurs d'ÉCHEC : elle
+ * répondait « rien à réparer », et l'on revenait au point de départ. Trois
+ * messages vrais, aucun geste — et le seul chemin restant était de détruire la
+ * base.
+ *
+ * Le geste est donc rendu au produit, où il laisse une trace et où il est
+ * BORNÉ : une entrée précisément nommée, jamais un lot, jamais un motif.
+ *
+ * ⚠️ Ne touche pas la base : après cet oubli, la migration sera REJOUÉE au
+ * prochain passage. Si elle avait réellement été appliquée, ce rejeu échouera
+ * — bruyamment, ce qui est le comportement voulu.
+ *
+ * @param driver - pilote sous verrou.
+ * @param entries - entrées à désinscrire, chacune nommée `source` et `tag`.
+ * @returns celles qui existaient et ont été retirées.
+ */
+export declare function forgetEntries(driver: IMigrationDriver, entries: readonly {
+    source: string;
+    tag: string;
+}[]): Promise<{
+    source: string;
+    tag: string;
+}[]>;

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

@@ -0,0 +1,20 @@
+/**
+ * Applicateur de migrations de schéma du module drizzle.
+ *
+ * Il **planifie, valide, applique, adopte et répare** — avec sa table
+ * d'historique et son verrou natif par dialecte. Les fichiers, eux, sont
+ * produits par `npm run generate:migrations` (drizzle-kit) et livrés dans le
+ * paquet.
+ */
+export { DrizzleMigrator, DEFAULT_LOCK_TIMEOUT_MS, type IDrizzleMigratorOptions, type IMigrateOptions, } from "./DrizzleMigrator.js";
+export { openMigrationDriver, SqliteMigrationDriver, PostgresMigrationDriver, MysqlMigrationDriver, PG_LOCK_KEY, MYSQL_LOCK_NAME_SQL, MYSQL_LOCK_PREFIX, type IMigrationTarget, } from "./drivers/index.js";
+export { ensureHistorySchema, readHistory, HISTORY_STEPS, type IHistoryStep, } from "./history.js";
+export { migrationHash, normalizeSql } from "./hash.js";
+export { checkMigrationName, suggestMigrationName, MIGRATION_NAME_MAX, type MigrationNameCheck, } from "./name.js";
+export { schemaReader, sameColumnName, type ISchemaReader, type SqlQuery, } from "./catalog.js";
+export { comparisonAgainstDeclared, describeDivergence, gapAgainstDeclared, } from "./divergence.js";
+export { adoptFromDatabase, introspectionUrl, readJournal, snapshotTables, tablesPresentIn, uncommentIntrospection, type IAdoptedBaseline, } from "./adopt.js";
+export { compareSchema, additiveSql, hasGap, type ISchemaComparison, type ISchemaGap, type IExpectedTable, } from "./schemaDiff.js";
+export { frameworkMigrationsDir, defaultMigrationSources, FRAMEWORK_SOURCE, APP_SOURCE, FRAMEWORK_RANK, APP_RANK, } from "./paths.js";
+export { loadSources, orderSources, splitStatements, createdTables, SUPPORTED_JOURNAL_VERSIONS, type ILoadedSources, frameworkTables, } from "./sources.js";
+export { HISTORY_TABLE, FORMAT_MARKER, STATEMENT_BREAKPOINT, MigrationVerdictError, type IAppliedMigration, type IMigrationAction, type IMigrationApplied, type IMigrationDrift, type IMigrationDriver, type IMigrationFile, type IMigrationPlan, type IMigrationRun, type IMigrationSource, type IMigrationVerdict, type MigrationVerdictCode, } from "./types.js";

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

@@ -0,0 +1,141 @@
+import type { SqlDialect } from "../../interfaces/IDrizzleConfig.js";
+/** Ce qu'une règle d'audit rend quand elle reconnaît une instruction. */
+export interface IAuditRule {
+    /** Identifiant stable de la règle (cité dans les messages et les tests). */
+    id: string;
+    /** Ce que l'instruction fait à la base. */
+    what: string;
+    /** La manœuvre sûre — un refus qui ne dit pas quoi faire ne sert à rien. */
+    todo: string;
+}
+/** Verdict d'une relecture de migration. */
+export interface IMigrationAudit {
+    /** Ce qui détruit des données : refusé sans consentement explicite. */
+    destructive: IAuditRule[];
+    /** Ce qui verrouille en production : signalé, jamais bloquant. */
+    blocking: IAuditRule[];
+}
+/**
+ * Marqueur de format, RÉ-EXPORTÉ depuis sa seule définition.
+ *
+ * Il était défini deux fois dans ce même dossier : ici pour l'ÉCRIRE, dans
+ * `types.ts` pour le LIRE. Le jour d'un `format=2`, celui qui édite l'une des
+ * deux copies fabrique un générateur qui estampille un format que le lecteur
+ * refuse — chaque copie restant verte dans ses propres tests.
+ */
+export { FORMAT_MARKER } from "./types.js";
+/**
+ * Résout le binaire de `drizzle-kit` sans passer par un lanceur de shell.
+ *
+ * `npx` est un `.cmd` sous Windows, inexécutable sans `shell: true` — qui
+ * rouvrirait une injection par le nom de migration. Le paquet n'exporte pas son
+ * binaire (`exports` ne couvre que `.` et `./api`), donc on remonte les dossiers
+ * `node_modules` comme le ferait Node.
+ *
+ * @param from - dossier de départ de la remontée (racine du paquet qui génère,
+ *   ou racine de l'application).
+ * @returns chemin absolu de `bin.cjs`.
+ * @throws Error si `drizzle-kit` n'est pas installé au-dessus de `from`.
+ */
+export declare function resolveDrizzleKitBin(from: string): string;
+/**
+ * Lance `drizzle-kit generate` et EXIGE la preuve qu'il a tourné.
+ *
+ * @param options - `cwd` (dossier depuis lequel l'outil est lancé — les chemins
+ *   de la configuration lui sont relatifs), `configRel` (configuration, chemin
+ *   relatif à `cwd`), `name` (nom imposé de la migration), `label` (ce qui est
+ *   cité dans l'erreur).
+ * @returns la sortie complète de l'outil (sortie standard puis sortie d'erreur).
+ * @throws Error si le code est non nul, ou si rien ne prouve que la génération a
+ *   eu lieu — l'absence de preuve n'est JAMAIS lue comme « rien à faire ».
+ */
+export declare function runGenerate({ cwd, configRel, name, label, regenerateCommand, }: {
+    cwd: string;
+    configRel: string;
+    name: string;
+    label: string;
+    /** La commande à rejouer dans un terminal, citée quand l'outil pose une question. */
+    regenerateCommand?: string;
+}): string;
+/**
+ * Lance `drizzle-kit introspect` et EXIGE la preuve qu'il a travaillé.
+ *
+ * C'est la seule commande de la chaîne qui LIT la base pour en tirer des
+ * fichiers. Elle sert l'adoption d'une base qui existait avant les migrations :
+ * l'instantané qu'elle dépose décrit l'état RÉEL, celui à partir duquel la
+ * génération suivante produira un `ALTER` au lieu d'un `CREATE TABLE`.
+ *
+ * La preuve n'est pas cherchée dans le texte de l'outil mais dans ce qu'il
+ * LAISSE : l'appelant relit le journal des fichiers. Ici on ne garde que le
+ * refus le plus grossier — un code de sortie non nul —, parce que l'outil rend
+ * `0` même en échec et qu'un marqueur de texte a déjà menti une fois (il change
+ * avec la couleur du terminal).
+ *
+ * @param options - `cwd` (dossier depuis lequel l'outil est lancé), `configRel`
+ *   (configuration, chemin relatif à `cwd`), `label` (ce qui est cité en cas
+ *   d'échec).
+ * @returns la sortie complète de l'outil.
+ * @throws Error si le code est non nul.
+ */
+export declare function runIntrospect({ cwd, configRel, label, }: {
+    cwd: string;
+    configRel: string;
+    label: string;
+}): string;
+/**
+ * La génération a-t-elle EU LIEU ? — lue sur une sortie DÉCOLORÉE.
+ *
+ * L'outil ne rend pas de code d'échec (il sort 0 même quand il rate) : la seule
+ * preuve disponible est un marqueur dans son texte. Encore faut-il le chercher
+ * dans le texte, et non dans sa mise en forme.
+ *
+ * 🔴 **Le piège, payé en intégration continue** : la forge pose `FORCE_COLOR`,
+ * l'outil colore alors sa coche — `[`, une séquence d'échappement, `✓`, une
+ * autre séquence, `]` — et `"[✓]"` n'est plus une sous-chaîne. La génération
+ * réussissait, le fichier était écrit, et l'appelant annonçait qu'elle n'avait
+ * pas eu lieu. Vert sur un poste sans terminal, rouge à la forge : la sonde
+ * mesurait la présentation.
+ *
+ * Fonction PURE, pour qu'elle s'éprouve sans lancer un process — une règle qui
+ * exige un sous-processus pour être vue rouge n'est jamais vue rouge.
+ *
+ * @param output - sortie complète de l'outil, telle qu'elle a été capturée.
+ * @returns `true` si l'outil dit avoir écrit, ou n'avoir rien eu à écrire.
+ */
+export declare function generationHappened(output: string): boolean;
+/**
+ * Analyse le SQL d'une migration et rend ce qui mérite un refus ou un regard.
+ *
+ * Volontairement **textuelle** : il ne s'agit pas d'analyser du SQL, mais de
+ * refuser de laisser passer sans un mot ce qui détruit des données. Un motif de
+ * trop fait poser une question ; un motif de moins fait perdre une table.
+ *
+ * @param sql - contenu d'un fichier de migration.
+ * @param dialect - dialecte concerné (certains risques lui sont propres).
+ * @returns `{ destructive, blocking }`, chacun décrivant ce qui a été reconnu.
+ */
+export declare function auditMigrationSql(sql: string, dialect: SqlDialect): IMigrationAudit;
+/**
+ * Reconnaît l'échec de `drizzle-kit` faute de terminal interactif.
+ *
+ * L'outil pose une question — « cette colonne a-t-elle été renommée, ou
+ * supprimée puis ajoutée ? » — à laquelle lui seul ne peut pas répondre. Sans
+ * terminal, il échoue, et **rend 0**. Sans reconnaissance explicite, l'utilisateur
+ * reçoit une pile d'appels de l'outil au lieu de la seule chose qui compte : la
+ * question qu'on lui pose, et où y répondre.
+ *
+ * @param output - sortie complète de l'outil.
+ * @returns `true` si l'échec vient d'une question restée sans terminal.
+ */
+export declare function isInteractivePromptFailure(output: string): boolean;
+/**
+ * Pose le marqueur de format en tête des `.sql` d'un dossier qui ne l'ont pas.
+ *
+ * Écrit en fins de ligne `\n` quel que soit le système : le dépôt et le gabarit
+ * d'application déclarent `* text=auto eol=lf`, sans quoi une copie de travail
+ * Windows produirait une fausse dérive à chaque lecture.
+ *
+ * @param dir - dossier `<sortie>/<dialecte>` dont on marque les fichiers.
+ * @returns le nombre de fichiers marqués.
+ */
+export declare function stampFormatMarker(dir: string): number;

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

@@ -0,0 +1,52 @@
+/**
+ * Ce qu'un nom de migration a le droit d'être — et ce qu'on propose sinon.
+ *
+ * **Pourquoi une fonction pure, à part de la commande** : ce nom entre dans le
+ * tag du fichier, et un tag ne se renomme plus une fois la migration appliquée
+ * quelque part — c'est lui qui dit à chaque base ce qu'elle a déjà reçu. La
+ * règle qui le garde mérite donc d'être exerçable sans démarrer une
+ * application : un contrôle qui coûte trois minutes est un contrôle qu'on
+ * saute.
+ */
+/**
+ * Longueur maximale d'un nom de migration.
+ *
+ * Le tag complet vaut `NNNN_<nom>` et le fichier `<tag>.sql` : à 120
+ * caractères, on reste très en deçà des 255 octets qu'un système de fichiers
+ * accepte pour un nom, et loin des 260 caractères qu'un chemin Windows tolère
+ * par défaut. La borne n'est pas là pour économiser des octets — elle est là
+ * pour qu'un nom trop long échoue AVANT d'avoir écrit un fichier, avec une
+ * phrase, plutôt qu'au moment de l'écriture avec un code d'erreur système.
+ */
+export declare const MIGRATION_NAME_MAX = 120;
+/** Verdict d'une vérification de nom. */
+export type MigrationNameCheck = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    /** Ce qui ne va pas, en une phrase française. */
+    reason: string;
+    /**
+     * Un nom valide à proposer, quand on peut en dériver un qui a du sens.
+     *
+     * **Jamais un nom que la commande refuserait ensuite** : proposer un
+     * geste qui échoue est pire que ne rien proposer, parce qu'il fait perdre
+     * un aller-retour ET la confiance dans les autres suggestions.
+     */
+    suggestion?: string;
+};
+/**
+ * Dérive un nom acceptable d'une saisie qui ne l'est pas.
+ *
+ * @param input - ce que l'utilisateur a tapé.
+ * @returns un nom conforme, ou `undefined` s'il n'en reste rien de sensé.
+ */
+export declare function suggestMigrationName(input: string): string | undefined;
+/**
+ * Vérifie un nom de migration, et dit ce qu'il faudrait taper à la place.
+ *
+ * @param input - nom reçu de la ligne de commande, éventuellement absent.
+ * @returns le verdict, avec sa raison et sa suggestion.
+ */
+export declare function checkMigrationName(input: string | undefined): MigrationNameCheck;

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

@@ -0,0 +1,54 @@
+import type { IMigrationSource } from "./types.js";
+/** Nom logique RÉSERVÉ de la source livrée par le framework. */
+export declare const FRAMEWORK_SOURCE = "framework";
+/** Nom logique RÉSERVÉ de la source livrée par l'application. */
+export declare const APP_SOURCE = "app";
+/** Rang de la source framework : première appliquée, toujours. */
+export declare const FRAMEWORK_RANK = 0;
+/**
+ * Rang de la source application : dernière appliquée, toujours.
+ *
+ * Les entités d'une application peuvent référencer les tables du framework et
+ * celles des modules ; l'inverse n'arrive jamais.
+ */
+export declare const APP_RANK = 1000000;
+/**
+ * Dossier des migrations livrées par ce paquet.
+ *
+ * **Trouvé en remontant jusqu'au `package.json` du paquet**, jamais par un
+ * nombre de niveaux codé en dur : la profondeur diffère entre les sources
+ * (`nodefony/src/migrator/`) et le paquet bâti (`dist/nodefony/src/migrator/`),
+ * et un compte figé serait juste d'un côté, faux de l'autre — sans que rien ne
+ * le signale avant l'exécution chez un utilisateur.
+ *
+ * @returns le chemin absolu du dossier `migrations` du paquet.
+ * @throws Error si la racine du paquet est introuvable.
+ */
+export declare function frameworkMigrationsDir(): Promise<string>;
+/**
+ * Registre de sources standard : le framework, puis l'application.
+ *
+ * L'espace de noms reste OUVERT — un module tiers ajoute la sienne au même
+ * registre, avec son propre rang. `framework` et `app` sont deux valeurs
+ * réservées, pas une énumération.
+ *
+ * **Le framework ne fournit ses migrations que s'il déclare ses entités.** Un
+ * module réglé `frameworkEntities: false` est data-only : il n'enregistre ni
+ * entité ni fabrique, et le démarrage en mode dérivé ne crée donc aucune table
+ * de session, de jeton, d'audit ni de webhook. Les inclure ici quand même
+ * faisait fabriquer DEUX bases différentes à la même application selon qu'elle
+ * démarrait en développement ou qu'on la migrait en production — et rien ne le
+ * disait, le verdict de divergence ignorant par construction ce que la base a
+ * en TROP.
+ *
+ * La règle vit ICI, à l'endroit unique où les sources se composent : ses deux
+ * appelants (le service au démarrage, les commandes) la recopieraient sinon, et
+ * deux copies divergent en silence.
+ *
+ * @param appDir - dossier de migrations de l'application, s'il y en a un.
+ * @param options.framework - `false` quand le module est data-only.
+ * @returns le registre, prêt pour l'applicateur.
+ */
+export declare function defaultMigrationSources(appDir?: string, options?: {
+    framework?: boolean;
+}): Promise<IMigrationSource[]>;

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

@@ -0,0 +1,170 @@
+import type { IDrizzleConfig } from "../../interfaces/IDrizzleConfig.js";
+import { MIGRATION_FORMAT_VERSION } from "./explain.js";
+import type { IMigrationAction } from "./types.js";
+import type { MigrationVerdictError } from "./types.js";
+import type { IConnectorResolution } from "./resolve.js";
+/** Codes d'arrêt propres à la ligne de commande (l'applicateur a les siens). */
+export type CommandFailureCode = 
+/** Aucun connecteur de ce nom, nulle part. */
+"NF_MIGRATE_UNKNOWN_CONNECTOR"
+/** Le connecteur existe, mais sa base ne se migre pas par fichiers. */
+ | "NF_MIGRATE_NO_MIGRATIONS" | "NF_MIGRATE_URL_MISMATCH"
+/** Connecteur SQL enregistré, mais absent de la configuration du module. */
+ | "NF_MIGRATE_NOT_CONFIGURED"
+/** Geste réservé au développement, demandé ailleurs. */
+ | "NF_MIGRATE_NOT_DEVELOPMENT"
+/** La commande n'a pas pu joindre la base, ou a échoué à l'exécution. */
+ | "NF_MIGRATE_UNAVAILABLE"
+/** Confirmation requise et non donnée. */
+ | "NF_MIGRATE_CONFIRM_REQUIRED"
+/** Des migrations en attente SUPPRIMENT des données, hors développement. */
+ | "NF_MIGRATE_DESTRUCTIVE"
+/** Adopter TOUT graverait une affirmation fausse : la base ne suit pas. */
+ | "NF_MIGRATE_BASELINE_AMBIGUOUS"
+/** Le nom de la migration manque, ou ne voyage pas sur les trois systèmes. */
+ | "NF_GENERATE_NAME"
+/** Une entité enregistrée qu'aucun fichier découvert ne fournit. */
+ | "NF_GENERATE_MISSING_ENTITY"
+/** Un fichier de l'application fournit une table qui appartient au framework. */
+ | "NF_GENERATE_FRAMEWORK_TABLE"
+/** La migration produite DÉTRUIT des données, et personne ne l'a dit. */
+ | "NF_GENERATE_DESTRUCTIVE"
+/** Rien à écrire, et pourtant la base ne porte pas le schéma déclaré. */
+ | "NF_GENERATE_DATABASE_BEHIND"
+/** L'outil qui ÉCRIT les migrations n'est pas installé. */
+ | "NF_GENERATE_TOOL_MISSING"
+/** Le schéma initial serait écrit sur une base qui porte DÉJÀ ces tables. */
+ | "NF_GENERATE_DATABASE_NOT_ADOPTED"
+/** L'adoption par lecture de la base, demandée alors qu'il existe déjà des migrations. */
+ | "NF_MIGRATE_BASELINE_NOT_EMPTY"
+/** La table d'historique existe, mais ce n'est pas celle du framework. */
+ | "NF_MIGRATE_HISTORY_FOREIGN";
+/**
+ * Ce que la découverte des entités a VU, au moment où la commande a refusé.
+ *
+ * **Pourquoi ce bloc existe.** Une migration se produit à partir des FICHIERS.
+ * Quand l'un d'eux manque à l'appel — illisible, écrit pour un autre moteur, ou
+ * n'exportant rien sous la configuration courante —, la table qu'il fournissait
+ * disparaît du schéma déclaré, et l'outil de diff ne voit pas une découverte
+ * amputée : il voit une table SUPPRIMÉE, et propose de la détruire. Le refus
+ * qui s'ensuit nomme alors la base, qui n'y est pour rien.
+ *
+ * Sans ces faits, la correction naturelle — accepter la destruction, ou repartir
+ * d'une base vide — détruit des données pour un défaut qui est dans le dossier
+ * d'entités. C'est le seul endroit d'où l'on peut le voir.
+ */
+export interface IDiscoveryFacts {
+    /** Fichiers d'entités examinés, toutes cibles confondues. */
+    filesScanned: number;
+    /** Tables de l'APPLICATION retenues pour le dialecte de ce connecteur. */
+    tables: string[];
+    /** Tables écartées : elles sont écrites pour un AUTRE moteur. */
+    otherDialect: {
+        table: string;
+        dialect: string;
+        file: string;
+    }[];
+    /** Fichiers qui n'ont pas pu être importés, avec leur cause. */
+    unreadable: {
+        file: string;
+        cause: string;
+    }[];
+}
+/** Ce qu'une commande écrit quand elle n'a PAS pu rendre un état. */
+export interface ICommandFailure {
+    formatVersion: typeof MIGRATION_FORMAT_VERSION;
+    connector: string;
+    exitCode: 1 | 2;
+    /**
+     * Présent ⇔ la commande n'a pas pu faire son travail. C'est le discriminant :
+     * une sortie qui porte `verdict` est un état lu, une sortie qui porte `error`
+     * est un arrêt. Aucune n'a jamais les deux.
+     */
+    error: {
+        code: CommandFailureCode | MigrationVerdictError["verdict"]["code"];
+        summary: string;
+        meaning: string;
+        nextActions: IMigrationAction[];
+        /**
+         * Ce que la découverte des entités a vu — présent sur les refus dont la
+         * cause PEUT être un schéma déclaré amputé. Optionnel : un refus de
+         * résolution n'a jamais découvert quoi que ce soit.
+         */
+        discovery?: IDiscoveryFacts;
+    };
+}
+/** Ce qu'il y a à dire d'un connecteur sur lequel on ne peut pas travailler. */
+export interface IResolutionRefusal {
+    code: CommandFailureCode;
+    /** Le fait constaté, en une phrase. */
+    summary: string;
+    /** Pourquoi c'est ainsi — la phrase qui évite la mauvaise correction. */
+    meaning: string;
+    /** Ce qu'il faut faire, du plus direct au plus assumé. */
+    nextActions: IMigrationAction[];
+    /**
+     * Code de sortie que ce refus produit sur la ligne de commande.
+     *
+     * Il vit ICI et pas dans l'appelant : un refus de résolution qui vaudrait
+     * `1` d'un côté et `2` de l'autre casserait les contrôles d'intégration
+     * continue qui lisent ce chiffre, sans qu'aucun test ne le voie.
+     */
+    exitCode: 1 | 2;
+}
+/**
+ * L'outil qui ÉCRIT les migrations n'est pas installé.
+ *
+ * Refus À PART, et c'est tout son intérêt : sans lui, cette cause tombait dans
+ * le fourre-tout des commandes de migration, qui habille toute exception non
+ * typée d'un `meaning` écrit pour la base injoignable. La charge utile portait
+ * alors DEUX explications qui se contredisent — le fait disait « l'outil
+ * manque », l'explication disait « vérifie que la base est démarrée » — et ses
+ * deux gestes interrogeaient une base qui n'y était pour rien.
+ *
+ * @returns le refus, avec le geste qui répare.
+ */
+export declare function generationToolMissing(): IResolutionRefusal;
+/**
+ * Erreur portant un {@link IResolutionRefusal} déjà composé.
+ *
+ * Elle existe pour que la CAUSE porte son propre remède jusqu'à la sortie de la
+ * commande : reconnaître une cause au texte de son message serait une garde qui
+ * se casse au premier reformulage.
+ */
+export declare class MigrationToolError extends Error {
+    readonly refusal: IResolutionRefusal;
+    /**
+     * @param refusal - refus complet, seule source de la décision.
+     */
+    constructor(refusal: IResolutionRefusal);
+}
+/**
+ * Le module qui porte les connecteurs n'est pas chargé par l'application.
+ *
+ * @returns le refus, prêt pour la ligne de commande comme pour l'écran.
+ */
+export declare function moduleAbsent(): IResolutionRefusal;
+/**
+ * Le connecteur est une base SQL, mais la configuration du module ne le déclare
+ * pas — cas d'un ORM construit directement dans du code.
+ *
+ * ⚠️ Ne JAMAIS lui répondre « ne porte pas de migrations » : c'est faux d'un
+ * connecteur SQL, et un message faux publié est appris par les scripts qui le
+ * lisent.
+ *
+ * @param connector - nom du connecteur.
+ * @param driver - base sous-jacente, telle que l'ORM la nomme.
+ * @returns le refus, prêt pour la ligne de commande comme pour l'écran.
+ */
+export declare function notConfigured(connector: string, driver: string): IResolutionRefusal;
+/**
+ * Traduit une résolution qui n'est PAS `ready` en refus lisible.
+ *
+ * @param wanted - nom demandé par l'appelant.
+ * @param resolution - ce que la résolution a rendu.
+ * @param config - configuration validée du module (nomme les connecteurs réels).
+ * @returns le refus correspondant, jamais `null` : chaque cas a sa prose.
+ */
+export declare function describeResolutionRefusal(wanted: string, resolution: Exclude<IConnectorResolution, {
+    kind: "ready";
+}>, config: IDrizzleConfig): IResolutionRefusal;