@nodefony/drizzle 10.0.0-alpha.1

package/dist/types/nodefony/src/DrizzleWebhookStore.d.ts

@@ -0,0 +1,79 @@
+import type { IRepository } from "@nodefony/orm-core";
+import type { IPage } from "nodefony";
+import type { IWebhookEndpoint, IWebhookListQuery, IWebhookStore, WebhookEndpointUpdate } from "@nodefony/security";
+import type { SqlDialect } from "../interfaces/IDrizzleConfig.js";
+import type { DrizzleOrm } from "./orm-core/DrizzleOrm.js";
+import type { DrizzleDb } from "./orm-core/DrizzleRepository.js";
+import { type WebhookEndpointRow } from "../entity/webhookEndpointEntity.js";
+/**
+ * Store d'endpoints webhook **Drizzle** (driver `better-sqlite3`) —
+ * implémentation SQL d'{@link IWebhookStore} au-dessus d'un unique repository
+ * `@nodefony/orm-core` (`webhook_endpoint`). Persistance DURABLE du registre
+ * (les endpoints survivent au redémarrage, contrairement à `MemoryWebhookStore`).
+ *
+ * **Approche B** : l'ORM ne connaît `@nodefony/security` qu'en `import type` → 0
+ * dépendance runtime. C'est l'application qui enregistre la fabrique
+ * (`registerWebhookStore("drizzle", …)`) et l'entité
+ * (`registerWebhookEndpointEntity(orm)` avant `orm.connect()`).
+ *
+ * **Portable sauf le listing paginé** : le CRUD passe par le contrat
+ * `IRepository` (transposable tel quel aux autres drivers) ; seuls `listPage` /
+ * `countEndpoints` descendent au SQL natif via le `queryKit`, parce que le
+ * filtre `event` cherche dans un tableau JSON — inexprimable en `Criteria`.
+ *
+ * **Mapping Row ↔ contrat** minimal : `IWebhookEndpoint` est déjà « plat tout
+ * `| null` » ; seuls les champs JSON `events` (`readonly` → mutable) et
+ * `metadata` sont copiés défensivement.
+ */
+export declare class DrizzleWebhookStore implements IWebhookStore {
+    #private;
+    /**
+     * {@inheritDoc IWebhookStore.sortableFields}
+     *
+     * Le moteur SQL trie sur n'importe laquelle de ces colonnes. Cette liste sert
+     * DEUX fois : elle annonce la capacité au data plane, et elle borne le
+     * `ORDER BY` construit par le queryKit (identifiant concaténé, non liable).
+     */
+    readonly sortableFields: readonly ["createdAt", "updatedAt", "url", "enabled", "failureCount", "id"];
+    /**
+     * @param repo - repository de la table `webhook_endpoint`.
+     * @param location - emplacement physique de la base (fichier SQLite) pour Studio
+     *   ({@link DrizzleOrm.location}) ; `undefined` pour un backend réseau/`:memory:`.
+     * @param db - handle Drizzle natif, requis par le seul listing paginé (filtre
+     *   `event` = containment dans un tableau JSON, hors `Criteria` portable).
+     *   `null` = store construit sans handle : `listPage` refuse plutôt que de
+     *   charger toute la table en silence.
+     * @param dialect - dialecte SQL du connecteur (route les requêtes du queryKit).
+     */
+    constructor(repo: IRepository<WebhookEndpointRow>, location?: string, db?: DrizzleDb | null, dialect?: SqlDialect);
+    /**
+     * Emplacement physique de la base (fichier SQLite) pour l'écran Studio « Stores »
+     * — lu par `readStoreLocation`. `undefined` = backend réseau ou `:memory:`.
+     */
+    get location(): string | undefined;
+    /**
+     * Construit le store depuis un {@link DrizzleOrm} connecté. L'entité
+     * (`registerWebhookEndpointEntity`) doit avoir été enregistrée **avant**
+     * `orm.connect()`.
+     *
+     * @param orm - ORM Drizzle connecté hébergeant la table du store.
+     */
+    static from(orm: DrizzleOrm): DrizzleWebhookStore;
+    save(endpoint: IWebhookEndpoint): Promise<void>;
+    findById(id: string): Promise<IWebhookEndpoint | null>;
+    update(id: string, patch: WebhookEndpointUpdate): Promise<void>;
+    delete(id: string): Promise<void>;
+    listAll(): Promise<IWebhookEndpoint[]>;
+    /**
+     * {@inheritDoc IWebhookStore.listPage}
+     *
+     * Chemin NATIF (queryKit) : le filtre `event` cherche dans un tableau JSON —
+     * `json_each` (sqlite) / `@>` jsonb (postgres) / `JSON_CONTAINS` (mysql), non
+     * exprimable en `Criteria` portable. On sélectionne les `id` de la page (SQL
+     * pur, aucune ligne matérialisée), puis on recharge la page typée en 1
+     * requête `IN (...)` — coût O(page), jamais O(table).
+     */
+    listPage(query: IWebhookListQuery): Promise<IPage<IWebhookEndpoint>>;
+    /** {@inheritDoc IWebhookStore.countEndpoints} */
+    countEndpoints(query: IWebhookListQuery): Promise<number>;
+}

