@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,201 @@
+import type { Kernel } from "nodefony";
+import type { DdlMode, DivergenceMode, MigrationCheckMode, SqlDialect } from "../../config/config.js";
+import type { IDrizzleConfig } from "../../interfaces/IDrizzleConfig.js";
+import { DrizzleMigrator } from "./DrizzleMigrator.js";
+import type { IMigrationTarget } from "./drivers/index.js";
+/**
+ * Résolution du décor d'une commande de migration : QUI possède le connecteur,
+ * OÙ se trouve sa base, QUEL mode de schéma s'applique.
+ *
+ * **Pourquoi un fichier à part, et pourquoi il ne fait aucune entrée-sortie** :
+ * ces règles sont lues par cinq commandes, par le démarrage du module et par la
+ * sonde de disponibilité. Une seule d'entre elles recopiée ailleurs
+ * divergerait — et une divergence de mode `ddl` entre le démarrage et la ligne
+ * de commande, c'est une base que l'un croit à jour et que l'autre migre.
+ *
+ * Les fonctions de décision sont **pures** : on leur INJECTE l'environnement
+ * constaté au lieu de le lire ici. C'est ce qui les rend éprouvables sans
+ * kernel, sans base et sans variable d'environnement à poser.
+ */
+import { MIGRATE_URL_ENV } from "./types.js";
+export { MIGRATE_URL_ENV };
+/** L'environnement tel qu'on le CONSTATE — jamais déduit à l'intérieur. */
+export interface IMigrationEnv {
+    /** Mode moteur normalisé du kernel : `development` ou `production`. */
+    runtime: "development" | "production";
+    /** `NODE_ENV` brut — seul porteur de la valeur `test`. */
+    nodeEnv?: string | undefined;
+}
+/**
+ * Constate l'environnement depuis le kernel et le processus.
+ *
+ * @param kernel - kernel courant, ou `null` hors application.
+ * @returns l'environnement constaté, prêt à être injecté aux règles pures.
+ */
+export declare function readMigrationEnv(kernel: Kernel | null): IMigrationEnv;
+/**
+ * L'effacement d'une base est-il ACCEPTÉ dans cet environnement ?
+ *
+ * **Liste blanche, jamais liste noire** : seul `development` passe. Un
+ * `staging`, un `test`, un environnement que personne n'a pensé à nommer sont
+ * refusés — c'est exactement ce qu'une garde écrite « si production » laisserait
+ * passer, et c'est là que l'accident se produit.
+ *
+ * Écrite ici parce qu'elle a DEUX lecteurs qui doivent dire la même chose :
+ * `orm:reset`, qui refuse ; et le rendu des migrations, qui ne doit pas proposer
+ * un geste que l'autre va rejeter. Deux copies de cette règle divergeraient, et
+ * la sortie promettrait alors une commande impossible.
+ *
+ * @param env - environnement constaté.
+ * @returns `true` si `orm:reset` est recevable.
+ */
+export declare function resetAllowed(env: IMigrationEnv): boolean;
+/**
+ * Le mode de schéma qui s'applique à un connecteur.
+ *
+ * Règle des défauts, et son pourquoi : **appliquer des migrations au démarrage
+ * n'est jamais un défaut**. C'est la norme unanime des outils de migration, et
+ * elle tient à un fait simple — au démarrage, plusieurs exemplaires partent en
+ * même temps. `migrate` est donc toujours un choix écrit, jamais une déduction.
+ *
+ * - développement et test → `auto` : le schéma suit le code, sans rien taper ;
+ * - 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.
+ *
+ * @param explicit - valeur écrite dans la configuration du connecteur, si elle l'est.
+ * @param env - environnement constaté.
+ * @returns le mode effectif.
+ */
+export declare function resolveDdlMode(explicit: DdlMode | undefined, env: IMigrationEnv): DdlMode;
+/**
+ * La conduite de la sonde de disponibilité face à un schéma en retard.
+ *
+ * En production, un exemplaire dont le schéma est en retard ne doit pas
+ * recevoir de trafic : il répondrait des erreurs de colonne inconnue à des
+ * utilisateurs réels. Ailleurs, le retenir gênerait plus qu'il n'aiderait — un
+ * avertissement suffit.
+ *
+ * @param explicit - valeur écrite dans `migrations.check`, si elle l'est.
+ * @param env - environnement constaté.
+ * @returns la conduite effective.
+ */
+export declare function resolveCheckMode(explicit: MigrationCheckMode | undefined, env: IMigrationEnv): MigrationCheckMode;
+/** Ce qu'un connecteur est, du point de vue des migrations. */
+export type IConnectorResolution = {
+    /** Le connecteur existe et son propriétaire sait migrer. */
+    kind: "ready";
+    connector: string;
+    dialect: SqlDialect;
+    target: IMigrationTarget;
+    /** `true` quand la cible vient de {@link MIGRATE_URL_ENV}. */
+    fromMigrateUrl: boolean;
+    ddl: DdlMode;
+} | {
+    /**
+     * Le connecteur est enregistré, mais la commande ne peut pas travailler
+     * dessus. Deux causes bien distinctes, et il ne faut JAMAIS les
+     * confondre — `sqlLike` les sépare.
+     */
+    kind: "unsupported";
+    connector: string;
+    /** Ce qui porte ce connecteur, tel que l'ORM se décrit lui-même. */
+    owner: string;
+    /**
+     * Sa base est-elle une base SQL ?
+     *
+     * `true` — c'est un connecteur SQL qui n'est simplement pas déclaré dans
+     * la configuration du module : la commande n'a pas ses coordonnées de
+     * connexion. Lui répondre « ne porte pas de migrations » serait FAUX, et
+     * un message faux publié est appris par les scripts qui le lisent.
+     *
+     * `false` — sa base résorbe l'écart entre le code et le schéma autrement
+     * (index synchronisés plutôt que fichiers versionnés) : il n'y a rien à
+     * migrer ici, aujourd'hui.
+     */
+    sqlLike: boolean;
+    /** Base sous-jacente telle que l'ORM la nomme (`mongodb`, `sqlite`…). */
+    driver: string;
+} | {
+    /**
+     * La variable de migration désigne une AUTRE base que le connecteur.
+     *
+     * Refuser est le seul comportement sûr : on ne peut ni appliquer du SQL
+     * d'un dialecte avec le pilote d'un autre, ni deviner laquelle des deux
+     * bases l'exploitant visait. L'ignorer produisait un faux succès de
+     * déploiement — la pire sortie possible d'une commande de migration.
+     */
+    kind: "url-mismatch";
+    connector: string;
+    /** Dialecte du connecteur déclaré. */
+    dialect: SqlDialect;
+    /** Dialecte que désigne la variable, ou `null` si elle est illisible. */
+    urlDialect: SqlDialect | null;
+} | {
+    /** Aucun connecteur de ce nom, nulle part. */
+    kind: "unknown";
+    connector: string;
+    /** Tous les noms qui existent, tous ORM confondus, triés. */
+    known: string[];
+};
+/**
+ * Tous les noms de connecteurs qui existent, tous ORM confondus.
+ *
+ * L'union du registre et de la configuration : le registre porte ce qui est
+ * connecté, la configuration ce qui est déclaré. Un connecteur déclaré mais non
+ * connecté doit apparaître dans la liste — sinon un utilisateur qui a fait une
+ * faute de frappe se voit répondre que son connecteur n'existe pas ET ne le
+ * voit pas dans la liste, alors qu'il est bien écrit dans son fichier.
+ *
+ * @param config - configuration validée du module drizzle.
+ * @returns les noms, triés, sans doublon.
+ */
+export declare function knownConnectors(config: IDrizzleConfig): string[];
+/**
+ * Résout un nom de connecteur en l'une des **trois** réponses possibles.
+ *
+ * Ces trois réponses sont un contrat, pas un détail d'implémentation : le jour
+ * où un second ORM apporte ses propres migrations, c'est `unsupported` qui doit
+ * cesser de sortir pour ses connecteurs — et rien d'autre ne bouge. Répondre
+ * « ne porte pas de migrations » à un connecteur qui en porterait serait un
+ * message FAUX, appris par les scripts qui le lisent.
+ *
+ * La propriété se **constate** sur la configuration du module, jamais par un
+ * test d'instance : à la frontière npm, deux copies du même paquet font échouer
+ * `instanceof` sans un mot.
+ *
+ * @param connector - nom demandé.
+ * @param config - configuration validée du module drizzle.
+ * @param env - environnement constaté.
+ * @param kernel - kernel courant, indispensable au chemin SQLite par défaut.
+ * @param options - `allowMigrateUrl` autorise {@link MIGRATE_URL_ENV} à primer.
+ * @returns la réponse, discriminée par `kind`.
+ */
+export declare function resolveConnector(connector: string, config: IDrizzleConfig, env: IMigrationEnv, kernel: Kernel | null, options?: {
+    allowMigrateUrl?: boolean;
+}): IConnectorResolution;
+/**
+ * Dossier de migrations de l'application, résolu depuis la racine que le kernel
+ * connaît.
+ *
+ * Jamais depuis le répertoire courant du processus : un espace de travail en a
+ * plusieurs, et la commande serait juste ou fausse selon l'endroit d'où on la
+ * tape — le pire des comportements, parce qu'il marche une fois sur deux.
+ *
+ * @param kernel - kernel courant.
+ * @param dir - valeur de `migrations.dir` (relative, ou absolue si l'app le veut).
+ * @returns le chemin absolu, ou `undefined` sans kernel.
+ */
+export declare function appMigrationsDir(kernel: Kernel | null, dir: string): string | undefined;
+/**
+ * Construit l'applicateur d'un connecteur résolu.
+ *
+ * @param resolution - réponse `ready` de {@link resolveConnector}.
+ * @param config - configuration validée du module drizzle.
+ * @param kernel - kernel courant (racine de l'application).
+ * @returns l'applicateur, sources du framework et de l'application chargées.
+ */
+export declare function buildMigrator(resolution: Extract<IConnectorResolution, {
+    kind: "ready";
+}>, config: IDrizzleConfig, kernel: Kernel | null): Promise<DrizzleMigrator>;
+/** Conduite face à la divergence, telle que la configuration la déclare. */
+export declare function resolveDivergenceMode(config: IDrizzleConfig): DivergenceMode;

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

