@nodefony/orm-core 10.0.0-alpha.1

package/dist/nodefony/src/buildOrmLeanHealth.js

@@ -0,0 +1,54 @@
+import { ormRegistry } from "./OrmRegistry.js";
+import { connectionMonitor } from "./ConnectionMonitor.js";
+import { queryFlowMonitor } from "./QueryFlowMonitor.js";
+//#region nodefony/src/buildOrmLeanHealth.ts
+/**
+* **Santé ORM lean per-instance** — somme process-wide de tous les connecteurs enregistrés,
+* destinée à voyager dans le report de sonde cluster (« ORM par worker »). C'est la fonction
+* branchée par le driver via `setOrmHealthProvider` (core) ; le framework la lit dans le report.
+*
+* Perf (règle ABSOLUE) : lecture PURE des singletons déjà alimentés (`queryFlowMonitor` +
+* `connectionMonitor`) → **0 ping**, **0 `toSQL()`**, O(N connecteurs, N petit). `isConnected()`
+* est un simple test d'état (pas une requête). `queryTotal` reste à 0 si le flux est OFF
+* (prod) — c'est voulu : la sonde ne crée aucun coût, elle agrège ce qui existe déjà.
+*
+* @returns la santé ORM agrégée du process ({@link IOrmLeanHealth}).
+*/
+function buildOrmLeanHealth() {
+	const names = ormRegistry.list();
+	let connected = 0;
+	let assumed = 0;
+	let queryTotal = 0;
+	let slowTotal = 0;
+	let errorTotal = 0;
+	let reconnectTotal = 0;
+	let maxEwmaMs = null;
+	for (const name of names) {
+		try {
+			const orm = ormRegistry.get(name);
+			if (orm.isConnected()) {
+				connected += 1;
+				if (orm.liveness !== "events") assumed += 1;
+			}
+		} catch {}
+		const conn = connectionMonitor.snapshot(name);
+		errorTotal += conn.errorCount;
+		reconnectTotal += conn.reconnectCount;
+		const flow = queryFlowMonitor.snapshot(name, "");
+		queryTotal += flow.total;
+		slowTotal += flow.slowTotal;
+		if (flow.ewmaMs !== null && (maxEwmaMs === null || flow.ewmaMs > maxEwmaMs)) maxEwmaMs = flow.ewmaMs;
+	}
+	return {
+		connectors: names.length,
+		connected,
+		assumed,
+		queryTotal,
+		slowTotal,
+		errorTotal,
+		reconnectTotal,
+		maxEwmaMs
+	};
+}
+//#endregion
+export { buildOrmLeanHealth, buildOrmLeanHealth as default };

package/dist/nodefony/src/criteria.js