package/dist/types/nodefony/src/SessionStorage.d.ts

@@ -0,0 +1,72 @@
+import { SessionsService } from "@nodefony/http";
+import type { ISessionStorage, ISerializedSession, ISessionRecord, ISessionListFilter, ISessionListQuery } from "@nodefony/http";
+import type { IPage } from "nodefony";
+/**
+ * Stockage de session **Drizzle** (driver `better-sqlite3`), branché sur
+ * `@nodefony/orm-core`.
+ *
+ * Implémente le contrat {@link ISessionStorage} consommé par le `SessionsService`
+ * de `@nodefony/http` — store de session portable. Persiste via
+ * le repository orm-core de l'entité `session` (connecteur `default`, table créée
+ * au boot par `DrizzleOrm`). Le GC supprime les sessions expirées avec un
+ * opérateur riche portable (`updatedAt < cutoff`).
+ */
+declare class SessionStorage implements ISessionStorage {
+    #private;
+    manager: SessionsService;
+    idleTimeoutS: number;
+    absoluteTimeoutS: number;
+    /**
+     * Même vocabulaire public que les autres backends — le tri part dans le
+     * `ORDER BY`, donc il ne coûte rien de plus qu'un index bien posé.
+     */
+    readonly sortableFields: readonly ["updatedAt", "createdAt", "user", "id"];
+    constructor(manager: SessionsService);
+    /**
+     * Emplacement physique de la base (fichier SQLite) pour l'écran Studio « Stores »
+     * — lu par `readStoreLocation` du core au boot de `SessionsService`. Résolu
+     * **lazy** depuis l'ORM du connecteur session (comme {@link SessionStorage.#repo}) :
+     * `undefined` si l'ORM n'est pas encore enregistré, en `:memory:`, ou réseau
+     * (postgres/mysql → l'emplacement EST l'infra déclarée, surfacée à part). Lecture
+     * DÉFENSIVE (getter `location` optionnel) — l'ORM base `IOrm` ne l'expose pas.
+     */
+    get location(): string | undefined;
+    read(id: string): Promise<ISerializedSession>;
+    start(id: string): Promise<ISerializedSession>;
+    write(id: string, data: ISerializedSession): Promise<ISerializedSession>;
+    open(): Promise<number>;
+    close(): boolean;
+    destroy(id: string): Promise<boolean>;
+    gc(idleSeconds?: number, absoluteSeconds?: number): Promise<void>;
+    /**
+     * Prolonge l'idle d'une session (timeout glissant) : `UPDATE updatedAt = now`
+     * sur la PK `session_id` — SANS réécrire le blob (touch NIST/OWASP). N'affecte
+     * pas `createdAt` (= borne absolute). ORM déconnecté → no-op ; une ligne absente
+     * (session expirée) → 0 row affectée, silencieux.
+     */
+    touch(id: string): Promise<void>;
+    /**
+     * Énumération admin (capacité optionnelle d'`ISessionStorage`) : un `SELECT`
+     * filtrable par `user` (WHERE indexable côté SQL). **Redaction par construction**
+     * — seuls `user`/`metaBag`/timestamps sortent de la base ; `Attributes`/`flashBag`
+     * (potentiellement sensibles) restent en base. ORM déconnecté → `[]`.
+     */
+    listAll(filter?: ISessionListFilter): Promise<ISessionRecord[]>;
+    /**
+     * Pagination **native** `LIMIT/OFFSET` + `COUNT` (helper `paginate` orm-core) :
+     * une page = une requête bornée, quel que soit le nombre de sessions en base.
+     * Ordre `updatedAt` DESC départagé par `session_id` — déterministe même quand
+     * deux sessions partagent la milliseconde. ORM déconnecté → page vide.
+     */
+    listPage(query: ISessionListQuery): Promise<IPage<ISessionRecord>>;
+    /** `COUNT(*)` natif filtré — aucune ligne matérialisée. ORM déconnecté → 0. */
+    countSessions(query?: Partial<ISessionListQuery>): Promise<number>;
+    /**
+     * `COUNT(DISTINCT user)` natif filtré. `write` normalise l'anonyme en `NULL`,
+     * et `COUNT(DISTINCT …)` ignore les `NULL` : les sessions anonymes ne forment
+     * donc pas un « utilisateur » de plus, sans filtre supplémentaire.
+     * ORM déconnecté → 0 (même dégradation que {@link countSessions}).
+     */
+    countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number>;
+}
+export default SessionStorage;