@@ -0,0 +1,112 @@
+import type { IColumnInfo } from "@nodefony/orm-core";
+import type { SqlDialect } from "../../config/config.js";
+import type { ISchemaReader } from "./catalog.js";
+/**
+ * L'écart entre le schéma DÉCLARÉ dans le code et le schéma RÉELLEMENT en base.
+ *
+ * ## Pourquoi ce calcul existe, et ce qu'il permet que personne d'autre ne fait
+ *
+ * Les outils de migration connaissent **deux** choses : les fichiers et
+ * l'historique. Ils en déduisent « tout est appliqué » et s'arrêtent là. Ils ne
+ * regardent jamais la base elle-même.
+ *
+ * Croiser une **troisième** source rend visible un incident courant et coûteux :
+ * *l'historique est complet, aucune migration n'est en attente — et pourtant la
+ * base ne correspond pas au code*. Quelqu'un a modifié la base à la main, un
+ * correctif d'urgence n'a pas été reporté, deux environnements ont divergé.
+ *
+ * Le même calcul sert deux usages qui n'ont l'air d'avoir aucun rapport :
+ *
+ * - en développement, il **répare tout seul** le cas de loin le plus fréquent —
+ *   le back a ajouté un champ, la table existe déjà, et la colonne manque ;
+ * - en production, il **signale** la divergence, sans jamais rien réparer.
+ *
+ * ## Deux règles non négociables
+ *
+ * **1. Ce qui est EN PLUS est ignoré.** Le diff signale ce qui MANQUE, jamais
+ * ce qu'il trouve en trop. Ce n'est pas de la prudence, c'est une condition
+ * d'existence : toute application qui écrit des migrations libres (une vue, un
+ * déclencheur, une colonne ajoutée à une table d'entité) a une base
+ * légitimement et en permanence différente du schéma déclaré. Signaler le
+ * surplus allumerait le voyant à vie chez ces utilisateurs — donc il serait
+ * appris comme du bruit, donc il serait mort.
+ *
+ * **2. Le rattrapage est STRICTEMENT additif.** Il ajoute une colonne absente,
+ * et seulement si elle accepte le vide. Jamais de suppression, jamais de
+ * changement de type, jamais de passage en obligatoire — et jamais de valeur
+ * inventée pour remplir une colonne obligatoire. Tout le reste est publié comme
+ * un écart, avec le geste, et attend une décision humaine.
+ */
+/** Une colonne attendue par le code et absente de la base. */
+export interface ISchemaGap {
+    /** Table concernée, telle qu'elle s'appelle en base. */
+    table: string;
+    /** Colonne attendue. */
+    column: string;
+    /** Type SQL attendu, dans le dialecte du connecteur. */
+    type: string;
+    /** La colonne accepte-t-elle le vide ? (seules celles-ci se rattrapent) */
+    nullable: boolean;
+}
+/** Ce que la comparaison a trouvé. */
+export interface ISchemaComparison {
+    /**
+     * Colonnes manquantes qui acceptent le vide — rattrapables sans rien
+     * inventer. C'est le cas fréquent : un champ ajouté par le back.
+     */
+    additive: ISchemaGap[];
+    /**
+     * Colonnes manquantes et OBLIGATOIRES — jamais rattrapées : les poser
+     * exigerait d'inventer une valeur pour les lignes existantes, ce qui est une
+     * décision métier, pas une décision d'outil.
+     */
+    blocking: ISchemaGap[];
+    /** Tables entièrement absentes de la base. */
+    missingTables: string[];
+}
+/**
+ * Nomme ce qui manque, en trois mots plutôt qu'en trois lignes.
+ *
+ * Un refus qui dit « la base diverge » sans dire OÙ oblige à rouvrir un client
+ * SQL — c'est-à-dire exactement le geste que ces commandes existent pour éviter.
+ *
+ * Écrite ici parce qu'elle a DEUX lecteurs, et qu'ils doivent nommer l'écart de
+ * la même façon : l'adoption d'une base existante, et le générateur quand il
+ * n'a rien à écrire. Deux formulations pour un même fait apprendraient à leurs
+ * lecteurs qu'il s'agit de deux problèmes.
+ *
+ * @param c - les écarts, tels que la comparaison les rend.
+ * @returns une énumération courte, prête à entrer dans une phrase.
+ */
+export declare function summarizeGap(c: ISchemaComparison): string;
+/** La base s'écarte-t-elle du code ? */
+export declare function hasGap(c: ISchemaComparison): boolean;
+/** Le schéma attendu d'une table, tel que le code le déclare. */
+export interface IExpectedTable {
+    table: string;
+    columns: IColumnInfo[];
+}
+/**
+ * Compare le schéma déclaré au schéma réel, table par table.
+ *
+ * Une requête par table, et **au démarrage uniquement** : rien de ceci n'existe
+ * dans le chemin d'une requête.
+ *
+ * @param reader - lecteur de catalogue du porteur (ORM connecté, ou pilote).
+ * @param expected - schéma attendu (cf `DrizzleOrm.describeTables`).
+ * @returns les écarts, séparés selon qu'ils se rattrapent ou non.
+ */
+export declare function compareSchema(reader: ISchemaReader, expected: readonly IExpectedTable[]): Promise<ISchemaComparison>;
+/**
+ * Le `ALTER TABLE` qui pose une colonne manquante.
+ *
+ * Aucune valeur par défaut n'est émise, et aucune contrainte : la colonne est
+ * ajoutée telle que le code la déclare, nullable. Ajouter un défaut ici
+ * reviendrait à inventer la donnée des lignes existantes.
+ *
+ * @param gap - la colonne manquante (elle DOIT accepter le vide).
+ * @param dialect - dialecte du connecteur.
+ * @returns le SQL, prêt à exécuter.
+ * @throws Error si l'on tente de rattraper une colonne obligatoire.
+ */
+export declare function additiveSql(gap: ISchemaGap, dialect: SqlDialect): string;

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