@@ -0,0 +1,176 @@
+//#region nodefony/src/criteria.ts
+/**
+* Liste figée des opérateurs riches reconnus dans un critère portable.
+*
+* Source de vérité unique partagée par tous les adapters : un objet de valeur de
+* champ n'est traité comme {@link FieldOperators} que si **toutes** ses clés
+* appartiennent à cette liste (cf {@link isFieldOperators}).
+*/
+const OPERATOR_KEYS = [
+	"$eq",
+	"$ne",
+	"$gt",
+	"$gte",
+	"$lt",
+	"$lte",
+	"$in",
+	"$nin",
+	"$like",
+	"$null"
+];
+const OPERATOR_SET = new Set(OPERATOR_KEYS);
+/**
+* Indique si une valeur de champ est un objet d'{@link FieldOperators}.
+*
+* Heuristique : objet simple, non-`null`, non-tableau, dont **toutes** les clés
+* propres sont des opérateurs reconnus (et au moins une). Une valeur objet
+* « ordinaire » (colonne JSON, sous-document) n'a pas que des clés `$`-préfixées
+* reconnues → elle est traitée comme une égalité, jamais comme un filtre riche.
+*
+* @param value - valeur de critère associée à un champ.
+* @returns `true` si `value` doit être interprétée comme des opérateurs.
+*/
+function isFieldOperators(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return false;
+	for (const key of keys) if (!OPERATOR_SET.has(key)) return false;
+	return true;
+}
+/**
+* Liste figée des opérateurs d'**écriture** reconnus dans le `update` d'un
+* `upsert` (cf {@link UpdateOperators}).
+*
+* Source de vérité unique partagée par tous les adapters — pendant, côté
+* écriture, de {@link OPERATOR_KEYS}.
+*/
+const UPDATE_OPERATOR_KEYS = ["$max", "$min"];
+const UPDATE_OPERATOR_SET = new Set(UPDATE_OPERATOR_KEYS);
+/**
+* Indique si une valeur d'écriture est un objet d'{@link UpdateOperators}.
+*
+* Même heuristique que {@link isFieldOperators} : objet simple, non-`null`,
+* non-tableau, dont **toutes** les clés propres sont des opérateurs d'écriture
+* reconnus (et au moins une). Une valeur objet « ordinaire » (colonne JSON,
+* sous-document) est donc écrite telle quelle, jamais interprétée.
+*
+* @param value - valeur d'écriture associée à un champ.
+* @returns `true` si `value` doit être interprétée comme des opérateurs.
+*/
+function isUpdateOperators(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return false;
+	for (const key of keys) if (!UPDATE_OPERATOR_SET.has(key)) return false;
+	return true;
+}
+/**
+* Le caractère d'échappement des motifs `$like` du contrat portable.
+*
+* Il ne se choisit pas librement : **PostgreSQL et MySQL appliquent déjà `\`**
+* quand aucune clause `ESCAPE` n'est écrite, si bien qu'un motif portant un
+* antislash se comportait DÉJÀ différemment selon le moteur (SQLite, lui, n'a
+* aucun échappement par défaut : il cherchait l'antislash littéral). Fixer `\`
+* et l'émettre explicitement ne change donc pas la sémantique du contrat — cela
+* la fait exister, en alignant les trois moteurs sur celui des deux
+* comportements qui était déjà majoritaire.
+*
+* @see {@link escapeLikeTerm} pour construire un motif, {@link likePatternToRegExp}
+*   pour l'interpréter là où il n'y a pas de SQL (Mongo, mémoire).
+*/
+const LIKE_ESCAPE_CHAR = "\\";
+/**
+* Neutralise les métacaractères d'un **texte** pour l'insérer dans un motif
+* `$like` — `%`, `_` et l'antislash lui-même.
+*
+* À utiliser dès qu'un fragment de motif vient d'un humain ou d'une donnée :
+* sans elle, chercher `50%` demande « 50 suivi de n'importe quoi », et chercher
+* `a_b` ramène `axb`. L'utilisateur ne lit pas ça comme une imprécision, il le
+* lit comme un résultat.
+*
+* L'échappement n'a de valeur que si la clause `ESCAPE` correspondante est
+* ÉMISE : un motif échappé sans elle est cherché littéralement, antislash
+* compris, et ne rend plus rien — en silence. C'est pourquoi les deux vont
+* ensemble et vivent ici, et non chez chaque appelant.
+*
+* @param text - le fragment littéral à insérer dans un motif.
+* @returns le même texte, ses métacaractères neutralisés.
+*
+* @example
+* ```ts
+* { discount: { $like: `${escapeLikeTerm("50%")}%` } }  // → "50\%%"
+* ```
+*/
+function escapeLikeTerm(text) {
+	return text.replace(/[\\%_]/g, (c) => "\\" + c);
+}
+/**
+* Traduit un motif `$like` en expression régulière **ancrée** — pour les stores
+* qui n'ont pas de `LIKE` (MongoDB, implémentations en mémoire).
+*
+* C'est la contrepartie exacte de ce qu'un moteur SQL fait avec
+* `LIKE … ESCAPE '\'` : `%` vaut « n'importe quelle suite », `_` « un
+* caractère », et un caractère précédé de {@link LIKE_ESCAPE_CHAR} vaut
+* lui-même. Sans cette lecture, un adapter documentaire rendrait des résultats
+* différents d'un adapter SQL pour le même critère portable — la divergence la
+* plus coûteuse qui soit, puisqu'elle ne se voit qu'en changeant de backend.
+*
+* Un antislash final sans caractère à échapper est traité comme un antislash
+* littéral, comme le font les moteurs SQL.
+*
+* @param pattern - le motif du contrat (`préfixe%`, `a\_b`…).
+* @returns une `RegExp` ancrée aux deux bouts.
+*/
+function likePatternToRegExp(pattern) {
+	let source = "";
+	for (let i = 0; i < pattern.length; i++) {
+		const c = pattern[i];
+		if (c === "\\" && i + 1 < pattern.length) source += escapeRegExpChar(pattern[++i]);
+		else if (c === "%") source += ".*";
+		else if (c === "_") source += ".";
+		else source += escapeRegExpChar(c);
+	}
+	return new RegExp(`^${source}$`);
+}
+/** Neutralise UN caractère pour l'insérer dans une expression régulière. */
+function escapeRegExpChar(c) {
+	return /[.*+?^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+}
+/**
+* Traduit un terme de recherche `?q=` en critère portable — **la** règle de
+* recherche d'orm-core, en un seul exemplaire.
+*
+* Elle existe parce qu'elle était écrite plusieurs fois, presque à l'identique,
+* dans des stores qui n'avaient aucun test dessus.
+*
+* **Le motif est ANCRÉ À GAUCHE** (`préfixe%`), donc **indexable**. Une
+* recherche `%terme%` interdit tout usage d'index et impose un balayage
+* complet : plus « pratique » sur dix lignes, intenable sur un million. C'est un
+* choix de conception — un besoin de sous-chaîne relève d'un index plein-texte,
+* pas de `LIKE`.
+*
+* Plusieurs champs deviennent un `$or` ; un seul reste un critère plat (les
+* deux formes sont équivalentes pour les adapters, la seconde est plus lisible
+* dans les journaux de requêtes).
+*
+* Le terme est **échappé** ({@link escapeLikeTerm}) : chercher `50%` cherche
+* « 50% », et `a_b` ne ramène pas `axb`. Ça n'a été possible qu'une fois la
+* clause `ESCAPE` émise par la traduction de `$like` — auparavant un terme
+* échappé était cherché littéralement, antislash compris, et ne rendait plus
+* rien du tout, en silence. Les deux gestes sont indissociables : c'est pourquoi
+* ils vivent dans le même fichier.
+*
+* @param q - le terme saisi, déjà trimé par `parsePageQuery`.
+* @param fields - les champs sur lesquels chercher, en noms de propriétés.
+* @returns le critère à fusionner, ou `null` si le terme est vide ou qu'aucun
+*   champ n'est déclaré — l'appelant décide alors quoi faire de `q`.
+*/
+function searchCriteria(q, fields) {
+	const term = q?.trim();
+	if (!term || fields.length === 0) return null;
+	const likePattern = `${escapeLikeTerm(term)}%`;
+	if (fields.length === 1) return { [fields[0]]: { $like: likePattern } };
+	return { $or: fields.map((f) => ({ [f]: { $like: likePattern } })) };
+}
+//#endregion
+export { LIKE_ESCAPE_CHAR, OPERATOR_KEYS, UPDATE_OPERATOR_KEYS, escapeLikeTerm, isFieldOperators, isUpdateOperators, likePatternToRegExp, searchCriteria };

package/dist/nodefony/src/decorators/entitiesDecorator.js

@@ -0,0 +1,67 @@
+import { entityRegistry } from "../EntityRegistry.js";
+//#region nodefony/src/decorators/entitiesDecorator.ts
+/** Connecteur retenu quand ni l'entité ni le décorateur n'en nomment un. */
+const DEFAULT_CONNECTOR = "default";
+/**
+* Déclare les entités qu'un module apporte — l'équivalent de `@controllers([...])`
+* pour la couche données.
+*
+* ```ts
+* @entities([PostEntity, CommentEntity])
+* @controllers([PostController])
+* class Blog extends Module { … }
+* ```
+*
+* **Pourquoi ce décorateur existe** : l'inscription d'une entité est impérative
+* (`entityRegistry.register()`), et il n'y a aucune découverte automatique. Sans lui,
+* une application n'a **aucun endroit** où déclarer ses entités : elle dépend d'un
+* import à effet de bord, où un fichier simplement oublié donne une entité
+* silencieusement absente — l'erreur n'apparaît qu'au premier `getRepository()`, loin
+* de sa cause. Une liste, elle, se lit.
+*
+* **Phase `onRegister`, jamais `onBoot`** (piège) : les connecteurs se branchent à
+* `onBoot` et créent les tables à ce moment-là. Enregistrer les entités à `onBoot`,
+* comme le fait `@controllers`, en ferait une **course** avec le `connect()` : selon
+* l'ordre des écouteurs, la table n'existerait pas. `onRegister` est strictement
+* antérieur — sûr par construction.
+*
+* **Idempotent** : une entité déjà inscrite pour le même connecteur est ignorée (un
+* module peut être instancié deux fois dans un même processus — tests, rechargement).
+* Une **collision réelle** (deux entités différentes, même nom, même connecteur) reste
+* une erreur levée par le registre : c'est un conflit de modèle, pas un doublon bénin.
+*
+* @param list - descripteurs produits par `defineEntity()` (un seul ou un tableau).
+* @param options - connecteur cible commun.
+* @returns le décorateur de classe `Module`.
+*/
+function entities(list, options = {}) {
+	const definitions = Array.isArray(list) ? list : [list];
+	return function(constructor) {
+		class NewConstructorEntities extends constructor {
+			constructor(...args) {
+				super(...args);
+				this.kernel?.once("onRegister", () => {
+					this.initDecoratorEntities();
+				});
+			}
+			/** Inscrit les entités déclarées dans le registre, avant toute connexion ORM. */
+			initDecoratorEntities() {
+				for (const definition of definitions) {
+					const connector = definition.connector ?? options.connector ?? "default";
+					if (entityRegistry.has(definition.name, connector)) {
+						this.log(`ENTITY ${definition.name} (${connector}) déjà enregistrée — ignorée`, "DEBUG");
+						continue;
+					}
+					entityRegistry.register({
+						...definition,
+						connector
+					});
+					this.log(`ADD ENTITY : ${definition.name} (connector ${connector})`, "DEBUG");
+				}
+			}
+		}
+		return NewConstructorEntities;
+	};
+}
+//#endregion
+export { DEFAULT_CONNECTOR, entities };

package/dist/nodefony/src/decorators/entityDecorator.js

@@ -0,0 +1,51 @@
+import { entityRegistry } from "../EntityRegistry.js";
+import { setEntityMeta } from "./metadataStore.js";
+//#region nodefony/src/decorators/entityDecorator.ts
+/**
+* Décore une classe comme entité multi-ORM et l'enregistre au chargement.
+*
+* Résout le piège d'ordre d'initialisation TS (le constructeur de base
+* s'exécute avant les initialiseurs de champs de la sous-classe) : le décorateur
+* s'exécute sur la **classe** au chargement du module, donc `name`/`connector`
+* sont connus sans instance. Il construit un **descripteur {@link IEntity} depuis
+* les options** (aucune instanciation au boot), l'enregistre dans le
+* `entityRegistry` process-wide, et stocke la métadonnée via un `WeakMap`
+* (cf. `metadataStore`, sans `reflect-metadata`).
+*
+* @param options - connecteur cible + nom/schéma/relations optionnels.
+* @returns le décorateur de classe (renvoie la classe inchangée).
+* @throws si une entité de même `name` est déjà enregistrée sur le même `connector`.
+*
+* @example
+* ```ts
+* \@entity({ connector: "db_principale", schema: { id: { type: "uuid" } } })
+* class User extends Entity { ... }
+* ```
+*/
+function entity(options) {
+	return (target) => {
+		const name = options.name ?? target.name;
+		const meta = {
+			name,
+			connector: options.connector,
+			module: options.module,
+			domain: options.domain,
+			schema: options.schema,
+			relations: options.relations,
+			target
+		};
+		setEntityMeta(target, meta);
+		const descriptor = {
+			name,
+			connector: options.connector,
+			module: options.module,
+			domain: options.domain,
+			schema: options.schema,
+			relations: options.relations
+		};
+		entityRegistry.register(descriptor);
+		return target;
+	};
+}
+//#endregion
+export { entity };

package/dist/nodefony/src/decorators/index.js

@@ -0,0 +1,5 @@
+import { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta } from "./metadataStore.js";
+import { entity } from "./entityDecorator.js";
+import { DEFAULT_CONNECTOR, entities } from "./entitiesDecorator.js";
+import { repository } from "./repositoryDecorator.js";
+export { DEFAULT_CONNECTOR, entities, entity, getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, repository };

package/dist/nodefony/src/decorators/metadataStore.js

@@ -0,0 +1,38 @@
+//#region nodefony/src/decorators/metadataStore.ts
+/**
+* Stockage des métadonnées de décorateurs SANS `reflect-metadata`.
+*
+* orm-core est une lib pure : aucune dépendance runtime hors `nodefony`. Les
+* décorateurs `@entity`/`@repository` ne lisent jamais les types émis par TS
+* (`design:paramtypes`), donc un `WeakMap<classe, métadonnée>` process-wide
+* suffit — clé = constructeur, GC-friendly (pas de fuite si la classe est
+* déréférencée). Aucun polyfill Reflect requis.
+*/
+const ENTITY_META = /* @__PURE__ */ new WeakMap();
+const REPOSITORY_META = /* @__PURE__ */ new WeakMap();
+/** Enregistre la métadonnée `@entity` d'une classe. */
+function setEntityMeta(target, meta) {
+	ENTITY_META.set(target, meta);
+}
+/** Récupère la métadonnée `@entity` d'une classe, ou `undefined`. */
+function getEntityMeta(target) {
+	return ENTITY_META.get(target);
+}
+/** Indique si une classe porte une métadonnée `@entity`. */
+function hasEntityMeta(target) {
+	return ENTITY_META.has(target);
+}
+/** Enregistre la métadonnée `@repository` d'une classe. */
+function setRepositoryMeta(target, meta) {
+	REPOSITORY_META.set(target, meta);
+}
+/** Récupère la métadonnée `@repository` d'une classe, ou `undefined`. */
+function getRepositoryMeta(target) {
+	return REPOSITORY_META.get(target);
+}
+/** Indique si une classe porte une métadonnée `@repository`. */
+function hasRepositoryMeta(target) {
+	return REPOSITORY_META.has(target);
+}
+//#endregion
+export { getEntityMeta, getRepositoryMeta, hasEntityMeta, hasRepositoryMeta, setEntityMeta, setRepositoryMeta };

package/dist/nodefony/src/decorators/repositoryDecorator.js

@@ -0,0 +1,35 @@
+import { setRepositoryMeta } from "./metadataStore.js";
+//#region nodefony/src/decorators/repositoryDecorator.ts
+/**
+* Décore une classe comme repository d'une entité (tag métadonnée pur).
+*
+* Stocke le lien repo↔entity dans un `WeakMap` (cf. `metadataStore`, sans
+* `reflect-metadata`). N'enregistre RIEN dans un registre en P5.3 : le binding
+* DI (`@Inject('repository.user.db_principale')`) est câblé par l'adapter ORM
+* concret (P5.4+), qui scanne ces métadonnées. Coût uniquement au chargement
+* du module — jamais par requête.
+*
+* @param name - nom logique du repository (clé DI, ex. `"repository.user"`).
+* @param options - entité gérée + connecteur cible optionnel.
+* @returns le décorateur de classe (renvoie la classe inchangée).
+*
+* @example
+* ```ts
+* \@repository("repository.user", { entity: "User", connector: "db_principale" })
+* class UserRepository implements IRepository<User> { ... }
+* ```
+*/
+function repository(name, options) {
+	return (target) => {
+		const meta = {
+			name,
+			entity: options.entity,
+			connector: options.connector,
+			target
+		};
+		setRepositoryMeta(target, meta);
+		return target;
+	};
+}
+//#endregion
+export { repository };

package/dist/nodefony/src/defineEntity.js

@@ -0,0 +1,27 @@
+//#region nodefony/src/defineEntity.ts
+/**
+* Déclare une entité applicative. Fonction d'**identité typée** : elle ne fait
+* qu'attacher le type — aucun effet de bord, aucun enregistrement.
+*
+* L'enregistrement est le rôle du décorateur `entities([...])` posé sur le Module,
+* qui s'exécute à la phase `onRegister` (avant que l'ORM ne se connecte). Séparer
+* les deux permet d'importer une entité (dans un test, un script, un autre module)
+* sans déclencher son inscription dans un registre global.
+*
+* @example
+* ```ts
+* export const PostEntity = defineEntity({
+*   name: "Post",
+*   module: "blog",
+*   schema: postTable,     // table Drizzle native (ou SchemaDefinition Mongoose)
+* });
+* ```
+*
+* @param definition - descripteur (nom logique, schéma natif, module, relations…).
+* @returns le descripteur, tel quel.
+*/
+function defineEntity(definition) {
+	return definition;
+}
+//#endregion
+export { defineEntity };

package/dist/nodefony/src/errors.js

@@ -0,0 +1,76 @@
+//#region nodefony/src/errors.ts
+/**
+* Erreurs typées du socle ORM — **data-level uniquement** (aucun couplage à une
+* couche API/transport : ces erreurs décrivent des fautes sur les données, pas
+* sur une requête HTTP/GraphQL). Une surface API qui les rencontre décide
+* elle-même comment les projeter (400, erreur GraphQL…), l'ORM n'en sait rien.
+*/
+/**
+* Levée quand un critère de repository référence un **champ inconnu** de l'entité
+* ciblée.
+*
+* Garde-fou « ultra solide » + **portabilité** : sans elle, un champ inconnu est
+* traité différemment selon l'adapter — Drizzle l'**ignore** (la condition
+* disparaît → la requête peut renvoyer **toute** la table), Mongoose le **garde**
+* (→ **0 résultat**). Le même critère mal typé donnerait donc des résultats
+* opposés selon l'ORM (rupture de la promesse « swap d'ORM ») et une faute de
+* frappe (`emial`) passerait silencieusement. On échoue **tôt et pareil** sur les
+* deux drivers.
+*
+* Les requêtes natives/calculées (opérateurs logiques `$or`, sous-requêtes…) ne
+* relèvent **pas** du critère portable : passer par `IOrm.getNativeConnection()`.
+*/
+var UnknownCriteriaField = class extends Error {
+	/** Champ fautif (clé du critère non résolue sur l'entité). */
+	field;
+	/** Nom logique de l'entité ciblée. */
+	entity;
+	/** Champs connus de l'entité (aide au diagnostic / faute de frappe). */
+	known;
+	/**
+	* @param field - champ inconnu rencontré dans le critère.
+	* @param entity - entité ciblée (nom logique).
+	* @param known - champs connus de l'entité.
+	*/
+	constructor(field, entity, known) {
+		super(`Unknown criteria field "${field}" on entity "${entity}". Known fields: ${known.join(", ")}. For native/computed queries (logical $or, sub-queries…), use getNativeConnection().`);
+		this.name = "UnknownCriteriaField";
+		this.field = field;
+		this.entity = entity;
+		this.known = known;
+	}
+};
+/**
+* Levée quand l'option de lecture `order` n'est pas un tableau de couples
+* `[champ, "ASC" | "DESC"]`.
+*
+* Symétrique de {@link UnknownCriteriaField}, sous la même règle « jamais un skip
+* silencieux » : avant cette garde, une forme voisine mais fausse — `{ age: "asc" }`
+* au lieu de `[["age", "ASC"]]` — faisait partir la requête **sans `ORDER BY`**, et
+* l'appelant recevait des lignes non triées qu'il croyait triées. Le sens est vérifié
+* en casse exacte : un `"desc"` minuscule aurait produit un tri **ASC**, soit
+* l'inverse de l'intention.
+*
+* TypeScript attrape déjà le cas au typage ; la surface réelle est l'appel non typé
+* ou construit dynamiquement — exactement là où un tri faux ne se voit pas. La
+* normalisation d'une entrée utilisateur (casse, `champ:sens`) appartient à la
+* frontière qui la reçoit (`parsePageQuery`), jamais au repository.
+*/
+var InvalidOrderOption = class extends Error {
+	/** Nom logique de l'entité ciblée. */
+	entity;
+	/** Ce qui a été reçu, décrit par sa FORME (jamais la valeur : pas de fuite de données). */
+	received;
+	/**
+	* @param entity - entité ciblée (nom logique).
+	* @param received - description de la forme reçue (ex. `an object`, `pair #0 is not an array`).
+	*/
+	constructor(entity, received) {
+		super(`Invalid "order" option on entity "${entity}": expected an array of [field, "ASC" | "DESC"] pairs, received ${received}. Example: { order: [["createdAt", "DESC"]] }.`);
+		this.name = "InvalidOrderOption";
+		this.entity = entity;
+		this.received = received;
+	}
+};
+//#endregion
+export { InvalidOrderOption, UnknownCriteriaField };

package/dist/nodefony/src/ormWiring.js

@@ -0,0 +1,78 @@
+import { ormRegistry } from "./OrmRegistry.js";
+import { buildConnectionHealth, buildOrmFlow, registerOrmAdminApi } from "./OrmAdminApi.js";
+import { buildOrmLeanHealth } from "./buildOrmLeanHealth.js";
+import { setOrmHealthProvider, setOrmRichProvider } from "nodefony";
+//#region nodefony/src/ormWiring.ts
+/**
+* Branche le « plan d'administration » ORM dans le kernel — montage **idempotent**
+* appelé par CHAQUE driver à son `onKernelBoot`. Factorise la dette C5 : le bloc
+* était jusqu'ici recopié à l'identique dans chaque module driver (Drizzle,
+* Mongoose), donc voué à diverger ; il vit désormais à un seul endroit.
+*
+* Trois branchements, tous **GLOBAUX** (ils itèrent `ormRegistry`) → couvrent
+* TOUS les ORM enregistrés, peu importe le driver appelant ; idempotents
+* (« dernier gagne ») → sûr d'être invoqué par N drivers :
+*  1. `registerOrmAdminApi` (si un broker admin est présent) — monte les routes
+*     data plane `/nodefony/orm/api/*` ;
+*  2. `setOrmHealthProvider` — santé ORM lean dans la sonde cluster (par worker) ;
+*  3. `setOrmRichProvider` — diagnostic riche (connexion + flux) pour le drill Studio.
+*
+* Les seams `setOrm*Provider` matérialisent l'inversion de dépendance : le core
+* expose la prise, orm-core fournit l'implémentation agnostique
+* (0 dépendance `framework` → `orm-core`).
+*
+* @param kernel - kernel courant (`this.kernel` du module driver), ou nullish.
+*/
+function wireOrmAdminPlane(kernel) {
+	const broker = kernel?.container?.get("adminBroker");
+	if (broker) registerOrmAdminApi(broker);
+	setOrmHealthProvider(buildOrmLeanHealth);
+	setOrmRichProvider(async () => ({
+		health: await buildConnectionHealth(),
+		flow: buildOrmFlow()
+	}));
+	kernel?.once?.("onServersReady", () => reportOrmBootLines(kernel));
+}
+/**
+* Pousse dans le BootReporter une ligne par ORM enregistré (« nom → driver
+* (cible) ») pour que la phase de boot « Services & ORM » RACONTE les connexions
+* mises en place, au lieu d'une phase muette. Idempotent : reconstruit la liste
+* complète depuis le registre et REMPLACE (sûr d'être appelé par N drivers).
+*
+* `describeConnection()` ne révèle JAMAIS de credential (redaction côté adapter).
+* Le libellé « Services & ORM » doit matcher une phase du `BootReporter` (core).
+*
+* @param kernel - kernel courant (`this.kernel` du module driver), ou nullish.
+*/
+function reportOrmBootLines(kernel) {
+	if (!kernel) return;
+	const lines = [];
+	for (const name of ormRegistry.list()) try {
+		const orm = ormRegistry.get(name);
+		const info = orm.describeConnection?.();
+		if (!info) continue;
+		const target = info.target ? ` ${info.target}` : "";
+		const state = orm.isConnected() ? "" : " (non connecté)";
+		lines.push(`${name} → ${info.driver}${target}${state}`);
+	} catch {}
+	kernel.setBootLines("Services & ORM", lines);
+}
+/**
+* Détermine si la sonde de flux ORM (`queryFlowMonitor`) doit être active :
+* **OFF en production** (coût nul sur le hot path des requêtes), **ON sinon**
+* (observabilité dev / Supervision). Override explicite par la variable
+* d'environnement `NF_ORM_FLOW` (`1`/`true` = forcer ON).
+*
+* Factorise le calcul recopié à l'identique dans chaque `*Service.onBoot` (le
+* pendant « flux » de {@link wireOrmAdminPlane}, gardé distinct car il s'exécute
+* dans le Service, pas le Module, et porte une responsabilité différente).
+*
+* @param kernel - kernel courant (pour lire l'environnement d'exécution).
+* @returns `true` si la sonde de flux doit être activée.
+*/
+function resolveOrmFlowEnabled(kernel) {
+	const flag = process.env.NF_ORM_FLOW;
+	return flag !== void 0 ? flag === "1" || flag === "true" : kernel?.environment !== "production";
+}
+//#endregion
+export { reportOrmBootLines, resolveOrmFlowEnabled, wireOrmAdminPlane };

package/dist/nodefony/src/paginate.js

@@ -0,0 +1,55 @@
+import { searchCriteria } from "./criteria.js";
+import { PageQueryError } from "nodefony";
+//#region nodefony/src/paginate.ts
+/**
+* Pagine un {@link IRepository} de façon **portable** — au-dessus des primitives
+* natives `find(criteria, { limit, offset, order })` et `count(criteria)` que tout
+* adapter implémente déjà (SQL `LIMIT/OFFSET`+`COUNT`, Mongo `skip/limit`+
+* `countDocuments`…). Aucun adapter n'a à changer : un seul aller vers la page,
+* jamais de matérialisation de toute la collection.
+*
+* `hasNext` est obtenu **sans `COUNT`** par l'astuce `limit + 1` : on demande une
+* ligne de plus que la page ; si elle arrive, il y a une suite (on la retire du
+* résultat). Le `COUNT(*)` — coûteux sur les grosses tables — n'est payé que si
+* `withTotal` n'est pas `false` (mode « Page » vs « Slice », cf Spring Data).
+*
+* La **recherche** `?q=` n'est honorée que si l'appelant déclare où chercher
+* ({@link IPaginateOptions.searchable}) ; sans cela elle est refusée en `400`.
+*
+* @typeParam T - type de l'entité paginée.
+* @param repo - le repository à paginer.
+* @param page - la requête de page ({@link PageQuery}).
+* @param options - capacités de ce point d'entrée (recherche).
+* @returns une {@link Page} : au plus `limit` items, `hasNext`, et `total` si demandé.
+* @throws {@link PageQueryError} (`400`) si un `q` est reçu sans champ
+*   cherchable déclaré, ou si le critère porte déjà un `$or`.
+*/
+async function paginate(repo, page, options = {}) {
+	const limit = Math.max(1, Math.floor(page.limit));
+	const offset = Math.max(0, Math.floor(page.offset ?? 0));
+	const withTotal = page.withTotal ?? true;
+	let criteria = page.criteria;
+	const search = searchCriteria(page.q, options.searchable ?? []);
+	if (search) {
+		if (criteria && "$or" in criteria) throw new PageQueryError("Cannot combine full-text search with a criteria that already uses \"$or\" (the grammar has no \"$and\" to nest them). Search on a single field, or build the criteria in the caller.");
+		criteria = {
+			...criteria,
+			...search
+		};
+	} else if (page.q?.trim()) throw new PageQueryError("This endpoint does not support full-text search (\"q\"): no searchable field is declared. Pass { searchable: [...] } to paginate(), or drop \"q\".");
+	const rows = await repo.find(criteria, {
+		limit: limit + 1,
+		offset,
+		order: page.order
+	});
+	const hasNext = rows.length > limit;
+	return {
+		items: hasNext ? rows.slice(0, limit) : rows,
+		limit,
+		offset,
+		hasNext,
+		total: withTotal ? await repo.count(criteria) : void 0
+	};
+}
+//#endregion
+export { paginate };