package/dist/types/nodefony/src/connectorTarget.d.ts

@@ -0,0 +1,48 @@
+import type { Kernel } from "nodefony";
+import type { SqlDialect } from "../config/config.js";
+import type { IDrizzleConnectorConfig } from "../interfaces/IDrizzleConfig.js";
+/**
+ * OÙ vit la base d'un connecteur — **une seule implémentation, deux lecteurs**.
+ *
+ * Le service qui connecte l'application au démarrage et les commandes de
+ * migration doivent désigner exactement la même base. Ce n'est pas une
+ * commodité : quand les deux divergent, rien ne le signale. La commande décrit
+ * alors une base que l'application n'utilise pas, annonce « à jour » ou
+ * « appliqué », et rend le code de sortie du succès.
+ *
+ * C'est arrivé, et voici comment : `filename` est **optionnel sans défaut**
+ * dans le schéma de configuration, parce que sa valeur dépend du kernel
+ * (`<app>/var/databases/…`) et que le schéma reste pur. Une lecture naïve de la
+ * configuration rend donc `undefined` — et le pilote SQLite retombe alors sur
+ * une base **en mémoire**, vide, jetée à la fin du processus. Toutes les
+ * migrations s'y « appliquent » parfaitement.
+ *
+ * La règle vit donc ici, et les deux appelants l'appellent.
+ */
+/**
+ * Chemin SQLite par défaut d'un connecteur, résolu depuis le kernel.
+ *
+ * Sous `kernel.varDir` (`<app>/var`) — la base commune des données persistées :
+ * un seul répertoire à sauvegarder et à ignorer du dépôt, et « où sont mes
+ * données » a une réponse unique.
+ *
+ * @param kernel - kernel courant (`null` accepté : repli sur le répertoire courant).
+ * @param name - nom du connecteur.
+ * @returns le chemin absolu du fichier de base.
+ */
+export declare function defaultConnectorFilename(kernel: Kernel | null, name: string): string;
+/** Coordonnées complètes d'un connecteur, prêtes à ouvrir une connexion. */
+export interface IConnectorTarget {
+    dialect: SqlDialect;
+    filename?: string;
+    url?: string;
+}
+/**
+ * Résout les coordonnées d'un connecteur : dialecte, et fichier ou URL.
+ *
+ * @param kernel - kernel courant, pour le chemin par défaut.
+ * @param name - nom du connecteur.
+ * @param cfg - configuration déclarée du connecteur.
+ * @returns les coordonnées, avec le fichier SQLite TOUJOURS résolu.
+ */
+export declare function resolveConnectorTarget(kernel: Kernel | null, name: string, cfg: IDrizzleConnectorConfig): IConnectorTarget;