@@ -0,0 +1,119 @@
+import type { SqlDialect } from "../../config/config.js";
+import { type IMigrationFile, type IMigrationSource } from "./types.js";
+/**
+ * Version du journal drizzle-kit que cet applicateur sait lire.
+ *
+ * On adopte le format d'un outil tiers : le lire « au mieux » reviendrait à
+ * découvrir un défaut de découpe APRÈS publication, quand le corriger
+ * changerait le sens de fichiers déjà livrés chez des utilisateurs.
+ */
+export declare const SUPPORTED_JOURNAL_VERSIONS: readonly string[];
+/**
+ * Résultat du chargement d'un registre de sources.
+ *
+ * Les sources **absentes** ne sont pas une erreur : désinstaller un module ne
+ * doit pas bloquer la migration à jamais. Elles sont nommées ici pour que
+ * l'appelant puisse le DIRE, ce qui n'est pas la même chose que de s'arrêter.
+ */
+export interface ILoadedSources {
+    /** Fichiers de toutes les sources présentes, dans l'ordre d'application. */
+    files: IMigrationFile[];
+    /** Noms des sources déclarées dont le dossier n'existe pas. */
+    absent: string[];
+}
+/**
+ * Ordonne un registre de sources : rang croissant, nom en départage.
+ *
+ * `framework` porte le rang 0 (les entités d'application peuvent référencer ses
+ * tables), `app` le rang le plus élevé. Entre les deux, les modules à leur
+ * ordre de chargement. Le nom départage à rang égal pour que l'ordre soit
+ * **déterministe** : deux pods qui liraient le même registre dans deux ordres
+ * différents appliqueraient deux plans différents.
+ *
+ * @param sources - registre, dans n'importe quel ordre.
+ * @returns le même registre, trié.
+ */
+export declare function orderSources(sources: readonly IMigrationSource[]): IMigrationSource[];
+/**
+ * Charge toutes les sources d'un registre pour un dialecte donné.
+ *
+ * @param sources - registre de sources (espace de noms ouvert).
+ * @param dialect - dialecte du connecteur ; sélectionne le sous-dossier.
+ * @returns les fichiers ordonnés et les sources absentes, nommées.
+ * @throws MigrationVerdictError si un fichier ne porte pas le format attendu.
+ */
+export declare function loadSources(sources: readonly IMigrationSource[], dialect: SqlDialect): Promise<ILoadedSources>;
+/**
+ * Découpe un fichier de migration en statements exécutables.
+ *
+ * ## Le séparateur EST un commentaire SQL — et c'est tout le problème
+ *
+ * `--> statement-breakpoint` commence par deux tirets : pour le moteur, c'est
+ * un commentaire, et rien ne le distingue d'un autre à l'œil nu. Deux ordres
+ * naïfs échouent donc, chacun pour sa raison, et les deux ont été constatés :
+ *
+ * - **découper puis retirer les commentaires** fait d'un séparateur écrit DANS
+ *   un commentaire un vrai séparateur. La ligne est coupée en deux, et le
+ *   fragment de droite — qui ne commence plus par deux tirets — part au pilote
+ *   comme une instruction. Le produit se le faisait à lui-même : le gabarit
+ *   qu'écrit `orm:generate --custom` porte la phrase qui NOMME le séparateur,
+ *   si bien que toute migration libre écrite en suivant son aide échouait sur
+ *   une erreur de syntaxe, en laissant dans l'historique une migration `failed`
+ *   — c'est-à-dire une base bloquée, à réparer à la main ;
+ * - **retirer les commentaires puis découper** emporte les séparateurs
+ *   eux-mêmes, et fond toutes les instructions du fichier en une seule.
+ *
+ * Il n'y a donc pas d'ordre à trouver : les deux décisions se prennent au MÊME
+ * moment, ligne par ligne, en sachant si l'on est dans une chaîne littérale.
+ * Un commentaire ne peut pas ouvrir un commentaire : dès que la ligne commence
+ * par deux tirets sans être le séparateur, tout ce qu'elle porte est du texte.
+ *
+ * Le séparateur n'est pas reconnu « ligne entière » pour autant : drizzle-kit
+ * le colle en fin d'instruction (`CREATE INDEX …;--> statement-breakpoint`), et
+ * l'exiger seul sur sa ligne ferait fusionner toutes les instructions d'une
+ * migration du framework.
+ *
+ * ## La grammaire de chaîne est celle du MOTEUR, pas une moyenne des trois
+ *
+ * Savoir si l'on est dans une chaîne n'a pas la même réponse partout : MySQL
+ * échappe l'apostrophe par une contre-oblique, PostgreSQL délimite les corps
+ * par `$tag$`. Une grammaire fausse ne lève AUCUNE erreur — le scanner croit
+ * sortir d'une chaîne où il est encore, la ligne suivante commençant par deux
+ * tirets est retirée comme un commentaire alors qu'elle est de la DONNÉE, ou
+ * un séparateur porté par un texte coupe l'instruction en deux. La migration
+ * s'inscrit ensuite en succès avec l'empreinte du fichier entier : plus aucun
+ * verdict ne peut le voir. Le dialecte est donc un paramètre REQUIS, jamais un
+ * défaut — le fichier vit déjà sous `<source>/<dialecte>/`, l'appelant l'a.
+ *
+ * @param normalized - contenu normalisé (fins de ligne en LF).
+ * @param dialect - dialecte du connecteur ; choisit la grammaire de chaîne.
+ * @returns les statements non vides, dans l'ordre du fichier.
+ */
+export declare function splitStatements(normalized: string, dialect: SqlDialect): string[];
+/**
+ * Noms des tables qu'un lot de migrations CRÉE.
+ *
+ * Sert la garde d'adoption : un historique vide alors que ces tables existent
+ * déjà signale une base antérieure aux migrations, pas une base neuve. La
+ * liste est DÉRIVÉE des fichiers — une liste codée en dur mentirait dès la
+ * première migration livrée par un module tiers.
+ *
+ * @param files - fichiers de migration chargés.
+ * @returns les noms de tables, sans doublon.
+ */
+export declare function createdTables(files: readonly IMigrationFile[]): string[];
+/**
+ * Tables que le FRAMEWORK construit — dérivées de ses fichiers de migration.
+ *
+ * Dérivées, jamais listées à la main : une liste codée en dur mentirait dès la
+ * première migration livrée par une version suivante.
+ *
+ * Une seule implémentation, parce que deux appelants en dépendent pour la même
+ * décision — le générateur les exclut de ce qu'il écrit, l'adoption les exclut
+ * de ce qu'elle lit. Deux copies divergeraient en silence, chacune verte dans
+ * son propre test.
+ *
+ * @param dialect - dialecte du connecteur visé.
+ * @returns les noms de tables du framework.
+ */
+export declare function frameworkTables(dialect: SqlDialect): Promise<string[]>;

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

