@nodefony/drizzle 10.0.0-alpha.1

package/dist/nodefony/src/orm-core/DrizzleOrm.js

@@ -0,0 +1,1154 @@
+import { schemaReader, toDollarParams } from "../migrator/catalog.js";
+import { notConfigured } from "../migrator/refusals.js";
+import { additiveSql, compareSchema, hasGap } from "../migrator/schemaDiff.js";
+import { describeTargetSafely } from "../safeTarget.js";
+import { failureFrom } from "../migrator/status.js";
+import { DrizzleRepository } from "./DrizzleRepository.js";
+import { DrizzleTransaction } from "./DrizzleTransaction.js";
+import { createRequire } from "node:module";
+import { Orm, entityRegistry } from "@nodefony/orm-core";
+import fs from "node:fs";
+import path from "node:path";
+import { is } from "drizzle-orm";
+import { SQLiteSyncDialect, SQLiteTable, getTableConfig } from "drizzle-orm/sqlite-core";
+import { PgDialect, PgTable, getTableConfig as getTableConfig$1 } from "drizzle-orm/pg-core";
+import { MySqlDialect, MySqlTable, getTableConfig as getTableConfig$2 } from "drizzle-orm/mysql-core";
+//#region nodefony/src/orm-core/DrizzleOrm.ts
+/**
+* Rend le prédicat d'une contrainte `CHECK` en SQL littéral, avec la grammaire
+* du dialecte demandé.
+*
+* Un `CHECK` ne peut porter **aucun paramètre lié** : une définition de table
+* n'a pas de place où en fournir la valeur. Le prédicat qui en produirait un
+* est donc écarté plutôt qu'émis avec un `?` que le serveur refuserait — le
+* colKit, seul producteur de contraintes du framework, compose exclusivement en
+* `sql.raw`.
+*
+* @param check - contrainte lue sur la table Drizzle.
+* @param dialect - dialecte SQL cible (grammaire de citation et de paramètre).
+* @returns le prédicat littéral, ou `null` s'il porte un paramètre lié.
+*/
+function renderCheck(check, dialect) {
+	const query = dialect === "postgres" ? new PgDialect().sqlToQuery(check.value) : dialect === "mysql" ? new MySqlDialect().sqlToQuery(check.value) : new SQLiteSyncDialect().sqlToQuery(check.value);
+	return query.params.length === 0 ? query.sql : null;
+}
+/**
+* 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).
+*/
+var DrizzleOrm = class DrizzleOrm extends Orm {
+	#client = null;
+	/**
+	* Détacheurs des listeners de cycle de vie posés sur le pool natif.
+	* `null` tant qu'aucun pool réseau n'est ouvert (SQLite n'en a pas) — lazy,
+	* et surtout : un `disconnect()`/`connect()` répété empilerait sinon un jeu
+	* de listeners par cycle.
+	*/
+	#unwire = null;
+	/**
+	* 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() {
+		return this.#dialect === "sqlite" ? "assumed" : "events";
+	}
+	/** Pool `pg` (dialecte postgres) — `null` hors postgres ou non connecté. */
+	#pgPool = null;
+	/** Pool `mysql2/promise` (dialecte mysql) — `null` hors mysql ou non connecté. */
+	#mysqlPool = null;
+	#db = null;
+	/**
+	* Ouvre une transaction sur le driver du connecteur — posée par le
+	* `#connectX` du dialecte, `null` hors connexion.
+	*
+	* **Pourquoi une fabrique par dialecte plutôt qu'un `switch` dans
+	* {@link DrizzleOrm.transaction}** : une transaction postgres/mysql exige une
+	* connexion DÉDIÉE empruntée au pool (le `BEGIN` et les écritures doivent
+	* tomber sur la MÊME connexion, sinon aucune atomicité) et le db Drizzle qui
+	* lui est lié — donc la factory `drizzle` du driver, importée en LAZY au
+	* connect. La closure capture ce que seul le connect connaît, et
+	* `transaction()` reste un chemin unique, sans réimport ni branche.
+	*/
+	#beginTx = null;
+	/**
+	* File d'attente des transactions **sqlite** (lazy, `null` au repos) — dernier
+	* maillon de la chaîne : chaque transaction attend le précédent, et libère le
+	* suivant en se terminant.
+	*
+	* **Pourquoi** : la connexion `better-sqlite3` est UNIQUE → c'est un pool de
+	* taille 1. Sans file, deux transactions concurrentes (= deux requêtes HTTP
+	* simultanées) émettent deux `BEGIN` sur la même connexion et la seconde
+	* échoue (`cannot start a transaction within a transaction`) — un framework
+	* qui assume sqlite en prod mono-nœud doit encaisser ça. postgres/mysql n'en
+	* ont pas besoin : leur pool EST la file d'attente (prouvé au banc — 15
+	* transactions simultanées sur un pool de 10 passent).
+	*/
+	#sqliteTxGate = null;
+	/**
+	* Tables Drizzle indexées par nom logique d'entité (lazy) — union
+	* multi-dialecte {@link DrizzleTable} (variante sqlite OU pg selon le
+	* connecteur), consommée telle quelle par le `DrizzleRepository` porté.
+	*/
+	#tables = null;
+	/** Relations résolues : entité → champ → relation eager-load (lazy). */
+	#relations = null;
+	/** Repositories mémoïsés par nom d'entité (lazy). */
+	#repositories = null;
+	#dialect;
+	/**
+	* Le schéma est-il dérivé du code à la connexion ? (cf `deriveSchema`)
+	*
+	* Fixé au constructeur : changer d'avis en cours de vie ferait qu'une
+	* reconnexion poserait des tables qu'un exploitant croyait sous contrôle des
+	* migrations.
+	*/
+	#deriveSchema;
+	/**
+	* Écart CONSTATÉ entre le schéma déclaré et la base — `null` tant qu'il n'y
+	* en a pas, ce qui est le cas courant : rien n'est alloué pour un état sain.
+	*/
+	#drift = null;
+	#filename;
+	#url;
+	/** Injecté par le service — cf {@link DrizzleOrmOptions.migrationStatus}. */
+	#migrationStatus;
+	/** Injecté par le service — cf {@link DrizzleOrmOptions.migrationPlan}. */
+	#migrationPlan;
+	/** Injecté par le service — cf {@link DrizzleOrmOptions.applyMigrations}. */
+	#applyMigrations;
+	/**
+	* @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, options = {}) {
+		super(name);
+		this.#dialect = options.dialect ?? "sqlite";
+		this.#deriveSchema = options.deriveSchema !== false;
+		this.#filename = options.filename ?? ":memory:";
+		this.#url = options.url;
+		this.#migrationStatus = options.migrationStatus;
+		this.#migrationPlan = options.migrationPlan;
+		this.#applyMigrations = options.applyMigrations;
+	}
+	/**
+	* 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() {
+		return this.#deriveSchema;
+	}
+	/** Dialecte SQL de ce connecteur. */
+	get dialect() {
+		return this.#dialect;
+	}
+	/**
+	* É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() {
+		return this.#drift;
+	}
+	/**
+	* 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() {
+		return compareSchema(schemaReader(this.#dialect, this.#rawQuery), this.describeTables());
+	}
+	/**
+	* 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() {
+		if (this.#dialect !== "sqlite" || this.#filename === ":memory:") return;
+		return this.#safeTarget();
+	}
+	/** Entités enregistrées dans `entityRegistry` ciblant cet ORM. */
+	#ownEntities() {
+		return entityRegistry.list().filter((entity) => entity.connector === this.name);
+	}
+	/** FK déterministe camelCase `<entité>Id` (parité avec Mongoose). */
+	#foreignKey(entityName) {
+		return `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Id`;
+	}
+	/**
+	* Générateur de `CREATE TABLE IF NOT EXISTS` partagé entre dialectes (dev/test).
+	* Émet uniquement les contraintes colonne (PK / NOT NULL / UNIQUE) à partir du
+	* type SQL natif de chaque colonne (`getSQLType()` rend `text`/`integer` en
+	* SQLite, `text`/`bigint`/`jsonb` en Postgres, `varchar(512)`/`json` en MySQL
+	* → DDL adapté sans code spécifique). Le quoting d'identifiants diverge :
+	* `"…"` (SQL standard, SQLite/PG) vs backtick MySQL (qui ne lit `"…"` qu'en
+	* mode ANSI_QUOTES, jamais garanti). La prod reste pilotée par drizzle-kit.
+	*/
+	#buildCreateTable(name, columns, quote = "\"", checks = [], dialect = "sqlite") {
+		const defs = columns.map((col) => {
+			const parts = [`${quote}${col.name}${quote}`, col.getSQLType()];
+			if (col.primary) parts.push("PRIMARY KEY");
+			if (col.notNull) parts.push("NOT NULL");
+			if (col.isUnique) parts.push("UNIQUE");
+			return parts.join(" ");
+		});
+		for (const check of checks) {
+			const predicate = renderCheck(check, dialect);
+			if (predicate === null) continue;
+			defs.push(`CONSTRAINT ${quote}${check.name}${quote} CHECK (${predicate})`);
+		}
+		return `CREATE TABLE IF NOT EXISTS ${quote}${name}${quote} (${defs.join(", ")})`;
+	}
+	/**
+	* Dérive les `CREATE INDEX` des index déclarés sur la table (dev/test).
+	*
+	* Les index étaient construits sur la table Drizzle mais jamais émis : une
+	* colonne déclarée indexée ne l'était nulle part, et rien ne le disait. La
+	* requête restait correcte, seulement lente — le pire genre d'écart, celui qui
+	* ne se voit qu'en charge.
+	*
+	* Pourquoi ici et pas dans `#buildCreateTable` : un index est un objet SÉPARÉ
+	* de la table en SQL standard, et `CREATE TABLE IF NOT EXISTS` ne le porterait
+	* pas. Émis à part, il arrive AUSSI sur une base de développement déjà créée —
+	* ce qu'aucune clause de table ne permettrait.
+	*
+	* Les clés étrangères, elles, ne sont toujours PAS émises : elles se déclarent
+	* DANS le `CREATE TABLE`, donc elles n'atteindraient jamais une base existante,
+	* et elles imposeraient de créer les tables dans l'ordre de leurs dépendances
+	* (indécidable sur un cycle). C'est le travail du DDL de production
+	* (drizzle-kit), pas d'un dérivé de développement.
+	*
+	* @param table - nom de la table portant les index.
+	* @param indexes - index déclarés (`getTableConfig(...).indexes`).
+	* @param quote - caractère de citation des identifiants du dialecte.
+	* @returns une instruction par index (vide s'il n'y en a aucun).
+	*/
+	#buildCreateIndexes(table, indexes, quote = "\"") {
+		const statements = [];
+		for (const entry of indexes) {
+			const { name, unique, columns } = entry.config;
+			const names = columns.map((column) => column.name).filter((column) => typeof column === "string");
+			if (names.length === 0 || names.length !== columns.length) continue;
+			const cols = names.map((column) => `${quote}${column}${quote}`).join(", ");
+			statements.push(`CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ${quote}${name}${quote} ON ${quote}${table}${quote} (${cols})`);
+		}
+		return statements;
+	}
+	/** Dérive le `CREATE TABLE` SQLite depuis la table Drizzle (dev/test). */
+	#createTableSQL(table) {
+		const { name, columns, checks } = getTableConfig(table);
+		return this.#buildCreateTable(name, columns, "\"", checks, "sqlite");
+	}
+	/** Dérive les `CREATE INDEX` SQLite depuis la table Drizzle (dev/test). */
+	#createIndexesSQL(table) {
+		const { name, indexes } = getTableConfig(table);
+		return this.#buildCreateIndexes(name, indexes);
+	}
+	/** Dérive le `CREATE TABLE` Postgres depuis la table Drizzle (dev/test). */
+	#createTablePgSQL(table) {
+		const { name, columns, checks } = getTableConfig$1(table);
+		return this.#buildCreateTable(name, columns, "\"", checks, "postgres");
+	}
+	/** Dérive les `CREATE INDEX` Postgres depuis la table Drizzle (dev/test). */
+	#createIndexesPgSQL(table) {
+		const { name, indexes } = getTableConfig$1(table);
+		return this.#buildCreateIndexes(name, indexes);
+	}
+	/** Dérive le `CREATE TABLE` MySQL depuis la table Drizzle (dev/test). */
+	#createTableMysqlSQL(table) {
+		const { name, columns, checks } = getTableConfig$2(table);
+		return this.#buildCreateTable(name, columns, "`", checks, "mysql");
+	}
+	/**
+	* Dérive les `CREATE INDEX` MySQL depuis la table Drizzle (dev/test).
+	*
+	* MySQL ne connaît pas `CREATE INDEX IF NOT EXISTS` : la clause est retirée, et
+	* l'exécution tolère l'erreur « index déjà existant » (le seul cas où rejouer
+	* le DDL de développement doit rester silencieux).
+	*/
+	#createIndexesMysqlSQL(table) {
+		const { name, indexes } = getTableConfig$2(table);
+		return this.#buildCreateIndexes(name, indexes, "`").map((statement) => statement.replace(" IF NOT EXISTS", ""));
+	}
+	/** Résout les relations déclaratives d'une entité en métadonnées eager-load. */
+	#resolveRelations(entity, tables) {
+		const resolved = {};
+		for (const relation of entity.relations ?? []) {
+			const target = tables[relation.target];
+			if (!target) throw new Error(`DrizzleOrm "${this.name}": relation target "${relation.target}" (from "${entity.name}.${relation.field}") not registered for this ORM.`);
+			resolved[relation.field] = this.#resolveOne(entity, relation, target);
+		}
+		return resolved;
+	}
+	/** Construit une relation résolue (FK déterministe selon la cardinalité). */
+	#resolveOne(entity, relation, target) {
+		switch (relation.type) {
+			case "one-to-many": return {
+				type: "one-to-many",
+				targetTable: target,
+				foreignKey: relation.foreignKey ?? this.#foreignKey(entity.name),
+				localKey: "id",
+				targetKey: "id"
+			};
+			case "many-to-one":
+			case "one-to-one": return {
+				type: relation.type,
+				targetTable: target,
+				foreignKey: relation.foreignKey ?? this.#foreignKey(relation.target),
+				localKey: "id",
+				targetKey: "id"
+			};
+			case "many-to-many": throw new Error(`DrizzleOrm "${this.name}": many-to-many ("${entity.name}.${relation.field}") non portable — déclarer via getNativeConnection().`);
+		}
+	}
+	async onConnect() {
+		await this.#releasePrevious();
+		this.#tables = Object.create(null);
+		this.#relations = Object.create(null);
+		const entities = this.#ownEntities();
+		switch (this.#dialect) {
+			case "sqlite":
+				await this.#connectSqlite(entities);
+				break;
+			case "postgres":
+				await this.#connectPostgres(entities);
+				break;
+			case "mysql": await this.#connectMysql(entities);
+		}
+		if (this.#deriveSchema) {
+			await this.#reconcileSchema();
+			await this.#createIndexes(entities);
+		}
+		for (const entity of entities) this.#relations[entity.name] = this.#resolveRelations(entity, this.#tables);
+	}
+	/**
+	* Connexion SQLite + création des tables (dev/test).
+	*
+	* Le pilote est chargé en LAZY, même patron que `#connectPostgres` et
+	* `#connectMysql` : les trois dialectes sont symétriques, et une application
+	* n'embarque que celui qu'elle ouvre. `better-sqlite3` est un binaire natif
+	* compilé à l'installation — l'imposer à une application PostgreSQL coûtait
+	* un `node-gyp` et des mégaoctets pour rien.
+	*
+	* La méthode devient asynchrone pour cette seule raison ; le pilote, lui,
+	* reste synchrone une fois chargé (`client.exec`, `client.pragma`).
+	*/
+	async #connectSqlite(entities) {
+		let Sqlite;
+		let sqliteDrizzle;
+		try {
+			const ns = await import("better-sqlite3");
+			const resolved = ns.default ?? ns;
+			if (typeof resolved !== "function") throw new Error("`better-sqlite3` did not expose a constructor");
+			Sqlite = resolved;
+			sqliteDrizzle = (await import("drizzle-orm/better-sqlite3")).drizzle;
+		} catch (e) {
+			throw new Error(`DrizzleOrm "${this.name}": the sqlite dialect needs the optional driver \`better-sqlite3\` (run \`npm i better-sqlite3\`). ${e.message}`, { cause: e });
+		}
+		const client = new Sqlite(this.#filename);
+		if (this.#filename !== ":memory:") {
+			client.pragma("journal_mode = WAL");
+			client.pragma("synchronous = NORMAL");
+		}
+		this.#client = client;
+		const db = sqliteDrizzle(client);
+		this.#db = db;
+		this.#beginTx = async () => {
+			const previous = this.#sqliteTxGate;
+			let release;
+			const mine = new Promise((resolve) => {
+				release = resolve;
+			});
+			this.#sqliteTxGate = mine;
+			if (previous) await previous;
+			client.exec("BEGIN");
+			return new DrizzleTransaction(db, {
+				exec: (sql) => {
+					client.exec(sql);
+					return Promise.resolve();
+				},
+				quoteIdent: (name) => `"${name}"`,
+				release: () => {
+					if (this.#sqliteTxGate === mine) this.#sqliteTxGate = null;
+					release();
+				}
+			});
+		};
+		for (const entity of entities) {
+			this.#assertDialectTable(entity, SQLiteTable, "sqlite");
+			const table = entity.schema;
+			this.#tables[entity.name] = table;
+			entity.model = table;
+			if (!this.#deriveSchema) continue;
+			client.exec(this.#createTableSQL(table));
+		}
+	}
+	/**
+	* Exécute une requête paramétrée sur la connexion COURANTE du connecteur.
+	*
+	* Réservé à la lecture du catalogue et au rattrapage de schéma, au démarrage.
+	* Ce n'est pas une trappe publique : `getNativeConnection()` reste le chemin
+	* documenté pour du SQL applicatif.
+	*
+	* @param sql - requête, paramètres écrits `?` (traduits pour PostgreSQL).
+	* @param params - valeurs bindées.
+	* @returns les lignes rendues.
+	*/
+	#rawQuery = async (sql, params = []) => {
+		switch (this.#dialect) {
+			case "sqlite": {
+				const statement = this.#client.prepare(sql);
+				return statement.reader ? statement.all(...params) : [];
+			}
+			case "postgres": return (await this.#pgPool.query(toDollarParams(sql), params)).rows;
+			case "mysql": {
+				const [rows] = await this.#mysqlPool.query(sql, params);
+				return Array.isArray(rows) ? rows : [];
+			}
+		}
+	};
+	/**
+	* Exécute une instruction sans résultat sur la connexion courante.
+	*
+	* @param sql - instruction DDL.
+	*/
+	async #rawExec(sql) {
+		switch (this.#dialect) {
+			case "sqlite":
+				this.#client.exec(sql);
+				return;
+			case "postgres":
+				await this.#pgPool.query(sql);
+				return;
+			case "mysql":
+				await this.#mysqlPool.query(sql);
+				return;
+		}
+	}
+	/**
+	* Confronte le schéma DÉCLARÉ par le code à celui que la base porte
+	* vraiment, répare ce qui se répare, et publie le reste.
+	*
+	* **Le cas fréquent se répare tout seul** : le back ajoute un champ qui
+	* accepte le vide, la table existe déjà, la colonne manque — elle est ajoutée
+	* et journalisée en clair. Le développeur front tire la branche, le serveur
+	* redémarre, ça marche : il n'a rien à taper, et n'a pas eu à comprendre un
+	* domaine qui n'est pas le sien.
+	*
+	* **Ce qui ne se répare pas est ÉNONCÉ, jamais deviné** : une colonne
+	* obligatoire exigerait d'inventer une valeur pour les lignes existantes, et
+	* c'est une décision métier. Une table absente relève des migrations. Dans
+	* les deux cas l'écart est publié ({@link DrizzleOrm.schemaDrift}), journalisé
+	* avec le geste exact, et **le démarrage continue** : un serveur qui refuse de
+	* démarrer n'apprend rien de plus à celui qui le lance, et lui retire le seul
+	* outil qui pourrait le renseigner.
+	*
+	* ⚠️ Ne tourne QUE lorsque le schéma est dérivé du code (développement). En
+	* `migrate`/`none`, le même calcul est demandé explicitement par
+	* {@link DrizzleOrm.compareToDeclared} — il constate, il ne répare jamais.
+	*/
+	async #reconcileSchema() {
+		const comparison = await this.compareToDeclared();
+		if (!hasGap(comparison)) {
+			this.#drift = null;
+			return;
+		}
+		for (const gap of comparison.additive) {
+			await this.#rawExec(additiveSql(gap, this.#dialect));
+			this.log(`schéma rattrapé : colonne « ${gap.column} » (${gap.type}) ajoutée à la table « ${gap.table} » — le code la déclarait, la base ne l'avait pas.`, "INFO");
+		}
+		const remaining = {
+			additive: [],
+			blocking: comparison.blocking,
+			missingTables: comparison.missingTables
+		};
+		this.#drift = hasGap(remaining) ? remaining : null;
+		if (this.#drift) this.log(this.#explainDrift(this.#drift), "CRITIC");
+	}
+	/**
+	* Met en mots un écart que le démarrage ne sait pas réparer.
+	*
+	* @param drift - l'écart restant après rattrapage.
+	* @returns le texte à journaliser, geste compris.
+	*/
+	#explainDrift(drift) {
+		const lines = [`La base du connecteur « ${this.name} » ne correspond pas au code, et l'écart ne se rattrape pas tout seul :`];
+		for (const table of drift.missingTables) lines.push(`  · table « ${table} » absente`);
+		for (const gap of drift.blocking) lines.push(`  · colonne « ${gap.table}.${gap.column} » (${gap.type}) absente et OBLIGATOIRE — la poser exigerait d'inventer une valeur pour les lignes déjà présentes`);
+		lines.push(`  Les index et les requêtes qui portent sur ces colonnes échoueront.`, `  En développement, le geste est : nodefony orm:reset --connector ${this.name}`, `  (il SUPPRIME et recrée la base — jamais hors développement).`, `  Sur une base qui porte des données, c'est une migration qu'il faut : nodefony orm:migrate:status --connector ${this.name}`);
+		return lines.join("\n");
+	}
+	/**
+	* Crée les index déclarés, table par table.
+	*
+	* **Séparé de la création des tables, et joué APRÈS le rattrapage** : un
+	* index porte sur des colonnes, et le poser sur une table à laquelle il en
+	* manque une échoue. C'était le mode de défaillance réel avant ce
+	* découpage — le serveur de développement ne démarrait plus du tout, sur une
+	* erreur de pilote (`no such column`) qui ne nommait ni le connecteur, ni le
+	* geste.
+	*
+	* @param entities - entités du connecteur.
+	*/
+	async #createIndexes(entities) {
+		const empechees = new Set(this.#drift?.missingTables ?? []);
+		for (const gap of this.#drift?.blocking ?? []) empechees.add(gap.table);
+		for (const entity of entities) {
+			const table = this.#tables?.[entity.name];
+			if (!table) continue;
+			switch (this.#dialect) {
+				case "sqlite": {
+					const t = table;
+					if (empechees.has(getTableConfig(t).name)) continue;
+					for (const statement of this.#createIndexesSQL(t)) this.#client.exec(statement);
+					break;
+				}
+				case "postgres": {
+					const t = table;
+					if (empechees.has(getTableConfig$1(t).name)) continue;
+					for (const statement of this.#createIndexesPgSQL(t)) await this.#pgPool.query(statement);
+					break;
+				}
+				case "mysql": {
+					const t = table;
+					if (empechees.has(getTableConfig$2(t).name)) continue;
+					for (const statement of this.#createIndexesMysqlSQL(t)) try {
+						await this.#mysqlPool.query(statement);
+					} catch (error) {
+						if (error.code !== "ER_DUP_KEYNAME") throw error;
+					}
+					break;
+				}
+			}
+		}
+	}
+	/**
+	* Garde fail-loud : une entité dont la table n'est pas du dialecte du
+	* connecteur (ex. variante sqlite enregistrée sur un connecteur postgres)
+	* doit échouer avec un message ACTIONNABLE — pas le `TypeError: Cannot
+	* convert undefined or null to object` cryptique de `getTableConfig`.
+	*/
+	#assertDialectTable(entity, tableCtor, dialect) {
+		if (!is(entity.schema, tableCtor)) throw new Error(`DrizzleOrm "${this.name}" (${dialect}): entity "${entity.name}" is not ported to this dialect (its schema is not a ${dialect} table). Port it via a createXTable("${dialect}") factory, or keep this connector on a dialect the entity supports (multi-dialect worksite).`);
+	}
+	/**
+	* Connexion **Postgres** : le driver `pg` (optionalDependency) et l'adapter
+	* `drizzle-orm/node-postgres` sont chargés en LAZY (`await import`) — un
+	* déploiement SQLite ne les tire jamais. Pool partagé ; DDL dérivé pour dev/test
+	* (prod = drizzle-kit). Échec d'import → message actionnable (`npm i pg`).
+	*/
+	async #connectPostgres(entities) {
+		if (!this.#url) throw new Error(`DrizzleOrm "${this.name}": dialect "postgres" requires a connection \`url\`.`);
+		let PoolCtor;
+		let pgDrizzle;
+		try {
+			const pgNs = await import("pg");
+			const resolved = pgNs.Pool ?? pgNs.default?.Pool;
+			if (!resolved) throw new Error("`pg` did not expose a `Pool` constructor");
+			PoolCtor = resolved;
+			pgDrizzle = (await import("drizzle-orm/node-postgres")).drizzle;
+		} catch (e) {
+			throw new Error(`DrizzleOrm "${this.name}": the postgres dialect needs the optional driver \`pg\` (run \`npm i pg\`). ${e.message}`, { cause: e });
+		}
+		const pool = new PoolCtor({
+			connectionString: this.#url,
+			keepAlive: true,
+			keepAliveInitialDelayMillis: 1e4
+		});
+		this.#wirePgLifecycle(pool);
+		try {
+			await pool.query("SELECT 1");
+		} catch (e) {
+			this.#unwireAll();
+			await pool.end().catch(() => void 0);
+			throw e;
+		}
+		this.#pgPool = pool;
+		this.#db = pgDrizzle(pool);
+		try {
+			await this.#finishPostgres(entities, pool, pgDrizzle);
+		} catch (e) {
+			this.#unwireAll();
+			await pool.end().catch(() => void 0);
+			this.#pgPool = null;
+			this.#db = null;
+			this.#beginTx = null;
+			throw e;
+		}
+	}
+	/** Suite de la connexion postgres — isolée pour rendre `connect()` atomique. */
+	async #finishPostgres(entities, pool, pgDrizzle) {
+		this.#beginTx = async () => {
+			const cx = await pool.connect();
+			const puitsTx = (err) => {
+				this.connectionLost(`pg (transaction) : ${err?.message ?? String(err)}`);
+			};
+			cx.on("error", puitsTx);
+			/** Rend la connexion, en retirant d'abord NOTRE puits. */
+			const giveBack = (err) => {
+				cx.removeListener("error", puitsTx);
+				cx.release(err === void 0 ? void 0 : err instanceof Error ? err : true);
+			};
+			try {
+				await cx.query("BEGIN");
+			} catch (e) {
+				giveBack(e);
+				throw e;
+			}
+			return new DrizzleTransaction(pgDrizzle(cx), {
+				exec: async (sql) => {
+					await cx.query(sql);
+				},
+				quoteIdent: (name) => `"${name}"`,
+				release: giveBack
+			});
+		};
+		for (const entity of entities) {
+			this.#assertDialectTable(entity, PgTable, "postgres");
+			const table = entity.schema;
+			this.#tables[entity.name] = table;
+			entity.model = table;
+			if (!this.#deriveSchema) continue;
+			await pool.query(this.#createTablePgSQL(table));
+		}
+	}
+	/**
+	* Referme ce qu'un établissement précédent avait ouvert, s'il y en a eu un.
+	* Silencieux et idempotent : au premier `connect()` il n'y a rien à faire.
+	*/
+	async #releasePrevious() {
+		if (!this.#pgPool && !this.#mysqlPool && !this.#client) return;
+		this.#unwireAll();
+		const sink = () => void 0;
+		this.#pgPool?.on("error", sink);
+		try {
+			this.#client?.close();
+			await this.#pgPool?.end();
+			await this.#mysqlPool?.end();
+		} catch {}
+		this.#client = null;
+		this.#pgPool = null;
+		this.#mysqlPool = null;
+	}
+	/** Détache tous les listeners de cycle de vie posés sur les pools natifs. */
+	#unwireAll() {
+		if (!this.#unwire) return;
+		for (const off of this.#unwire) off();
+		this.#unwire = null;
+	}
+	/**
+	* Traduit le cycle de vie du pool **`pg`** en signaux du contrat `orm-core`.
+	*
+	* 🔴 Ce listener n'est pas du confort, il empêche un CRASH. `pg-pool` fait
+	* `pool.emit("error", …)` quand un client **inactif** tombe (serveur
+	* redémarré, coupure réseau, `pg_terminate_backend`) ; un `EventEmitter` qui
+	* émet `error` sans auditeur **lève**, et rien n'installe de
+	* `uncaughtException` dans le framework — le pod tombait. Constaté au banc :
+	* `docker stop` du serveur PostgreSQL ⇒ process mort, code 1.
+	*
+	* Le RETOUR se lit sur `connect` **et** `acquire`. `connect` seul ne suffit
+	* pas : `pg` ne recrée un client que si aucun n'est disponible, donc après
+	* une coupure brève le pool peut reprendre du service en réutilisant un
+	* client sain — sans jamais émettre `connect`, laissant l'ORM marqué tombé
+	* alors que la base répond. `acquire` couvre les deux cas.
+	* `connectionRestored()` étant idempotent, les acquisitions d'un pool en
+	* bonne santé ne comptent rien.
+	*/
+	#wirePgLifecycle(pool) {
+		const onError = (err) => {
+			this.connectionLost(`pg: ${err?.message ?? String(err)}`);
+		};
+		const onConnect = () => {
+			this.connectionRestored();
+		};
+		pool.on("error", onError);
+		pool.on("connect", onConnect);
+		pool.on("acquire", onConnect);
+		(this.#unwire ??= []).push(() => {
+			pool.removeListener("error", onError);
+			pool.removeListener("connect", onConnect);
+			pool.removeListener("acquire", onConnect);
+		});
+	}
+	/**
+	* Traduit le cycle de vie du pool **`mysql2`** en signaux du contrat.
+	*
+	* `mysql2` n'expose PAS d'événement `error` sur le pool : ce sont les
+	* `PoolConnection` qui émettent (elles posent d'ailleurs leur propre
+	* `once("error")` pour se retirer du pool — c'est la seule raison pour
+	* laquelle MySQL ne fait pas tomber le process là où `pg` le fait). On
+	* s'abonne donc à chaque connexion créée ; `connection` sert aussi de
+	* signal de RETOUR, le pool en ouvrant une neuve dès que le serveur répond.
+	*
+	* 🔴 **Mais cet `error` n'arrive PAS quand le serveur tombe.** Mesuré, un
+	* `docker stop` sous une connexion établie : le socket rend `end` puis
+	* `close`, la requête en vol est rejetée en `PROTOCOL_CONNECTION_LOST`
+	* (`fatal: true`) — et la connexion n'émet rien, `mysql2` délivrant l'erreur
+	* fatale au demandeur plutôt qu'à l'émetteur. L'écoute ci-dessus ne couvre
+	* donc que les erreurs survenues connexion INACTIVE ; s'y fier seul laissait
+	* l'ORM marqué connecté jusqu'au battement suivant, quand `pg` bascule
+	* aussitôt par `pool.on("error")`.
+	*
+	* D'où la seconde écoute, sur le **socket** — le seul à parler dans ce cas.
+	* Sa fermeture n'est pas une preuve (une connexion inactive recyclée en
+	* ferme un aussi), donc elle ne conclut rien : elle déclenche un battement
+	* ANTICIPÉ, qui tranche par une requête. Cleanup : `once` se retire en
+	* partant, et le socket meurt avec la connexion qui le porte.
+	*/
+	#wireMysqlLifecycle(pool) {
+		const onConnection = (cx) => {
+			this.connectionRestored();
+			cx.on("error", (err) => {
+				if (this.#mysqlPool !== pool) return;
+				this.connectionLost(`mysql: ${err?.message ?? String(err)}`);
+			});
+			cx.stream?.once("close", () => {
+				if (this.#mysqlPool !== pool) return;
+				this.beatNow();
+			});
+		};
+		const emitter = pool;
+		emitter.on("connection", onConnection);
+		(this.#unwire ??= []).push(() => {
+			emitter.removeListener("connection", onConnection);
+		});
+	}
+	/**
+	* Connexion **MySQL** : le driver `mysql2` (optionalDependency) et l'adapter
+	* `drizzle-orm/mysql2` sont chargés en LAZY (`await import`) — même patron que
+	* `#connectPostgres`. Pool promise ouvert en `timezone: "Z"` : les colonnes
+	* `datetime(3)` (kind `dateMs` du colKit) sont écrites/relues en UTC — mêmes
+	* instants que `timestamptz` PG, sans dépendre de la timezone du serveur.
+	*/
+	async #connectMysql(entities) {
+		if (!this.#url) throw new Error(`DrizzleOrm "${this.name}": dialect "mysql" requires a connection \`url\`.`);
+		let pool;
+		let mysqlDrizzle;
+		try {
+			const mysqlNs = await import("mysql2/promise");
+			const createPool = mysqlNs.createPool ?? mysqlNs.default?.createPool;
+			if (!createPool) throw new Error("`mysql2/promise` did not expose `createPool`");
+			mysqlDrizzle = (await import("drizzle-orm/mysql2")).drizzle;
+			pool = createPool({
+				uri: this.#url,
+				timezone: "Z",
+				enableKeepAlive: true,
+				keepAliveInitialDelay: 1e4
+			});
+			this.#wireMysqlLifecycle(pool);
+		} catch (e) {
+			throw new Error(`DrizzleOrm "${this.name}": the mysql dialect needs the optional driver \`mysql2\` (run \`npm i mysql2\`). ${e.message}`, { cause: e });
+		}
+		try {
+			await pool.query("SELECT 1");
+		} catch (e) {
+			this.#unwireAll();
+			await pool.end().catch(() => void 0);
+			throw e;
+		}
+		this.#mysqlPool = pool;
+		this.#db = mysqlDrizzle(pool);
+		try {
+			await this.#finishMysql(entities, pool, mysqlDrizzle);
+		} catch (e) {
+			this.#unwireAll();
+			await pool.end().catch(() => void 0);
+			this.#mysqlPool = null;
+			this.#db = null;
+			this.#beginTx = null;
+			throw e;
+		}
+	}
+	/** Suite de la connexion mysql — isolée pour rendre `connect()` atomique. */
+	async #finishMysql(entities, pool, mysqlDrizzle) {
+		this.#beginTx = async () => {
+			const cx = await pool.getConnection();
+			try {
+				await cx.query("BEGIN");
+			} catch (e) {
+				cx.destroy();
+				throw e;
+			}
+			return new DrizzleTransaction(mysqlDrizzle(cx), {
+				exec: async (sql) => {
+					await cx.query(sql);
+				},
+				quoteIdent: (name) => `\`${name}\``,
+				release: (err) => {
+					if (err === void 0) cx.release();
+					else cx.destroy();
+				}
+			});
+		};
+		for (const entity of entities) {
+			this.#assertDialectTable(entity, MySqlTable, "mysql");
+			const table = entity.schema;
+			this.#tables[entity.name] = table;
+			entity.model = table;
+			if (!this.#deriveSchema) continue;
+			await pool.query(this.#createTableMysqlSQL(table));
+		}
+	}
+	async disconnect() {
+		this.alive = false;
+		this.stopHeartbeat();
+		this.#unwireAll();
+		const sink = () => void 0;
+		this.#pgPool?.on("error", sink);
+		if (this.#client) this.#client.close();
+		if (this.#pgPool) await this.#pgPool.end();
+		if (this.#mysqlPool) await this.#mysqlPool.end();
+		this.#client = null;
+		this.#pgPool = null;
+		this.#mysqlPool = null;
+		this.#db = null;
+		this.#beginTx = null;
+		this.#sqliteTxGate = null;
+		this.#tables = null;
+		this.#relations = null;
+		this.#repositories = null;
+	}
+	getRepository(name) {
+		const table = this.#tables?.[name];
+		if (!table || !this.#db) throw new Error(`DrizzleOrm "${this.name}": no entity table registered under "${name}".`);
+		if (this.#repositories === null) this.#repositories = Object.create(null);
+		let repository = this.#repositories[name];
+		if (repository === void 0) {
+			repository = new DrizzleRepository(this.#db, table, this.#relations?.[name] ?? {}, this.name, this.#dialect);
+			this.#repositories[name] = repository;
+		}
+		return repository;
+	}
+	/**
+	* 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.
+	*/
+	async transaction(work) {
+		const begin = this.#beginTx;
+		if (!begin) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		const tx = await begin();
+		try {
+			const result = await work(tx);
+			await tx.commit();
+			return result;
+		} catch (error) {
+			await tx.rollback().catch(() => void 0);
+			throw error;
+		}
+	}
+	getNativeConnection() {
+		if (!this.#db) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		return this.#db;
+	}
+	/**
+	* É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.
+	*/
+	async migrationStatus() {
+		if (this.#migrationStatus) return this.#migrationStatus();
+		return failureFrom(this.name, notConfigured(this.name, this.#dialect));
+	}
+	/**
+	* Ce qui S'APPLIQUERAIT, avec son SQL — lecture seule.
+	*
+	* @returns le plan, ou l'empêchement.
+	*/
+	async migrationPlan() {
+		if (this.#migrationPlan) return this.#migrationPlan();
+		return failureFrom(this.name, notConfigured(this.name, this.#dialect));
+	}
+	/**
+	* 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.
+	*/
+	async applyMigrations() {
+		if (this.#applyMigrations) return this.#applyMigrations();
+		return failureFrom(this.name, notConfigured(this.name, this.#dialect));
+	}
+	/**
+	* 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é.
+	*/
+	async ping() {
+		if (this.#pgPool) {
+			await this.#pgPool.query("SELECT 1");
+			return;
+		}
+		if (this.#mysqlPool) {
+			await this.#mysqlPool.query("SELECT 1");
+			return;
+		}
+		if (!this.#client) throw new Error(`DrizzleOrm "${this.name}": not connected.`);
+		this.#client.prepare("SELECT 1").get();
+	}
+	/**
+	* 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.
+	*/
+	async probe() {
+		if (this.#pgPool) return this.#probePgPool(this.#pgPool);
+		if (this.#mysqlPool) return this.#probeMysqlPool(this.#mysqlPool);
+		const client = this.#client;
+		if (!client) return {};
+		try {
+			const num = (sql, key) => {
+				const v = client.prepare(sql).get()?.[key];
+				return typeof v === "number" ? v : void 0;
+			};
+			const str = (sql, key) => {
+				const v = client.prepare(sql).get()?.[key];
+				return typeof v === "string" ? v : void 0;
+			};
+			const pages = num("PRAGMA page_count", "page_count");
+			const pageSize = num("PRAGMA page_size", "page_size");
+			return {
+				storage: {
+					pages,
+					pageSize,
+					sizeBytes: pages !== void 0 && pageSize !== void 0 ? pages * pageSize : void 0,
+					journalMode: str("PRAGMA journal_mode", "journal_mode"),
+					freePages: num("PRAGMA freelist_count", "freelist_count")
+				},
+				extra: { connections: 1 }
+			};
+		} catch {
+			return {};
+		}
+	}
+	/**
+	* Sonde du pool **postgres** — compteurs publics du driver `pg`, lus en
+	* mémoire (aucune requête).
+	*
+	* @param pool - pool `pg` du connecteur.
+	* @returns sonde `pool` (taille max, idle, empruntées, en attente).
+	*/
+	#probePgPool(pool) {
+		const max = pool.options?.max;
+		return { pool: {
+			size: typeof max === "number" ? max : 10,
+			available: pool.idleCount,
+			borrowed: pool.totalCount - pool.idleCount,
+			pending: pool.waitingCount
+		} };
+	}
+	/**
+	* Sonde du pool **mysql** — `mysql2` ne publie AUCUN compteur (contrairement
+	* à `pg`) : seuls des champs internes portent l'état, sous le pool callback
+	* (`promisePool.pool`). Accès défensif (chaque champ narrowé, jamais de cast
+	* aveugle) → un renommage chez `mysql2` rend une sonde PARTIELLE, jamais une
+	* exception ; et le banc de contrat, qui exige ces champs sur les dialectes
+	* serveur, vire au rouge pour le dire.
+	*
+	* @param pool - pool `mysql2/promise` du connecteur.
+	* @returns sonde `pool` (champs omis si le driver ne les expose plus).
+	*/
+	#probeMysqlPool(pool) {
+		const internals = pool.pool;
+		const len = (q) => typeof q?.length === "number" ? q.length : void 0;
+		const all = len(internals?._allConnections);
+		const free = len(internals?._freeConnections);
+		return { pool: {
+			size: internals?.config?.connectionLimit,
+			available: free,
+			borrowed: all !== void 0 && free !== void 0 ? all - free : void 0,
+			pending: len(internals?._connectionQueue)
+		} };
+	}
+	/**
+	* 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) {
+		const table = this.#tables?.[name];
+		if (!table) return [];
+		return (this.#dialect === "postgres" ? getTableConfig$1(table).columns : this.#dialect === "mysql" ? getTableConfig$2(table).columns : getTableConfig(table).columns).map((col) => ({
+			name: col.name,
+			type: col.getSQLType(),
+			primaryKey: col.primary,
+			nullable: !col.notNull,
+			unique: col.isUnique ?? false
+		}));
+	}
+	/**
+	* 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() {
+		const out = [];
+		for (const entity of this.#ownEntities()) {
+			const table = this.#tables?.[entity.name];
+			if (!table) continue;
+			const name = this.#dialect === "postgres" ? getTableConfig$1(table).name : this.#dialect === "mysql" ? getTableConfig$2(table).name : getTableConfig(table).name;
+			out.push({
+				entity: entity.name,
+				table: name,
+				columns: this.describeEntity(entity.name)
+			});
+		}
+		return out;
+	}
+	/**
+	* 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() {
+		if (this.#dialect === "postgres" || this.#dialect === "mysql") return {
+			driver: this.#dialect,
+			target: this.#safeUrlTarget(),
+			ormVersion: DrizzleOrm.#ormVersion()
+		};
+		return {
+			driver: "sqlite",
+			target: this.#safeTarget(),
+			version: this.#sqliteVersion(),
+			ormVersion: DrizzleOrm.#ormVersion()
+		};
+	}
+	/** Cible réseau affichable : `host:port/db`, **sans** user/password (anti-leak). */
+	#safeUrlTarget() {
+		return describeTargetSafely({
+			dialect: this.#dialect,
+			url: this.#url
+		});
+	}
+	/** Version de la lib `drizzle-orm` (résolue + cachée une seule fois). */
+	static #cachedOrmVersion;
+	static #ormVersion() {
+		if (DrizzleOrm.#cachedOrmVersion === void 0) DrizzleOrm.#cachedOrmVersion = DrizzleOrm.#resolvePkgVersion("drizzle-orm") ?? null;
+		return DrizzleOrm.#cachedOrmVersion ?? void 0;
+	}
+	/**
+	* Version d'un package npm via son `package.json` — `createRequire` +
+	* remontée FS. (`require("<pkg>/package.json")` direct échoue souvent :
+	* `exports` ne publie pas toujours `./package.json`.)
+	*/
+	static #resolvePkgVersion(name) {
+		try {
+			const req = createRequire(import.meta.url);
+			let dir = path.dirname(req.resolve(name));
+			for (let i = 0; i < 8; i++) {
+				const pkgPath = path.join(dir, "package.json");
+				if (fs.existsSync(pkgPath)) {
+					const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+					if (pkg.name === name) return pkg.version;
+				}
+				const parent = path.dirname(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		} catch {}
+	}
+	/** Cible affichable : `:memory:` tel quel, sinon chemin relatif au cwd
+	*  (basename si hors projet) — jamais d'absolu (anti info-leak). */
+	#safeTarget() {
+		return describeTargetSafely({
+			dialect: "sqlite",
+			filename: this.#filename
+		});
+	}
+	/** Version du moteur SQLite (`SELECT sqlite_version()`), si connecté. */
+	#sqliteVersion() {
+		if (!this.#client) return void 0;
+		try {
+			return this.#client.prepare("SELECT sqlite_version() AS v").get()?.v;
+		} catch {
+			return;
+		}
+	}
+};
+//#endregion
+export { DrizzleOrm };