@nodefony/drizzle 10.0.0-alpha.1

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

@@ -0,0 +1,273 @@
+import type { SqlDialect } from "../../config/config.js";
+import type { ISchemaReader } from "./catalog.js";
+/**
+ * URL de connexion réservée au **travail de migration**.
+ *
+ * Elle porte le compte qui a le droit de modifier le schéma — un compte que les
+ * exemplaires qui servent le trafic n'ont pas, et ne doivent pas avoir. C'est
+ * tout son intérêt : le secret est monté dans le travail de migration
+ * seulement.
+ *
+ * **Qui la lit, exactement** : les commandes `orm:migrate`,
+ * `orm:migrate:status`, `orm:migrate:baseline` et `orm:migrate:repair`.
+ * Personne d'autre — ni le démarrage de l'application, ni `orm:reset`, ni un
+ * store. Une variable de privilège élevé qui fuiterait dans le chemin ordinaire
+ * annulerait le moindre privilège qu'elle sert à installer.
+ *
+ * ⚠️ Elle doit désigner une connexion **directe** au serveur. Un répartiteur de
+ * connexions en mode transaction (PgBouncer `transaction`) casse les verrous
+ * consultatifs de session — et le verrou de l'applicateur en est un.
+ */
+export declare const MIGRATE_URL_ENV = "NF_MIGRATE_DATABASE_URL";
+/**
+ * Contrats de l'applicateur de migrations — verdicts, entrées de journal,
+ * historique, plan, et le pilote à connexion unique dont il a besoin.
+ *
+ * **Pourquoi un fichier de types séparé** : ces formes traversent la frontière
+ * npm (CLI, data plane d'administration, sonde de disponibilité, porte MCP) —
+ * quatre consommateurs pour un seul producteur. Les tenir à part évite qu'un
+ * import de l'applicateur tire les pilotes de base de données avec lui.
+ */
+/**
+ * Nom de la table d'historique — **jamais qualifié d'un schéma**.
+ *
+ * Elle suit donc le `search_path` de la connexion, exactement comme les tables
+ * d'entités. Écrire `public.nodefony_migrations` exclurait à vie le patron
+ * PostgreSQL d'isolation par schéma sur une base mutualisée : déplacer ensuite
+ * la table d'historique chez un utilisateur serait une migration de données,
+ * pas un correctif.
+ */
+export declare const HISTORY_TABLE = "nodefony_migrations";
+/**
+ * Marqueur de format que porte la première ligne de chaque fichier `.sql`.
+ *
+ * Le format de découpe est celui de drizzle-kit, adopté à vie ; un défaut
+ * découvert après publication ne pourrait plus être corrigé sans changer le
+ * SENS de fichiers déjà livrés. Le marqueur donne la porte de sortie : un
+ * fichier d'un autre format est **refusé en le nommant**, jamais lu au mieux.
+ */
+export declare const FORMAT_MARKER = "-- nodefony:migration format=1";
+/** Séparateur de statements produit par drizzle-kit. */
+export declare const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+/**
+ * Codes de refus stables de l'applicateur.
+ *
+ * Ils sont le contrat lu par une machine — un agent lit `code`, jamais une
+ * phrase française. Ajouter un code est additif ; en changer un est une
+ * rupture, au même titre qu'un code de sortie.
+ */
+export type MigrationVerdictCode = 
+/** Historique vide alors que les tables du schéma existent déjà. */
+"NF_MIGRATE_BASELINE_REQUIRED"
+/** Une migration a échoué (ou n'a jamais fini) : réparer avant de reprendre. */
+ | "NF_MIGRATE_FAILED_MARKER"
+/** Le fichier d'une migration appliquée a changé depuis son application. */
+ | "NF_MIGRATE_HASH_MISMATCH"
+/** Une migration en attente se range AVANT la dernière appliquée de sa source. */
+ | "NF_MIGRATE_OUT_OF_ORDER"
+/** Une migration appliquée n'a plus de fichier dans une source pourtant présente. */
+ | "NF_MIGRATE_MISSING_FILE"
+/** Un fichier ne porte pas le format que cet applicateur sait lire. */
+ | "NF_MIGRATE_UNKNOWN_FORMAT"
+/** Le verrou n'a pas pu être obtenu dans le délai imparti. */
+ | "NF_MIGRATE_LOCK_TIMEOUT"
+/** Le tag demandé (`--up-to`) ne désigne aucune migration connue. */
+ | "NF_MIGRATE_UNKNOWN_TAG"
+/** La source demandée (`--source`) n'est pas déclarée par cette application. */
+ | "NF_MIGRATE_UNKNOWN_SOURCE"
+/** Le journal d'une source annonce un fichier que le dossier ne contient pas. */
+ | "NF_MIGRATE_JOURNAL_MISMATCH";
+/** Commande à exécuter pour lever un refus — l'agent lit `nextActions[0]`. */
+export interface IMigrationAction {
+    /** Commande complète, prête à copier. */
+    command: string;
+    /** Arguments, séparés pour un appel programmatique. */
+    args: string[];
+}
+/**
+ * Verdict structuré : **la source**, dont la prose n'est qu'un rendu.
+ *
+ * Un producteur, quatre rendus (phrase de la CLI, `--json`, data plane,
+ * indication dans un corps d'erreur). Écrire le message pour l'humain ET un
+ * JSON pour la machine ferait deux implémentations d'une même règle, qui
+ * divergeraient.
+ */
+export interface IMigrationVerdict {
+    /** Code stable du refus. */
+    code: MigrationVerdictCode;
+    /** Connecteur concerné. */
+    connector: string;
+    /** Source de migrations concernée, quand le refus en désigne une. */
+    source?: string;
+    /** Tag concerné, quand le refus en désigne un. */
+    tag?: string;
+    /** Faits constatés, sans mise en forme — de quoi rendre la phrase. */
+    facts: Record<string, string | number | boolean | readonly string[]>;
+    /** Ce qu'il faut faire ensuite, du plus direct au plus assumé. */
+    nextActions: IMigrationAction[];
+}
+/**
+ * Une source de migrations : un espace de noms OUVERT.
+ *
+ * `framework` et `app` sont deux valeurs **réservées**, pas une énumération :
+ * le registre d'entités est déjà ouvert à N modules, et un modèle à deux
+ * valeurs casserait APRÈS publication (un module tiers n'aurait d'autre choix
+ * que de se déverser dans `app`, et désinstaller un module bloquerait toute
+ * migration ultérieure, pour toujours).
+ */
+export interface IMigrationSource {
+    /** Nom logique, découplé du paquet qui livre le dossier. */
+    name: string;
+    /** Dossier RACINE des migrations ; le sous-dossier de dialecte est dérivé. */
+    dir: string;
+    /** Rang d'application : `framework` = 0, modules ensuite, `app` en dernier. */
+    rank: number;
+}
+/** Un fichier de migration chargé depuis une source. */
+export interface IMigrationFile {
+    /** Source qui le livre. */
+    source: string;
+    /** Identité immuable du fichier (`0000_framework_init`). */
+    tag: string;
+    /** Rang dans le journal de SA source. */
+    idx: number;
+    /** Empreinte auto-descriptive `sha256:<hex>` du contenu normalisé. */
+    hash: string;
+    /** Statements découpés, dans l'ordre, sans les vides. */
+    statements: readonly string[];
+    /** Chemin du fichier — pour nommer un refus. */
+    path: string;
+}
+/** Une ligne de la table d'historique, colonnes lues NOMMÉMENT. */
+export interface IAppliedMigration {
+    source: string;
+    tag: string;
+    hash: string;
+    runId: string;
+    startedAt: number;
+    finishedAt: number | null;
+    executionMs: number | null;
+    success: boolean;
+    error: string | null;
+    appliedBy: string | null;
+}
+/** Une dérive constatée : le fichier a changé après avoir été appliqué. */
+export interface IMigrationDrift {
+    source: string;
+    tag: string;
+    /** Empreinte enregistrée au moment de l'application. */
+    expected: string;
+    /** Empreinte du fichier tel qu'il est aujourd'hui. */
+    actual: string;
+}
+/**
+ * État complet, calculé en LECTURE SEULE.
+ *
+ * Même producteur pour la CLI, le data plane, la porte d'agent et la sonde de
+ * disponibilité — quatre consommateurs, une seule vérité.
+ */
+export interface IMigrationPlan {
+    connector: string;
+    dialect: SqlDialect;
+    /** Migrations appliquées avec succès, ordre d'application. */
+    applied: readonly IAppliedMigration[];
+    /** Migrations à appliquer, dans l'ordre (rang de source, puis journal). */
+    pending: readonly IMigrationFile[];
+    /** Fichiers modifiés après application. */
+    drifted: readonly IMigrationDrift[];
+    /** Marqueurs d'échec, ou migrations jamais terminées. */
+    failed: readonly IAppliedMigration[];
+    /** Appliquées en base mais sans fichier, dans une source PRÉSENTE. */
+    missing: readonly {
+        source: string;
+        tag: string;
+    }[];
+    /** Sources vues en base mais absentes du registre — ignorées, jamais bloquantes. */
+    ignoredSources: readonly string[];
+    /** Historique vide alors que les tables du schéma existent déjà. */
+    baselineRequired: boolean;
+}
+/** Résultat de l'application d'une migration. */
+export interface IMigrationApplied {
+    source: string;
+    tag: string;
+    executionMs: number;
+}
+/** Résultat d'un `migrate()`. */
+export interface IMigrationRun {
+    /** Identifiant du run — groupe les migrations d'un même déploiement. */
+    runId: string;
+    /** Migrations effectivement appliquées, dans l'ordre. */
+    applied: readonly IMigrationApplied[];
+}
+/**
+ * Pilote de base de données de l'applicateur — **une connexion, pas un pool**.
+ *
+ * `pg_advisory_lock` et `GET_LOCK` sont des verrous de SESSION : un pool les
+ * rend inopérants (verrou pris sur une connexion, DDL exécuté sur une autre,
+ * libération sur une troisième). L'applicateur tient donc sa propre connexion,
+ * du verrou jusqu'à sa libération, avec les mêmes pilotes chargés en lazy que
+ * l'adapter — aucune dépendance nouvelle.
+ */
+export interface IMigrationDriver extends ISchemaReader {
+    /** Dialecte servi. */
+    readonly dialect: SqlDialect;
+    /**
+     * Le DDL de ce dialecte est-il transactionnel ?
+     *
+     * MySQL répond `false` : un `CREATE TABLE` y valide implicitement. C'est ce
+     * qui interdit toute reprise aveugle après un échec — la réparation tranche.
+     */
+    readonly transactionalDdl: boolean;
+    /** Exécute un statement sans résultat. */
+    exec(sql: string): Promise<void>;
+    /** Exécute une requête paramétrée ; les paramètres s'écrivent `?`. */
+    query<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /** Ouvre une transaction (`BEGIN IMMEDIATE` en sqlite). */
+    begin(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    /**
+     * Prend le verrou d'applicateur, ou lève au bout de `timeoutMs`.
+     *
+     * L'identité du verrou est un **contrat inter-versions** : deux versions du
+     * framework qui ne s'excluent plus, c'est pendant un déploiement que ça se
+     * paie — le seul moment qui compte.
+     */
+    lock(timeoutMs: number): Promise<void>;
+    /** Libère le verrou. Sans effet s'il n'était pas tenu. */
+    unlock(): Promise<void>;
+    /** Ferme la connexion. */
+    close(): Promise<void>;
+}
+/**
+ * Le verrou d'applicateur n'a pas été obtenu dans le délai imparti.
+ *
+ * Une classe, et pas une `Error` nue, pour une raison précise : c'est ce qui
+ * permet à l'applicateur de la reconnaître et de la rendre sous le code
+ * `NF_MIGRATE_LOCK_TIMEOUT`, publié dans le contrat et lu par les
+ * orchestrateurs pour décider d'ATTENDRE puis de reprendre. Levée nue, elle
+ * tombait dans le fourre-tout des pannes : le code promis n'était jamais émis,
+ * et les branches qui l'attendaient — jusqu'au code de sortie — étaient
+ * inatteignables.
+ *
+ * Un verrou tenu n'est pas une panne : c'est le déploiement d'à côté qui
+ * travaille, et la réponse est d'attendre.
+ */
+export declare class MigrationLockTimeoutError extends Error {
+    readonly timeoutMs: number;
+    /**
+     * @param timeoutMs - délai d'attente écoulé.
+     * @param message - phrase française destinée à un humain.
+     */
+    constructor(timeoutMs: number, message: string);
+}
+/** Erreur portant un {@link IMigrationVerdict} — le message n'est qu'un rendu. */
+export declare class MigrationVerdictError extends Error {
+    readonly verdict: IMigrationVerdict;
+    /**
+     * @param verdict - verdict structuré, seule source de la décision.
+     * @param message - phrase française destinée à un humain.
+     */
+    constructor(verdict: IMigrationVerdict, message: string);
+}

package/dist/types/nodefony/src/orm-core/DrizzleOrm.d.ts

@@ -0,0 +1,241 @@
+import { Orm } from "@nodefony/orm-core";
+import type { IOrmMigrationApplyReply, IOrmMigrationPlanReply, IOrmMigrationReply } from "@nodefony/orm-core";
+import { type ISchemaComparison } from "../migrator/schemaDiff.js";
+import type { IColumnInfo, IConnectionInfo, IOrmProbe, IRepository, ITransaction } from "@nodefony/orm-core";
+import type { SqlDialect } from "../../interfaces/IDrizzleConfig.js";
+/** Options de connexion de l'adapter Drizzle (driver selon `dialect`). */
+export interface DrizzleOrmOptions {
+    /**
+     * Dialecte SQL : `sqlite` (défaut, driver better-sqlite3) · `postgres` (driver
+     * `pg`, lazy) · `mysql` (driver `mysql2`, lazy). Sélectionne le client ET la
+     * variante de table que les entités enregistrent.
+     */
+    dialect?: SqlDialect;
+    /** Fichier SQLite (`":memory:"` par défaut) — dialecte `sqlite` uniquement. */
+    filename?: string;
+    /**
+     * Chaîne de connexion (`postgres://…`, `mysql://…`) — dialectes `postgres`/
+     * `mysql`. Requise pour ces dialectes.
+     */
+    url?: string;
+    /**
+     * Le schéma doit-il être DÉRIVÉ du code à la connexion ?
+     *
+     * `true` (défaut) : `CREATE TABLE IF NOT EXISTS` et les index déclarés sont
+     * émis à chaque connexion — c'est le confort du développement et l'usage
+     * direct en banc de test.
+     *
+     * `false` : la connexion ne touche PAS au schéma. C'est ce que veulent les
+     * modes `migrate` et `none` : le schéma y appartient aux migrations, et une
+     * création dérivée qui passerait par-dessus créerait précisément la
+     * divergence que les migrations existent pour empêcher — une table posée par
+     * le démarrage n'a aucune trace dans l'historique, donc plus personne ne sait
+     * d'où elle vient.
+     */
+    deriveSchema?: boolean;
+    /**
+     * Qui sait lire l'état des migrations de CE connecteur.
+     *
+     * Injecté par le service du module, seul à détenir la configuration (fichiers
+     * de migration, mode `ddl`, coordonnées) — l'ORM, lui, ne connaît que sa
+     * connexion. Sans lui, {@link DrizzleOrm.migrationStatus} répond que le
+     * connecteur n'est pas déclaré dans la configuration, ce qui est le cas d'un
+     * ORM construit à la main dans un banc.
+     */
+    migrationStatus?: () => Promise<IOrmMigrationReply>;
+    /** Qui sait dire ce qui S'APPLIQUERAIT — même origine que `migrationStatus`. */
+    migrationPlan?: () => Promise<IOrmMigrationPlanReply>;
+    /** Qui sait APPLIQUER — refuse hors développement, en le disant. */
+    applyMigrations?: () => Promise<IOrmMigrationApplyReply>;
+}
+/**
+ * Adapter Drizzle (driver `better-sqlite3`) **branché sur `@nodefony/orm-core`**
+ * — 3ᵉ adapter du banc multi-ORM (P7.4), choix SQL #1 moderne.
+ *
+ * Particularité vs les autres ORM : Drizzle est **schema-as-code** — il n'y
+ * a pas de « compilation » de modèle. `entity.schema` *est* déjà une table
+ * Drizzle (`sqliteTable(...)`). L'adapter :
+ * - dérive le DDL de chaque table via `getTableConfig()` et le crée (dev/test ;
+ *   la prod passera par `drizzle-kit`) — pas de `sync()` natif côté Drizzle ;
+ * - résout les relations déclaratives ({@link IEntityRelation}) en métadonnées
+ *   d'**eager-load manuel** (cf {@link DrizzleRepository}), pour rester générique
+ *   sans imposer la couche `relations()` de Drizzle ;
+ * - pilote les transactions à la main (`BEGIN`/`COMMIT`/`ROLLBACK`) car
+ *   `better-sqlite3` est synchrone (cf {@link DrizzleTransaction}).
+ *
+ * Trappe SQL brut : {@link DrizzleOrm.getNativeConnection} expose le db Drizzle
+ * (tag `sql`) pour les jointures arbitraires (ADR-0003 risque #1).
+ */
+export declare class DrizzleOrm extends Orm {
+    #private;
+    /**
+     * Ce que cet adapter sait de l'état de sa connexion, **par dialecte**.
+     *
+     * `postgres`/`mysql` traduisent les signaux de leur pool → `"events"`.
+     * `sqlite` est une base EMBARQUÉE : il n'y a ni serveur à perdre ni socket
+     * à surveiller, donc rien à constater — dire `"assumed"` n'est pas un aveu
+     * de faiblesse, c'est la description exacte de la situation.
+     */
+    get liveness(): "events" | "assumed";
+    /**
+     * @param name - clé unique de l'ORM dans le `ormRegistry` (ex. `"db_test"`).
+     * @param options - options de connexion (`dialect`, `filename` sqlite, `url` pg).
+     */
+    constructor(name: string, options?: DrizzleOrmOptions);
+    /**
+     * Le schéma est-il dérivé du code à la connexion, ou appartient-il aux
+     * migrations ?
+     *
+     * Se lire de l'extérieur a un usage précis : une brique qui s'apprête à
+     * interroger une table doit pouvoir dire si quelqu'un la crée. Quand la
+     * réponse est « non » et que la table ne figure dans aucune migration, un refus
+     * au démarrage vaut infiniment mieux qu'une erreur de colonne inconnue à la
+     * première requête d'un utilisateur.
+     *
+     * @returns `true` en mode `auto` (développement, test), `false` sinon.
+     */
+    get derivesSchema(): boolean;
+    /** Dialecte SQL de ce connecteur. */
+    get dialect(): SqlDialect;
+    /**
+     * Écart constaté entre le schéma déclaré par le code et la base — `null`
+     * quand la base est conforme.
+     *
+     * Publié pour que trois surfaces disent la MÊME chose : le corps d'erreur
+     * rendu au client, la sonde de disponibilité, et l'écran d'administration.
+     * En mode dérivé il est renseigné au démarrage, après rattrapage de ce qui se
+     * rattrapait ; ailleurs il ne l'est que sur demande explicite
+     * ({@link DrizzleOrm.compareToDeclared}).
+     */
+    get schemaDrift(): ISchemaComparison | null;
+    /**
+     * Compare la base à ce que le code déclare — sans jamais rien modifier.
+     *
+     * C'est la **troisième source** : les outils de migration croisent les
+     * fichiers et l'historique, et concluent « tout est appliqué » sans avoir
+     * regardé la base. Croiser le schéma réel rend visible l'incident qu'aucun
+     * d'eux ne voit — historique complet, rien en attente, et pourtant la base ne
+     * correspond pas au code (un `ALTER` passé à la main, un correctif jamais
+     * reporté, deux environnements qui ont divergé).
+     *
+     * La lecture passe par la connexion DÉJÀ ouverte de ce connecteur : en
+     * ouvrir une seconde sur `:memory:` désignerait une base vide et rendrait un
+     * verdict faux.
+     *
+     * @returns les écarts, séparés selon qu'ils se rattrapent ou non.
+     */
+    compareToDeclared(): Promise<ISchemaComparison>;
+    /**
+     * Emplacement PHYSIQUE lisible de la base, pour l'écran Studio « Stores »
+     * (« où sont écrites mes données ? »). Fichier SQLite **relativisé** au cwd
+     * (anti info-leak, cf {@link DrizzleOrm.#safeTarget}) — `undefined` pour
+     * `:memory:` (volatil) et pour un backend RÉSEAU (postgres/mysql), dont
+     * l'emplacement EST l'infra déclarée, déjà surfacée à part (le Studio dérive
+     * alors « backend réseau — voir l'infra »). Stable dès la construction
+     * (`#filename` fixé au ctor, indépendant du connect).
+     */
+    get location(): string | undefined;
+    protected onConnect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getRepository<T = unknown>(name: string): IRepository<T>;
+    /**
+     * Exécute `work` dans une transaction, sur les TROIS dialectes : commit si la
+     * closure résout, rollback si elle rejette (cf {@link DrizzleTransaction}).
+     *
+     * Un repository n'entre dans la transaction que lié par `withTransaction(tx)` :
+     * en postgres/mysql, la transaction tient une connexion dédiée du pool, tandis
+     * que `getRepository()` écrit via le pool — donc hors transaction.
+     *
+     * @param work - travail transactionnel ; reçoit la transaction à lier aux repositories.
+     * @returns la valeur rendue par `work`.
+     * @throws `not connected` hors connexion ; sinon l'erreur de `work`, après rollback.
+     */
+    transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>;
+    getNativeConnection<C = unknown>(): C;
+    /**
+     * État des migrations de ce connecteur — la MÊME charge utile que
+     * `orm:migrate:status --json`, jamais un second calcul.
+     *
+     * Le travail est fait par le lecteur injecté à la construction : lui seul
+     * détient la configuration (fichiers, mode `ddl`, coordonnées), quand cet
+     * objet ne connaît que sa connexion. Sans lecteur — un ORM construit à la
+     * main dans un banc —, la réponse dit exactement cela, et surtout PAS « ne
+     * porte pas de migrations » : ce serait faux d'un connecteur SQL, et un
+     * message faux publié est appris par les scripts qui le lisent.
+     *
+     * @returns l'état, ou l'empêchement qui explique pourquoi il n'y en a pas.
+     */
+    migrationStatus(): Promise<IOrmMigrationReply>;
+    /**
+     * Ce qui S'APPLIQUERAIT, avec son SQL — lecture seule.
+     *
+     * @returns le plan, ou l'empêchement.
+     */
+    migrationPlan(): Promise<IOrmMigrationPlanReply>;
+    /**
+     * Applique les migrations en attente — **développement seulement**, le
+     * lecteur injecté refuse ailleurs en le disant.
+     *
+     * @returns ce qui a été appliqué, ou l'empêchement.
+     */
+    applyMigrations(): Promise<IOrmMigrationApplyReply>;
+    /**
+     * Ping bas-coût : `SELECT 1` — round-trip RÉEL vers la base, routé par
+     * dialecte (pool pg/mysql, client better-sqlite3 synchrone).
+     *
+     * @throws si le connecteur n'est pas connecté.
+     */
+    ping(): Promise<void>;
+    /**
+     * Sonde driver-spécifique, **routée par dialecte** — alimente le data plane
+     * admin (panneau Studio ORM) :
+     * - **sqlite** : stockage via PRAGMA (synchrone, bon marché) — taille
+     *   (`page_count × page_size`), mode de journal (WAL ?), pages libres ;
+     * - **postgres / mysql** : état du **pool**, la métrique qui compte sur une
+     *   base serveur (sa saturation est une falaise de débit) — lu sur des
+     *   compteurs EN MÉMOIRE, donc sans requête réseau.
+     *
+     * Le stockage d'une base serveur n'est PAS sondé : il coûterait une requête
+     * (`pg_database_size`…) à chaque appel, pour une donnée que l'admin du SGBD
+     * expose déjà. Mieux vaut ne rien promettre que promettre en silence.
+     *
+     * Best-effort — `{}` seulement si le connecteur n'est pas connecté.
+     *
+     * @returns sonde `storage` (sqlite) ou `pool` (serveur), `{}` hors connexion.
+     */
+    probe(): Promise<IOrmProbe>;
+    /**
+     * Colonnes normalisées d'une entité, dérivées du DDL Drizzle
+     * (`getTableConfig`) — alimente le graphe canonique / ERD / contexte IA.
+     *
+     * @param name - nom logique de l'entité.
+     * @returns colonnes (`[]` si l'entité n'est pas connue de cet ORM).
+     */
+    describeEntity(name: string): IColumnInfo[];
+    /**
+     * Décrit le schéma ENTIER attendu par le code : une entrée par table.
+     *
+     * Même calcul que {@link DrizzleOrm.describeEntity}, à l'échelle du
+     * connecteur — et c'est le point : le rattrapage de colonnes au démarrage, le
+     * constat de divergence et l'écran d'administration comparent tous « ce que
+     * le code déclare » à « ce que la base contient ». Trois lecteurs, un seul
+     * producteur ; recopier ce parcours ailleurs le ferait diverger du jour où
+     * un dialecte s'ajoute.
+     *
+     * @returns une entrée par table, avec son NOM EN BASE (≠ nom d'entité).
+     */
+    describeTables(): {
+        entity: string;
+        table: string;
+        columns: IColumnInfo[];
+    }[];
+    /**
+     * Décrit la connexion : driver `sqlite` (better-sqlite3) + cible (chemin du
+     * fichier, `:memory:` pour les tests). Aucun credential (SQLite = fichier local).
+     * Le chemin est **relativisé** à la racine du process : on ne fuite jamais
+     * l'arborescence absolue du serveur (home, structure FS) dans le data plane.
+     *
+     * @returns driver + cible (chemin relatif, basename si hors projet, ou `:memory:`).
+     */
+    describeConnection(): IConnectionInfo;
+}

package/dist/types/nodefony/src/orm-core/DrizzleRepository.d.ts

@@ -0,0 +1,98 @@
+import type { Column } from "drizzle-orm";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+import type { PgTable } from "drizzle-orm/pg-core";
+import type { MySqlTable } from "drizzle-orm/mysql-core";
+import type { SqlDialect } from "../../interfaces/IDrizzleConfig.js";
+import type { Criteria, IRepository, ITransaction, RepositoryReadOptions, UpdateData } from "@nodefony/orm-core";
+/**
+ * Handle Drizzle (instance racine ou transaction) — schéma résolu côté adapter.
+ *
+ * Typage = **vue d'exécution CANONIQUE** (surface better-sqlite3) quel que soit
+ * le dialecte : `NodePgDatabase` expose la même surface builder pour les verbes
+ * du repository (`select`/`insert`/`update`/`delete`), et l'exactitude runtime
+ * est prouvée par les e2e PG (session/token/user/webauthn/totp/audit/webhook).
+ * La surface d'exécution native qui DIVERGE (`db.all` vs `db.execute().rows`)
+ * est routée par le `queryKit` — jamais ici.
+ */
+export type DrizzleDb = BetterSQLite3Database<Record<string, never>>;
+/** Table Drizzle multi-dialecte (l'union honnête des variantes colKit). */
+export type DrizzleTable = SQLiteTable | PgTable | MySqlTable;
+/** Colonne Drizzle dialecte-agnostique (classe de base — acceptée par les
+ *  opérateurs `eq`/`lt`/`asc`… et les fragments `sql`). */
+export type DrizzleColumn = Column;
+/**
+ * Vue d'exécution canonique (typage sqlite) d'une table multi-dialecte —
+ * **LE point unique** de conversion vers les builders (cf {@link DrizzleDb} :
+ * la surface builder est structurellement identique sqlite/pg, prouvée e2e).
+ * Consommé aussi par les stores à requêtes builder (`DrizzleAuditStore`).
+ */
+export declare function execTable(table: DrizzleTable): SQLiteTable;
+/**
+ * Relation résolue au boot de l'ORM, prête pour l'eager-load manuel (sans la
+ * couche `relations()` de Drizzle, pour rester générique cross-entités).
+ */
+export interface DrizzleResolvedRelation {
+    /** Cardinalité. */
+    type: "one-to-many" | "many-to-one" | "one-to-one";
+    /** Table cible Drizzle (variante du dialecte du connecteur). */
+    targetTable: DrizzleTable;
+    /** Colonne clé étrangère (sur la cible pour 1-N, sur la source pour N-1). */
+    foreignKey: string;
+    /** Clé primaire de l'entité courante (côté parent du 1-N). */
+    localKey: string;
+    /** Clé primaire de la cible (côté lookup du N-1). */
+    targetKey: string;
+}
+/**
+ * Repository portable (contrat {@link IRepository}) au-dessus d'une table Drizzle
+ * + driver `better-sqlite3`.
+ *
+ * 3ᵉ adapter du banc orm-core (ADR-0003) : valide le contrat sur un ORM
+ * **type-safe-first** dont le `WHERE` est un *builder* d'expressions (pas un objet
+ * plat). Spécificités traduites ici :
+ * - critère portable → expressions Drizzle (`eq`/`and`/`gt`/`inArray`/`like`...),
+ *   opérateurs riches inclus (résolution ADR-0003 risque #3) ;
+ * - **eager-load manuel** (`options.relations`) : une requête `IN (...)` par
+ *   relation déclarée, puis regroupement en mémoire — portable sans déclarer la
+ *   couche `relations()` de Drizzle ;
+ * - liaison transactionnelle via {@link DrizzleRepository.withTransaction} (le
+ *   handle de transaction *est* un db Drizzle → réutilisé tel quel).
+ *
+ * @typeParam T - forme plate de l'entité gérée.
+ */
+export declare class DrizzleRepository<T = unknown> implements IRepository<T> {
+    #private;
+    /**
+     * @param db - handle Drizzle (instance racine ou transaction).
+     * @param table - table Drizzle de l'entité (variante du dialecte).
+     * @param relations - relations résolues (eager-load), indexées par champ.
+     * @param connector - nom de la connexion (clé du registre) — défaut `"default"`.
+     * @param dialect - dialecte SQL du connecteur — défaut `"sqlite"`.
+     * @param transactional - `true` quand `db` est un handle de transaction :
+     *   l'instance est jetable (une par `withTransaction`) et, en pg, sa connexion
+     *   dédiée est rendue au commit — préparer dessus coûterait sans jamais
+     *   s'amortir. Les transactions gardent le chemin non préparé.
+     */
+    constructor(db: DrizzleDb, table: DrizzleTable, relations: Record<string, DrizzleResolvedRelation>, connector?: string, dialect?: SqlDialect, transactional?: boolean);
+    find(criteria?: Criteria<T>, options?: RepositoryReadOptions): Promise<T[]>;
+    findOne(criteria: Criteria<T>, options?: RepositoryReadOptions): Promise<T | null>;
+    create(data: Partial<T>): Promise<T>;
+    createMany(data: Partial<T>[]): Promise<T[]>;
+    updateOne(criteria: Criteria<T>, data: Partial<T>): Promise<T | null>;
+    upsert(criteria: Criteria<T>, update: UpdateData<T>, insertOnly?: Partial<T>): Promise<T>;
+    updateMany(criteria: Criteria<T>, data: Partial<T>): Promise<number>;
+    increment(criteria: Criteria<T>, changes: Partial<Record<keyof T, number>>): Promise<T | null>;
+    delete(criteria: Criteria<T>): Promise<number>;
+    deleteOne(criteria: Criteria<T>): Promise<boolean>;
+    findOneAndDelete(criteria: Criteria<T>): Promise<T | null>;
+    count(criteria?: Criteria<T>): Promise<number>;
+    /**
+     * `COUNT(DISTINCT col)` natif — la déduplication reste dans le moteur, aucune
+     * ligne n'est rapatriée. `COUNT(DISTINCT …)` ignore les `NULL` sur les trois
+     * dialectes, ce qui donne au contrat sa sémantique sans clause supplémentaire.
+     */
+    countDistinct(field: keyof T & string, criteria?: Criteria<T>): Promise<number>;
+    exists(criteria: Criteria<T>): Promise<boolean>;
+    withTransaction(tx: ITransaction): IRepository<T>;
+}