@@ -0,0 +1,132 @@
+import type { Kernel } from "nodefony";
+import type { IDrizzleConfig } from "../../interfaces/IDrizzleConfig.js";
+import { MIGRATION_FORMAT_VERSION } from "./explain.js";
+import type { IMigrationReport } from "./explain.js";
+import type { IMigrationPlan } from "./types.js";
+import type { IConnectorResolution } from "./resolve.js";
+import type { ICommandFailure, IResolutionRefusal } from "./refusals.js";
+/**
+ * L'état des migrations d'un connecteur, rendu en VALEUR — un producteur, deux
+ * portes.
+ *
+ * La ligne de commande et le plan d'administration de la console posent la même
+ * question et doivent recevoir le même objet. Le recalculer d'un côté — ne
+ * serait-ce que « à jour ou non » — ferait coexister deux vérités : l'écran
+ * dirait vert pendant que `orm:migrate:status` sortirait en 1, et c'est
+ * précisément le jour d'un déploiement raté qu'on s'en apercevrait.
+ *
+ * Ce module ne rend donc AUCUN verdict propre : il assemble ce que
+ * l'applicateur a calculé, et traduit les refus par la prose unique de
+ * {@link describeResolutionRefusal}.
+ */
+/** Le plan avec son SQL, ou le refus. */
+export type IMigrationPlanResult = {
+    ok: true;
+    plan: IMigrationPlanPayload;
+} | {
+    ok: false;
+    failure: ICommandFailure;
+};
+/** Ce qui s'appliquerait, avec le SQL de chaque migration en attente. */
+export interface IMigrationPlanPayload {
+    formatVersion: typeof MIGRATION_FORMAT_VERSION;
+    connector: string;
+    pending: {
+        source: string;
+        tag: string;
+        statements: string[];
+    }[];
+}
+/** Ce qu'une application a fait, ou le refus. */
+export type IMigrationApplyResult = {
+    ok: true;
+    run: IMigrationRunPayload;
+} | {
+    ok: false;
+    failure: ICommandFailure;
+};
+/** Le compte rendu d'une application. */
+export interface IMigrationRunPayload {
+    formatVersion: typeof MIGRATION_FORMAT_VERSION;
+    connector: string;
+    runId: string;
+    applied: {
+        source: string;
+        tag: string;
+        executionMs: number;
+    }[];
+}
+/** Le rapport, ou le refus — jamais les deux, jamais rien. */
+export type IMigrationStatusResult = {
+    ok: true;
+    report: IMigrationReport;
+} | {
+    ok: false;
+    failure: ICommandFailure;
+};
+/**
+ * Habille un refus en charge utile publiée — la MÊME que celle de `--json`.
+ *
+ * @param connector - connecteur demandé.
+ * @param refusal - ce qu'il y a à en dire.
+ * @returns la charge utile d'arrêt.
+ */
+export declare function failureFrom(connector: string, refusal: IResolutionRefusal): ICommandFailure;
+/**
+ * Compose la charge utile d'un état — le SEUL endroit où le contexte du rendu
+ * est assemblé.
+ *
+ * Les quatre commandes de migration ET le plan d'administration publient le
+ * même objet ; recopier son assemblage les faisait déjà diverger d'un champ à
+ * l'autre, et le prochain consommateur à naître aurait oublié celui du jour.
+ * La troisième source ne se paie qu'ici, une fois : `describeDivergence`
+ * s'abstient toute seule quand le verdict est déjà décidé.
+ *
+ * @param plan - plan calculé par l'applicateur, en lecture seule.
+ * @param resolution - connecteur prêt (porte le mode de schéma effectif).
+ * @param config - configuration validée du module.
+ * @param kernel - kernel courant, pour constater l'environnement.
+ * @returns la charge utile, prête pour `--json` comme pour l'écran.
+ */
+export declare function composeReport(plan: IMigrationPlan, resolution: Extract<IConnectorResolution, {
+    kind: "ready";
+}>, config: IDrizzleConfig, kernel: Kernel | null): Promise<IMigrationReport>;
+/**
+ * Lit l'état des migrations d'un connecteur, sans rien appliquer.
+ *
+ * @param wanted - connecteur demandé (`default` quand rien n'est précisé).
+ * @param config - configuration validée du module, `null` s'il n'est pas chargé.
+ * @param kernel - kernel courant.
+ * @returns l'état, ou le refus qui explique pourquoi il n'y en a pas.
+ */
+export declare function migrationStatusFor(wanted: string, config: IDrizzleConfig | null, kernel: Kernel | null): Promise<IMigrationStatusResult>;
+/**
+ * Ce qui S'APPLIQUERAIT, avec son SQL — lecture seule.
+ *
+ * Sert la confirmation d'un geste d'application : une modification de schéma
+ * ne se confirme pas sur une promesse, elle se confirme sur les instructions
+ * qui vont être exécutées.
+ *
+ * @param wanted - connecteur demandé.
+ * @param config - configuration validée du module, `null` s'il n'est pas chargé.
+ * @param kernel - kernel courant.
+ * @returns le plan, ou le refus.
+ */
+export declare function migrationPlanFor(wanted: string, config: IDrizzleConfig | null, kernel: Kernel | null): Promise<IMigrationPlanResult>;
+/**
+ * Applique les migrations en attente — **DÉVELOPPEMENT seulement**.
+ *
+ * 🔴 Le refus hors développement n'est pas une précaution d'interface, c'est la
+ * doctrine : en production, les migrations s'appliquent dans un travail
+ * d'orchestrateur qui se termine AVANT que le premier nouvel exemplaire ne
+ * démarre. Les appliquer au clic de quelqu'un qui regarde une console pendant
+ * que le trafic passe, c'est modifier un schéma sous les pieds des exemplaires
+ * en service. La garde vit ICI, dans le produit — jamais dans l'écran, qui ne
+ * protège que celui qui le regarde.
+ *
+ * @param wanted - connecteur demandé.
+ * @param config - configuration validée du module, `null` s'il n'est pas chargé.
+ * @param kernel - kernel courant.
+ * @returns ce qui a été appliqué, ou le refus.
+ */
+export declare function applyMigrationsFor(wanted: string, config: IDrizzleConfig | null, kernel: Kernel | null): Promise<IMigrationApplyResult>;