package/dist/types/nodefony/src/likeSql.d.ts

@@ -0,0 +1,29 @@
+import type { SQL } from "drizzle-orm";
+import type { SqlDialect } from "../interfaces/IDrizzleConfig.js";
+/**
+ * Compose une condition `LIKE` **avec sa clause `ESCAPE`** — le seul endroit de
+ * l'adapter Drizzle qui écrive un `LIKE`.
+ *
+ * La clause n'est pas un raffinement : sans elle, le contrat `$like` n'a pas une
+ * sémantique mais trois. PostgreSQL et MySQL appliquent déjà l'antislash comme
+ * échappement par défaut, SQLite n'en a aucun et cherche l'antislash littéral —
+ * si bien qu'un motif échappé rendait la bonne ligne en production et rien du
+ * tout en développement (mesuré sur les trois moteurs). L'émettre aligne les
+ * trois sur le comportement déjà majoritaire, et rend enfin exprimable un `%`
+ * littéral.
+ *
+ * Le motif est **bindé** (paramètre), jamais concaténé : seul le littéral
+ * d'échappement est brut, et il ne dépend que du dialecte.
+ *
+ * @param dialect - dialecte du connecteur branché.
+ * @param expr - l'expression de gauche, déjà composée (colonne, `LOWER(col)`…).
+ * @param pattern - le motif, dont les fragments littéraux ont été neutralisés
+ *   par `escapeLikeTerm` (`@nodefony/orm-core`).
+ * @returns la condition complète.
+ *
+ * @example
+ * ```ts
+ * likeCond(dialect, sql`LOWER(${col})`, `${escapeLikeTerm(q.toLowerCase())}%`)
+ * ```
+ */
+export declare function likeCond(dialect: SqlDialect, expr: SQL, pattern: string): SQL;

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

@@ -0,0 +1,94 @@
+import type { SqlDialect } from "../../config/config.js";
+import { type IMigrationTarget } from "./drivers/index.js";
+import { type IMigrationApplied, type IMigrationPlan, type IMigrationRun, type IMigrationSource } from "./types.js";
+/** Délai d'attente du verrou, par défaut. */
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 30000;
+/** Options de construction de l'applicateur. */
+export interface IDrizzleMigratorOptions extends IMigrationTarget {
+    /** Nom du connecteur — apparaît dans chaque verdict. */
+    connector: string;
+    /** Registre de sources, espace de noms OUVERT. */
+    sources: readonly IMigrationSource[];
+    /** Délai d'attente du verrou (ms). */
+    lockTimeoutMs?: number;
+    /** Qui applique — hôte du job par défaut. */
+    appliedBy?: string;
+    /** Horloge, injectable pour les tests. */
+    now?: () => number;
+}
+/** Assouplissements explicites d'une passe d'application. */
+export interface IMigrateOptions {
+    /** Accepte qu'une migration appliquée n'ait plus de fichier. */
+    ignoreMissing?: boolean;
+    /** Accepte d'appliquer une migration antérieure à la dernière appliquée. */
+    outOfOrder?: boolean;
+    /** N'applique rien : rend le plan tel qu'il serait exécuté. */
+    dryRun?: boolean;
+}
+export declare class DrizzleMigrator {
+    #private;
+    /**
+     * @param options - connecteur, cible de connexion et registre de sources.
+     */
+    constructor(options: IDrizzleMigratorOptions);
+    /** Connecteur servi par cet applicateur. */
+    get connector(): string;
+    /** Dialecte servi par cet applicateur. */
+    get dialect(): SqlDialect;
+    /**
+     * É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.
+     */
+    status(): Promise<IMigrationPlan>;
+    /**
+     * 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.
+     */
+    migrate(options?: IMigrateOptions): Promise<IMigrationRun>;
+    baseline(upTo?: string): Promise<IMigrationApplied[]>;
+    /**
+     * 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é.
+     */
+    repair(options?: {
+        source?: string;
+        updateHashes?: boolean;
+        forget?: readonly {
+            source: string;
+            tag: string;
+        }[];
+    }): Promise<{
+        cleared: {
+            source: string;
+            tag: string;
+        }[];
+        rehashed: {
+            source: string;
+            tag: string;
+        }[];
+        forgotten: {
+            source: string;
+            tag: string;
+        }[];
+    }>;
+}

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

@@ -0,0 +1,280 @@
+import type { SqlDialect } from "../../config/config.js";
+import { type IMigrationTarget } from "./drivers/index.js";
+import type { ISchemaReader } from "./catalog.js";
+/**
+ * L'adoption d'une base qui EXISTAIT avant les migrations.
+ *
+ * ## Le trou que cette brique ferme
+ *
+ * Le générateur compare le code au **journal des fichiers**, jamais à la base.
+ * Quand ce journal est vide — une application passée du mode dérivé, où le
+ * démarrage fabrique le schéma, au mode de production, où il ne le fabrique
+ * plus — il croit partir de rien et émet le schéma INITIAL : un `CREATE TABLE`
+ * de tables qui existent déjà, avec leurs données. Le fichier est inapplicable,
+ * et il empoisonne la suite : l'adoption l'inscrit comme appliqué, l'historique
+ * affirme alors un schéma que la base n'a pas, et plus aucune commande n'offre
+ * de geste. Mesuré au banc de découvrabilité : le seul chemin restant était de
+ * détruire la base.
+ *
+ * La cause n'est pas le générateur — il fait ce qu'on lui donne à lire. C'est
+ * l'**instantané** de référence qui manque. Le fabriquer depuis la base, et non
+ * depuis le code, remet les trois sources d'accord : les fichiers décrivent
+ * l'état réel, l'historique le déclare appliqué, et la génération suivante
+ * produit l'`ALTER` qu'on attendait.
+ *
+ * ## Pourquoi la migration de référence est DÉCOMMENTÉE
+ *
+ * L'outil d'introspection rend son `CREATE TABLE` entre `/* … *\/`, avec une
+ * ligne qui invite à le décommenter avant de l'exécuter. Le laisser commenté
+ * donnerait une baseline qui ne recrée RIEN : l'historique serait complet et
+ * une base neuve, montée depuis ces mêmes fichiers, sortirait vide. Une
+ * migration doit rester rejouable depuis zéro — c'est ce qui permet de créer un
+ * environnement de plus. Sur la base adoptée, elle n'est jamais exécutée :
+ * l'adoption l'inscrit comme appliquée sans lancer une instruction.
+ */
+/** Ce que l'introspection a produit, une fois remise en forme. */
+export interface IAdoptedBaseline {
+    /** Tag final de la migration de référence, `0000_<nom>`. */
+    tag: string;
+    /** Chemin absolu du fichier SQL. */
+    file: string;
+    /**
+     * Tables entrées dans la référence sans être déclarées par l'application.
+     *
+     * L'outil ne sait pas restreindre sa lecture à une liste de tables — il
+     * n'accepte qu'une exclusion. Ce que la base porte en plus est donc LU, et
+     * doit être NOMMÉ : à la génération suivante, une table de la référence
+     * qu'aucune entité ne déclare est une table que le diff propose de
+     * SUPPRIMER.
+     */
+    extraTables: string[];
+    /**
+     * Le corps a-t-il pu être DÉCOMMENTÉ ?
+     *
+     * Publié plutôt que supposé : si l'outil change sa mise en forme, une
+     * baseline muette passerait pour une baseline rejouable, et le défaut ne se
+     * verrait que le jour où quelqu'un monte un environnement neuf.
+     */
+    runnable: boolean;
+}
+/**
+ * Les coordonnées de connexion, dans la forme que l'outil d'introspection lit.
+ *
+ * SQLite désigne un FICHIER, les autres une URL — et c'est le seul endroit où
+ * cette distinction se fait, pour qu'elle ne se redécide pas à chaque appelant.
+ *
+ * @param target - cible résolue du connecteur.
+ * @returns l'URL de connexion, ou `null` si la cible n'en porte aucune.
+ */
+export declare function introspectionUrl(target: IMigrationTarget): string | null;
+/**
+ * Rend exécutable le corps qu'une introspection a mis en commentaire.
+ *
+ * Fonction PURE — c'est ce qui la rend éprouvable sans base et sans outil
+ * tiers : une règle qui exige un sous-processus pour être vue rouge n'est
+ * jamais vue rouge.
+ *
+ * Ne touche à RIEN si la forme attendue n'est pas là : rendre `null` laisse
+ * l'appelant dire ce qu'il a constaté, au lieu de publier un fichier tronqué
+ * par une expression écrite pour une autre version de l'outil.
+ *
+ * @param sql - le fichier tel que l'outil l'a écrit.
+ * @returns le SQL exécutable, ou `null` si aucun bloc commenté n'a été trouvé.
+ */
+export declare function uncommentIntrospection(sql: string): string | null;
+/** Une entrée du journal des fichiers, telle que l'outil l'écrit. */
+interface IJournalEntry {
+    idx: number;
+    version: string;
+    when: number;
+    tag: string;
+    breakpoints: boolean;
+}
+/** Le journal des fichiers d'un dossier de migrations. */
+interface IJournal {
+    version: string;
+    dialect: string;
+    entries: IJournalEntry[];
+}
+/**
+ * Lit le journal des FICHIERS d'un dossier de migrations.
+ *
+ * ⚠️ Ce journal n'est pas l'historique. Il vit dans le dépôt, il est versionné,
+ * et il dit ce que le code CONNAÎT. L'historique, lui, vit dans la base et dit
+ * ce qu'ELLE a reçu. Les confondre fait conclure « tout est appliqué » sur une
+ * base qui n'a rien vu.
+ *
+ * @param outDir - dossier `<migrations>/<dialecte>`.
+ * @returns le journal, ou `null` s'il n'y en a pas encore.
+ */
+export declare function readJournal(outDir: string): Promise<IJournal | null>;
+/**
+ * Donne à la migration de référence le nom que l'utilisateur a choisi.
+ *
+ * L'outil d'introspection tire un nom au hasard (`0000_futuristic_spectrum`) et
+ * n'accepte pas qu'on le lui impose. Or ce tag est une IDENTITÉ : il est
+ * enregistré dans chaque base qui reçoit la migration, et il ne se renomme plus
+ * ensuite. Le fixer ici, une fois, avant que quiconque l'ait vu.
+ *
+ * @param outDir - dossier `<migrations>/<dialecte>`.
+ * @param oldTag - tag tiré par l'outil.
+ * @param newTag - tag voulu.
+ * @returns le chemin du fichier SQL, sous son nom final.
+ */
+export declare function renameTag(outDir: string, oldTag: string, newTag: string): Promise<string>;
+/**
+ * Retire les modules que l'introspection dépose à côté de sa migration.
+ *
+ * `schema.ts` et `relations.ts` décrivent la base en TypeScript — utile à qui
+ * repart de zéro, hors sujet ici : les entités de l'application sont déjà la
+ * source du schéma. Les laisser dans le dossier des migrations y mettrait deux
+ * descriptions du même schéma, dont une que personne ne met à jour.
+ *
+ * @param outDir - dossier `<migrations>/<dialecte>`.
+ */
+export declare function dropIntrospectionModules(outDir: string): Promise<void>;
+/**
+ * Les tables que l'instantané fraîchement écrit décrit.
+ *
+ * Lues sur l'instantané et non sur le SQL : c'est lui qui sert de référence au
+ * prochain diff, donc c'est lui qui dit ce qui a réellement été adopté. Le
+ * fichier `.sql`, lui, n'est qu'un rendu.
+ *
+ * @param outDir - dossier `<migrations>/<dialecte>`.
+ * @returns les noms de tables, ou `[]` si l'instantané est illisible.
+ */
+export declare function snapshotTables(outDir: string): Promise<string[]>;
+/**
+ * Rend utilisable une référence que l'introspection vient d'écrire.
+ *
+ * L'outil rend ce qu'il a LU, fidèlement. Deux fidélités rendent pourtant le
+ * fichier inutilisable, et il faut les défaire — c'est la même famille de
+ * geste que le décommentage du corps : l'artefact est exact, personne ne peut
+ * s'en servir.
+ *
+ * ## 1. Les objets d'une table EXCLUE
+ *
+ * L'exclusion porte sur les tables, jamais sur ce qui gravite autour. La table
+ * d'historique est écartée — c'est le framework qui la crée —, mais sa
+ * SÉQUENCE, elle, entre dans la référence. Deux conséquences, toutes deux
+ * constatées sur un serveur : la référence rejouée sur un environnement neuf
+ * échoue (la séquence existe déjà, posée par les migrations du framework), et
+ * la génération suivante propose de la SUPPRIMER — ce que la base refuse,
+ * puisque la table d'historique en dépend. L'adoption se retrouve alors dans
+ * l'état qu'elle existe pour éviter : un historique en place, et plus aucune
+ * commande qui passe.
+ *
+ * ## 2. La qualification de schéma
+ *
+ * Une application peut vivre dans un schéma autre que `public` — le montage
+ * habituel d'une base mutualisée, obtenu par le chemin de recherche de la
+ * connexion. Les entités, elles, ne portent aucun schéma : `pgTable("article")`
+ * désigne `public.article` pour l'outil de comparaison, quand l'introspection
+ * rend `nf_app.article`. Au premier champ ajouté, l'outil voit une table qui
+ * disparaît et une autre qui apparaît, et demande s'il s'agit d'un RENOMMAGE :
+ * sans terminal la commande s'arrête, avec un terminal répondre « oui » écrit
+ * un `ALTER TABLE … RENAME` qui déplacerait les données.
+ *
+ * On retire donc la qualification, ce qui rétablit la symétrie avec les
+ * entités. À l'exécution, le chemin de recherche de la connexion place les
+ * tables là où elles doivent être : c'est déjà lui qui décide, l'adoption
+ * cesse simplement de le contredire.
+ *
+ * ## 3. Le booléen de MySQL
+ *
+ * `BOOLEAN` est un SYNONYME de `TINYINT(1)` en MySQL : le serveur ne garde que
+ * la forme physique, et l'introspection ne peut donc rendre que `tinyint(1)`.
+ * L'outil de comparaison, lui, compare des noms de type : il voit une
+ * différence là où la base n'en a aucune, et propose un `MODIFY COLUMN` sur
+ * chaque booléen — refusé ensuite comme destructif. Une application MySQL qui
+ * adopte sa base se retrouve donc bloquée au premier champ ajouté, pour une
+ * table qu'elle n'a jamais touchée.
+ *
+ * La forme déclarée est rétablie. Elle ne peut écraser aucune intention : dans
+ * une entité, `tinyint()` rend `tinyint` sans largeur — vérifié au source
+ * (`drizzle-orm/mysql-core/columns/tinyint.js`) —, et seul `boolean()` produit
+ * `tinyint(1)`. Sur un DDL écrit à la main hors de l'ORM, la réécriture reste
+ * exacte : les deux formes désignent la même colonne.
+ *
+ * @param outDir - dossier `<migrations>/<dialecte>`.
+ * @param options.dialect - dialecte lu ; seul MySQL a le synonyme booléen.
+ * @param file - fichier SQL de la référence.
+ * @param options.schema - schéma effectivement lu, ou `null` (hors PostgreSQL,
+ *   ou lecture dans `public` : il n'y a alors rien à déqualifier).
+ * @param options.excludedTables - tables écartées de la lecture, dont les
+ *   objets satellites doivent l'être aussi.
+ * @param options.stripTables - tables que l'outil a LUES faute de pouvoir les
+ *   exclure, et qu'il faut retirer du résultat (cf `lectureSansExclusion`).
+ */
+export declare function normalizeIntrospection(outDir: string, file: string, options: {
+    schema: string | null;
+    excludedTables: readonly string[];
+    stripTables?: readonly string[];
+    dialect?: SqlDialect;
+}): Promise<void>;
+/**
+ * Parmi les tables qu'on s'apprête à CRÉER, celles que la base porte déjà.
+ *
+ * 🔴 **La base est la seule source, et elle est INTERROGÉE.** Il serait tentant
+ * de déduire la présence d'une table de son absence dans une comparaison au
+ * code : c'est ce que faisait la première version, et le raccourci a produit un
+ * refus mensonger. La comparaison ne connaît que le REGISTRE — les entités
+ * qu'une application enregistre à son démarrage — alors que la génération part
+ * des FICHIERS, qui en contiennent d'autres : celles d'un module désactivé,
+ * d'un connecteur différent, ou d'un module pas encore câblé. Une table hors
+ * registre n'est ni manquante ni présente : elle est INCONNUE, et déduire sa
+ * présence faisait refuser la première migration d'une application en nommant
+ * sept tables qui n'existaient nulle part — puis renvoyait vers une adoption
+ * qui échouait pour la raison inverse. Deux commandes qui se prescrivent l'une
+ * l'autre en se refusant : une impasse, exactement celle que ce chantier
+ * existe pour fermer.
+ *
+ * Le lecteur est INJECTÉ plutôt que construit ici : c'est ce qui rend la règle
+ * éprouvable sans kernel ni serveur, et une règle qu'on ne peut pas voir rouge
+ * n'est pas une règle.
+ *
+ * Le coût est d'une requête de catalogue par table, et l'appelant ne s'en sert
+ * que lorsque le journal est vide — une fois dans la vie d'une application.
+ *
+ * @param reader - lecteur de catalogue ouvert sur la base visée.
+ * @param tables - tables que la migration créerait.
+ * @returns les tables déjà en base, dans l'ordre reçu.
+ */
+export declare function tablesPresentIn(reader: ISchemaReader, tables: readonly string[]): Promise<string[]>;
+/**
+ * Fabrique la migration de RÉFÉRENCE d'une base déjà en place.
+ *
+ * Orchestration complète du côté fichiers — la connexion est lue, rien n'est
+ * écrit dans la base : c'est l'appelant qui décide ensuite d'inscrire cette
+ * migration dans l'historique.
+ *
+ * Le dossier de travail ne survit à rien, ni au succès ni à l'échec : un module
+ * temporaire laissé derrière serait relu par le prochain outil qui balaie les
+ * sources, et personne ne saurait d'où il sort.
+ *
+ * @param options - racine du projet, dossier de sortie, cible, tables exclues,
+ *   tables déclarées, nom voulu pour la migration, dossier de travail.
+ * @returns le tag final, le fichier, et si son corps est exécutable.
+ * @throws Error si la base ne porte aucune table à adopter, ou si l'outil échoue.
+ */
+export declare function adoptFromDatabase({ projectRoot, outDir, dialect, target, excludedTables, declaredTables, name, workDir, }: {
+    projectRoot: string;
+    outDir: string;
+    dialect: SqlDialect;
+    target: IMigrationTarget;
+    /** Tables à ne PAS lire — celles du framework, et l'historique. */
+    excludedTables: readonly string[];
+    /**
+     * Tables que l'application DÉCLARE.
+     *
+     * Sert à CONSTATER ce que la lecture a ramassé, jamais à le restreindre :
+     * l'outil n'accepte qu'une exclusion (une liste positive tue son
+     * introspection sur MySQL). Une base partagée avec un autre logiciel voit
+     * donc ses tables entrer dans la référence — le taire les ferait proposer à
+     * la suppression à la génération suivante, sans que personne l'ait vu venir.
+     */
+    declaredTables: readonly string[];
+    name: string;
+    workDir: string;
+}): Promise<IAdoptedBaseline>;
+export {};