nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/kernel/decorators/kernelDecorator.d.ts

@@ -0,0 +1,76 @@
+import "reflect-metadata";
+import Module from "../Module.js";
+import { ServiceConstructor } from "../Kernel.js";
+import Service from "../../Service.js";
+import { InjectableOptions } from "../injector/injector.js";
+type Constructor = new (...args: any[]) => Module<unknown>;
+type Injectable<T = {
+    service: Service;
+}> = new (...args: any[]) => T;
+/**
+ * Déclare les services qu'un module enregistre dans son conteneur au démarrage.
+ *
+ * Décorateur de **classe de module**. Les services sont instanciés au hook
+ * `onPreBoot`, et **l'ordre écrit ici n'a aucune importance** : il est recalculé
+ * depuis les dépendances déclarées (`@inject`), de sorte qu'un service réclamé
+ * soit présent avant son consommateur. Le hook est tagué au nom du module : un
+ * service qui échoue suit la politique de criticité de SON module — fatal en
+ * production, dégradation annoncée ailleurs — au lieu de faire tomber le boot
+ * anonymement.
+ *
+ * @param nameOrPath - Une classe de service, un chemin de fichier, ou un tableau
+ *   mêlant les deux.
+ * @returns Le décorateur de classe, qui renvoie le module enrichi du hook.
+ * @example
+ * ```typescript
+ * @services([Router, Eta, AdminBroker])
+ * class FrameworkModule extends Module {}
+ * ```
+ */
+declare function services(nameOrPath: string | (string | ServiceConstructor)[] | ServiceConstructor): <T extends Constructor>(constructor: T) => T;
+/**
+ * Rend une classe de service résoluble par le conteneur d'injection.
+ *
+ * Décorateur de **classe**. Il inscrit la classe à l'annuaire d'injection sous
+ * un nom — celui de la classe par défaut — et fige sa portée. Sans lui, la
+ * classe reste une classe ordinaire : elle ne peut être ni découverte, ni
+ * injectée, et un `@inject("…")` qui la réclame échouera à la résolution.
+ *
+ * @param nameOrOptions - Le nom d'enregistrement, ou `{ name?, scope? }`. La
+ *   portée vaut `"singleton"` par défaut — une seule instance pour le
+ *   processus ; `"transient"` en fabrique une par résolution.
+ * @returns Le décorateur de classe, qui renvoie la classe inchangée.
+ * @example
+ * ```typescript
+ * @injectable()
+ * class Router extends Service {}
+ *
+ * @injectable({ name: "pdfRenderer", scope: "transient" })
+ * class PdfRenderer extends Service {}
+ * ```
+ */
+declare function injectable(nameOrOptions?: string | InjectableOptions): <T extends Injectable<Service>>(constructor: T) => T;
+/**
+ * Injecter une Service avec son nom dans le constructeur.
+ *
+ * @param serviceName - Le nom du service à injecter (doit correspondre à un @injectable)
+ *
+ * @example
+ *  class MyService extends Service {
+ *    constructor(@inject("Fetch") private fetch: Fetch) { super("my", ...) }
+ *  }
+ */
+declare function inject(serviceName: string): ParameterDecorator;
+/**
+ * Injecter une Service sur une propriété de classe (property injection).
+ * Distinct de @inject (minuscule) qui cible les paramètres de constructeur.
+ *
+ * Le nom est obligatoire si emitDecoratorMetadata n'est pas actif (tests tsx).
+ *
+ * @example
+ *  class MyService extends Service {
+ *    @Inject("Fetch") private fetch!: Fetch;
+ *  }
+ */
+declare function Inject(name?: string): PropertyDecorator;
+export { injectable, inject, Inject, services };

package/dist/types/kernel/injector/injector.d.ts

@@ -0,0 +1,47 @@
+import "reflect-metadata";
+import Service from "../../Service.js";
+import Kernel, { ServiceConstructor } from "../Kernel.js";
+export type DIScope = "singleton" | "transient";
+export interface InjectableOptions {
+    name?: string;
+    scope?: DIScope;
+}
+export interface PropertyInjectMeta {
+    key: string | symbol;
+    name: string;
+}
+declare class Injector extends Service {
+    static injectables: Record<string, ServiceConstructor>;
+    constructor(kernel: Kernel);
+    static register(serviceName: string, service: ServiceConstructor): ServiceConstructor;
+    static isRegistered(serviceName: string): boolean;
+    /**
+     * Mémorise la clé sous laquelle une classe de service vit RÉELLEMENT dans le
+     * container — apprise au moment où l'instance y est posée.
+     *
+     * @remarks Sans elle, `@inject("Router")` interrogeait le container avec
+     *   `"Router"` alors que l'instance y est rangée sous `"router"` (le nom de son
+     *   `super()`) : le container répondait `null` et le service était RECONSTRUIT,
+     *   son cache vide, silencieusement. Un seul des 7 `@injectable` échappait au
+     *   piège — `HttpKernel`, par coïncidence de casse.
+     *
+     * @param service - le constructeur, tel qu'enregistré par `@injectable`.
+     * @param containerKey - `instance.name`, la clé réelle du container.
+     */
+    static rememberContainerKey(service: ServiceConstructor, containerKey: string): void;
+    /**
+     * Clé container connue d'une classe de service, ou `null` si elle n'a jamais
+     * été posée au container (rien à apprendre encore).
+     */
+    static containerKeyOf(service: ServiceConstructor): string | null;
+    static getScope(serviceName: string): DIScope;
+    static get(serviceName: string): ServiceConstructor;
+    static inject<T extends Service = Service>(service: ServiceConstructor, ...args: unknown[]): T;
+    instantiate<T extends Service = Service>(constructor: ServiceConstructor, ...args: unknown[]): T;
+    static instantiate<T extends Service = Service>(constructor: ServiceConstructor, ...argsClass: unknown[]): T;
+    private static _resolveWithStack;
+    private static _applyPropertyInjection;
+    private static _instantiateWithStack;
+    reflect<T extends Service = Service>(constructor: ServiceConstructor, ...args: unknown[]): T;
+}
+export default Injector;

package/dist/types/kernel/injector/serviceOrder.d.ts

@@ -0,0 +1,29 @@
+import "reflect-metadata";
+import type { ServiceConstructor } from "../Kernel.js";
+/** Entrée d'un `@services([...])` : un constructeur, ou un chemin à charger. */
+export type ServiceEntry = string | ServiceConstructor;
+/**
+ * Réordonne les services d'un `@services([...])` selon leurs dépendances
+ * **déclarées**, pour que l'ordre d'écriture cesse de compter.
+ *
+ * `@services` instancie séquentiellement et pose chaque instance au container :
+ * un service réclamé par un autre doit donc exister AVANT lui, sinon le DI le
+ * reconstruit sans argument et son constructeur casse. Faire reposer ça sur
+ * l'ordre d'une liste écrite à la main est un piège : déplacer `HttpKernel` de
+ * trois lignes dans `@nodefony/http` suffisait à rendre 499 sur chaque requête.
+ * Les dépendances étant déjà déclarées (`@inject` / `design:paramtypes`), l'ordre
+ * correct se **calcule** — c'est ce que font Symfony (container compilé) et
+ * NestJS (résolution du graphe).
+ *
+ * Tri topologique **stable** : à contrainte égale, l'ordre d'écriture est
+ * conservé — un `@services` déjà correct sort inchangé.
+ *
+ * Ne touche pas aux entrées dont les dépendances sont inconnaissables sans les
+ * charger (chemins `string`) ni aux constructeurs hors registre : elles gardent
+ * leur position relative.
+ *
+ * @param entries - la liste telle qu'écrite dans `@services([...])`.
+ * @returns la même liste, réordonnée ; jamais une entrée perdue ou dupliquée.
+ * @throws Si les dépendances déclarées forment un cycle (message nommant le cycle).
+ */
+export declare function orderServicesByDependencies(entries: readonly ServiceEntry[]): ServiceEntry[];

package/dist/types/kernel/inspect/adminSubjects.d.ts

@@ -0,0 +1,169 @@
+import type { AdminHttpMethod, IAdminApi } from "../../types/IAdminApi.js";
+import type { IAdminCaller } from "../adminPlane/adminCaller.js";
+/**
+ * Ce qu'un sujet inspectable désigne : où le lire dans le plan d'administration.
+ */
+export interface IInspectSubject {
+    /** Producteur d'administration (`kernel`, `framework`, `orm`…). */
+    namespace: string;
+    /** Chemin de l'endpoint, tel que le producteur le déclare. */
+    path: string;
+    /** Ce que le sujet montre, en une ligne. */
+    summary: string;
+    /** Nom du paramètre attendu, quand le chemin en porte un (`module/{name}`). */
+    param?: string;
+}
+/**
+ * Sujets inspectables, et l'endpoint d'administration qui les sert.
+ *
+ * **Aucune donnée n'est calculée ici.** Chaque sujet pointe le producteur qui
+ * répond déjà en HTTP : toutes les portes rendent le même objet, parce que
+ * c'est le même code qui le produit. Une table de correspondance peut se
+ * périmer ; une réimplémentation, elle, diverge en silence — et c'est la porte
+ * secondaire qu'on croirait sur parole.
+ *
+ * ⚠️ Cette table est la SOURCE UNIQUE des sujets. La commande `inspect`, le
+ * serveur MCP et toute porte future la lisent ici — aucune n'en tient une
+ * copie.
+ */
+export declare const INSPECT_SUBJECTS: Record<string, IInspectSubject>;
+/**
+ * Extrait la donnée d'une réponse d'administration.
+ *
+ * Un handler rend soit la donnée, soit une enveloppe `{status, body}` (pour
+ * porter un 404). Même discrimination que le pont HTTP : enveloppe **si et
+ * seulement si** `body` est présent AVEC `status` ou `headers` — un objet
+ * métier qui posséderait un champ `body` n'est pas une enveloppe.
+ */
+export declare function unwrapAdminResult(result: unknown): {
+    status: number;
+    data: unknown;
+};
+/** Pourquoi une lecture de sujet n'a pas abouti — chaque porte le traduit. */
+export type InspectFailure = 
+/** Le sujet demandé n'est pas dans {@link INSPECT_SUBJECTS}. */
+"unknown-subject"
+/** Le sujet exige un paramètre qui n'a pas été fourni. */
+ | "missing-target"
+/** Le module qui sert ce sujet n'est pas chargé dans cette application. */
+ | "producer-missing"
+/** Le producteur existe mais ne déclare pas cet endpoint (version ?). */
+ | "endpoint-missing"
+/** Le handler a levé. */
+ | "handler-failed"
+/** Le handler a répondu un statut d'erreur (404 sur une cible inconnue). */
+ | "not-found"
+/**
+ * L'appelant n'a pas le rôle exigé par l'endpoint.
+ *
+ * Distinct de `not-found` : confondre « tu n'as pas le droit » avec « ça
+ * n'existe pas » envoie chercher une cible valide au lieu d'un jeton.
+ */
+ | "forbidden";
+/** Résultat d'une lecture de sujet : la donnée, ou la raison de l'échec. */
+export type InspectResult = {
+    ok: true;
+    status: number;
+    data: unknown;
+} | {
+    ok: false;
+    reason: InspectFailure;
+    message: string;
+    status?: number;
+    /**
+     * Le corps que le PRODUCTEUR a préparé pour ce refus, quand il en a
+     * préparé un — le plan d'une page dont la section demandée n'existe pas,
+     * la liste des valeurs acceptées, le nom du champ fautif.
+     *
+     * ⚠️ Ce champ a été ajouté parce que son absence faisait conclure
+     * l'inverse de la vérité : un refus « section inconnue » (la page existe,
+     * son plan est joint) arrivait à l'appelant sous la forme « introuvable
+     * (404) », et un agent en déduisait que la PAGE n'existait pas. Une porte
+     * qui résume un refus lui fait dire autre chose.
+     */
+    body?: unknown;
+    /**
+     * Message de l'exception, quand le handler a LEVÉ — réservé à un
+     * appelant local.
+     *
+     * 🔴 **Il ne traverse aucune porte distante.** Le transport HTTP rend
+     * « Internal admin handler error » et rien d'autre : le message d'une
+     * exception porte ce que le code avait sous la main au moment de
+     * l'échec — un chemin de disque, une requête, une valeur de
+     * configuration. Le recopier dans {@link InspectResult.message} faisait
+     * fuir par la porte MCP ce que la porte HTTP masque, sur exactement les
+     * mêmes handlers. Une porte qui en dit plus qu'une autre sur la même
+     * donnée est une faille, pas une commodité.
+     *
+     * L'opérateur qui lance une commande sur sa propre machine, lui, peut le
+     * lire : il possède déjà le processus et ses journaux.
+     */
+    cause?: string;
+};
+/** Vue minimale du broker dont cette lecture a besoin. */
+export interface IAdminBrokerLike {
+    list(): readonly IAdminApi[];
+}
+/** Ce qu'il faut pour joindre un endpoint du plan d'administration. */
+export interface IAdminCall {
+    /** Producteur d'administration (`kernel`, `framework`, `orm`…). */
+    namespace: string;
+    /** Chemin de l'endpoint, tel que le producteur le déclare. */
+    path: string;
+    /**
+     * Méthode de l'endpoint visé, défaut `"GET"`.
+     *
+     * ⚠️ **Elle fait partie de l'identité d'un endpoint, pas de son décor** : huit
+     * chemins du plan portent deux ou trois méthodes (`webhooks` en GET et POST,
+     * `users/{id}` en GET, PATCH et DELETE, `recent` en GET et DELETE). Résoudre
+     * par le seul chemin rendait le PREMIER déclaré — une lecture aujourd'hui, par
+     * chance, et une suppression le jour où un producteur réordonne son tableau.
+     */
+    method?: AdminHttpMethod;
+    /** Variables de route, quand le chemin en porte (`module/{name}`). */
+    params?: Readonly<Record<string, string>>;
+    /** Paramètres de requête, tels qu'une URL les porterait. */
+    query?: Readonly<Record<string, string | string[]>>;
+    /** Ce qu'on nomme dans les messages d'échec — le sujet, la cible, l'appel. */
+    label?: string;
+}
+/**
+ * Appelle un endpoint du plan d'administration, hors HTTP.
+ *
+ * ⭐ **Une source, plusieurs portes** : cette fonction ne fait que RÉSOUDRE
+ * l'endpoint (par producteur et chemin, là où la route HTTP le résout par nom
+ * de route), puis délègue à {@link ../adminPlane/executeAdmin.executeAdminEndpoint} —
+ * la même exécution que le transport HTTP. Autorisation, normalisation du
+ * retour et traduction des erreurs sont donc identiques par CONSTRUCTION, et
+ * non par vigilance.
+ *
+ * Ce que la version précédente perdait : elle appelait le handler directement
+ * et ne gardait, d'un statut d'erreur, que le nombre. Le corps préparé par le
+ * producteur — le plan d'une page, les valeurs acceptées — disparaissait, et
+ * l'appelant concluait l'inverse de la vérité. Il voyage désormais entier
+ * ({@link InspectResult}`.body`).
+ *
+ * Le rôle d'administrateur est **annoncé**, pas contourné : certains
+ * producteurs graduent leur réponse selon les rôles, et un appelant qui se
+ * présenterait en anonyme obtiendrait une vue amputée — il mentirait par
+ * omission face à la même donnée lue en HTTP. Le contrôle d'accès du plan
+ * d'administration protège le RÉSEAU ; la redaction des secrets, elle, vit dans
+ * les producteurs et s'applique donc à toutes les portes.
+ *
+ * @param broker - le service `adminBroker` du conteneur
+ * @param call - producteur, chemin, et ce qu'on lui passe
+ * @returns la donnée du producteur, ou la raison précise de l'échec
+ */
+export declare function callAdminEndpoint(broker: IAdminBrokerLike | undefined, call: IAdminCall, caller: IAdminCaller): Promise<InspectResult>;
+/**
+ * Lit un sujet d'inspection dans le plan d'administration.
+ *
+ * Résout le sujet dans {@link INSPECT_SUBJECTS}, puis délègue à
+ * {@link callAdminEndpoint} — ce qui vaut pour l'appel vaut donc ici.
+ *
+ * @param broker - le service `adminBroker` du conteneur
+ * @param subject - clé de {@link INSPECT_SUBJECTS}
+ * @param target - valeur du paramètre, pour les sujets qui en portent un
+ * @returns la donnée du producteur, ou la raison précise de l'échec
+ */
+export declare function readAdminSubject(broker: IAdminBrokerLike | undefined, subject: string, caller: IAdminCaller, target?: string): Promise<InspectResult>;

package/dist/types/kernel/inspect/docOutline.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Découpe d'un markdown par ses titres — le plan, puis une section.
+ *
+ * ⭐ **Pourquoi ce fichier existe** : les pages de documentation du framework
+ * pèsent 50 à 80 ko. Rendues entières à un agent, elles saturent sa fenêtre pour
+ * une question qui tenait dans un paragraphe ; tronquées, elles s'arrêtent au
+ * milieu d'une phrase sans dire ce qui manque. Le plan est la troisième voie :
+ * il coûte quelques centaines d'octets et permet de demander LA section utile.
+ *
+ * Vit dans le cœur parce que ses deux consommateurs sont de part et d'autre de
+ * la frontière de dépendance — le serveur MCP (cœur) et le plan
+ * d'administration (`@nodefony/framework`, qui peut importer le cœur, l'inverse
+ * étant interdit).
+ */
+/** Un titre du document, et ce qu'il ouvre. */
+export interface IMarkdownSection {
+    /** Niveau du titre : 1 pour `#`, 2 pour `##`… */
+    level: number;
+    /** Texte du titre, tel qu'il est écrit. */
+    title: string;
+    /** Ligne (1-indexée) du titre dans le document. */
+    line: number;
+    /** Poids de la section, titre compris — de quoi choisir sans l'ouvrir. */
+    chars: number;
+}
+/**
+ * Repère les titres d'un markdown, **en ignorant les blocs de code**.
+ *
+ * Cette exclusion n'est pas un détail de forme : la documentation du framework
+ * est pleine d'exemples shell, où un `# commentaire` en début de ligne serait
+ * lu comme un titre de niveau 1 — et découperait le document à des endroits qui
+ * n'existent pas.
+ *
+ * @param markdown - corps du document (frontmatter déjà retiré)
+ * @returns les titres dans l'ordre du document, avec le poids de leur section
+ */
+export declare function outlineMarkdown(markdown: string): IMarkdownSection[];
+/**
+ * Extrait UNE section d'un markdown, sous-sections comprises.
+ *
+ * Le titre demandé est reconnu sans casse, sans accents et sans ponctuation
+ * décorative ({@link foldTitle}) : « securite » retrouve « 🔐 Sécurité ». À
+ * défaut d'égalité, une inclusion suffit — un agent cite plus souvent un bout
+ * de titre que sa forme exacte.
+ *
+ * @param markdown - corps du document (frontmatter déjà retiré)
+ * @param wanted - titre cherché, sous n'importe quelle forme approchante
+ * @returns le titre RÉEL et le corps de sa section, ou `null` si rien ne matche
+ */
+export declare function extractMarkdownSection(markdown: string, wanted: string): {
+    title: string;
+    markdown: string;
+} | null;

package/dist/types/kernel/lifecycleTags.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Tags de **politique de boot** posés sur les listeners de lifecycle d'un
+ * {@link Module} — la couche POLITIQUE de la résilience de boot (cf
+ * `Event.emitAsyncGuarded` = la MÉCANIQUE générique, qui, elle, ignore tout de la
+ * notion de module/criticité).
+ *
+ * `Module.setEvents()` tague chaque hook (`onKernelRegister/Boot/Ready`) avec son
+ * propriétaire (`owner`) et sa criticité (`critical`) ; `Kernel.fireLifecycle()`
+ * relit ces tags via {@link readListenerTags} pour décider, en cas d'échec, de
+ * propager (module critique en production) ou de continuer (fail-soft).
+ *
+ * @module
+ */
+/** Tags relus depuis un listener (valeurs `undefined` si non tagué). */
+export interface IListenerTags {
+    /** Nom du module propriétaire du hook, ou `undefined` (listener interne/anonyme). */
+    owner?: string;
+    /** Criticité déclarée du module, ou `undefined` (→ traité comme critique par défaut). */
+    critical?: boolean;
+    /**
+     * Nom de la FONCTION listener, quand elle en a un — repli d'identification
+     * pour les hooks posés à la main (`kernel.on("onBoot", …)`), qui ne portent
+     * aucun `owner`. Sans lui, un échec de boot se journalise « (anonyme) » et ne
+     * désigne personne : en production, où l'échec interrompt le boot, le seul
+     * indice exploitable disparaît. `undefined` pour une lambda inline anonyme.
+     */
+    name?: string;
+}
+/**
+ * Pose `owner` + `critical` sur une fonction listener, **en place**, et la renvoie.
+ *
+ * @typeParam F - type de la fonction (préservé).
+ * @param fn - listener (typiquement `hook.bind(module)`).
+ * @param owner - nom du module propriétaire.
+ * @param critical - criticité du module (cf `Module.critical`).
+ * @returns la même fonction `fn`, taguée.
+ */
+export declare function tagListener<F extends object>(fn: F, owner: string, critical: boolean): F;
+/**
+ * Marque un listener comme n'étant PAS soumis à la borne de temps du boot.
+ *
+ * 🔴 Vécu, et c'est le pire mode de panne qui soit : l'action d'une commande est
+ * câblée comme un écouteur de cycle de vie (`Command.setEvents`), donc bornée
+ * comme un hook de module. Passé vingt secondes, la garde abandonnait
+ * l'écouteur en fail-soft, le boot enchaînait sur `finishOrPark(0)` et le
+ * processus sortait en **0 au milieu du travail**, sans un mot — `doctor
+ * --deep` rendait ainsi un succès muet en plein `npm run test`.
+ *
+ * La distinction est de NATURE, pas de durée : la borne existe pour qu'un module
+ * qui se fige ne gèle pas le DÉMARRAGE. Une commande, elle, EST le programme —
+ * une migration, une construction, une suite de tests ou une question posée à
+ * l'utilisateur dépassent vingt secondes sans rien avoir d'anormal.
+ *
+ * @typeParam F - type de la fonction (préservé).
+ * @param fn - le listener à marquer.
+ * @returns la même fonction `fn`, marquée.
+ */
+export declare function tagUnboundedListener<F extends object>(fn: F): F;
+/**
+ * Dit si un listener a été marqué par {@link tagUnboundedListener}.
+ *
+ * **Déballe le wrapper `once`** pour la même raison que {@link readListenerTags} :
+ * les actions de commande sont câblées via `kernel.once(...)`, et lire le
+ * marquage sur le wrapper interne de Node rendrait toujours `false`.
+ *
+ * @param fn - listener (wrapper `once` ou fonction directe).
+ * @returns `true` si ce listener échappe à la borne de temps du boot.
+ */
+export declare function isUnboundedListener(fn: unknown): boolean;
+/**
+ * Relit les tags d'un listener. **Déballe le wrapper `once`** : `rawListeners()`
+ * renvoie le wrapper interne d'`EventEmitter.once` (qui porte `.listener` =
+ * fonction d'origine) — les hooks de module étant câblés via `kernel.once(...)`,
+ * lire les tags directement sur le wrapper renverrait toujours `undefined`.
+ *
+ * @param fn - listener (wrapper `once` ou fonction directe).
+ * @returns `{ owner, critical }` (valeurs `undefined` si non tagué).
+ */
+export declare function readListenerTags(fn: unknown): IListenerTags;

package/dist/types/kernel/moduleConfig.d.ts

@@ -0,0 +1,35 @@
+import type { ZodType } from "zod";
+/**
+ * Valide la configuration d'un module contre son schéma Zod, et transforme un
+ * refus en {@link BootConfigurationError} nommant le module et la clé fautive.
+ *
+ * ⭐ TL;DR : c'est LA porte par laquelle toute config de module est validée.
+ * Chaque module l'appelle depuis son `define<X>Config()` ; aucun ne réécrit le
+ * bloc `try`/`catch`.
+ *
+ * **Pourquoi une fonction du cœur, et pas un bloc recopié par module.** Les dix
+ * modules du framework portaient le même `catch` à l'identique, et il avait
+ * divergé sur les deux points qui comptent : le TYPE de l'erreur levée et la
+ * LANGUE du message. Une règle écrite à dix endroits diverge au premier ajout.
+ *
+ * **Pourquoi `BootConfigurationError` et pas une `Error` ordinaire.** Le kernel
+ * distingue les deux ({@link BootConfigurationError}) : un hook de cycle de vie
+ * qui lève une erreur QUELCONQUE est absorbé en développement — c'est le
+ * fail-soft, il protège la DX d'un module optionnel cassé — tandis qu'une
+ * erreur de CONFIGURATION interrompt le boot dans TOUS les environnements. Une
+ * `Error` nue rendait donc le refus INVISIBLE là où il est le plus utile :
+ * sur le poste de celui qui vient d'écrire la faute de frappe.
+ *
+ * ⚠️ Ne gèle rien — le gel est la décision du module appelant. `@nodefony/http`
+ * ne peut PAS geler sa config (ses services la mutent au boot : `uploadDir`,
+ * `serialNumber`), quand les autres le font.
+ *
+ * @param schema - schéma Zod du module (source unique des défauts).
+ * @param input - configuration brute venue de `use("<paquet>", { … })`.
+ * @param packageName - nom du paquet, préfixe du message (`@nodefony/http`).
+ * @returns la configuration validée, défauts appliqués.
+ * @throws BootConfigurationError si un champ est invalide ou une clé inconnue —
+ *   toutes les anomalies agrégées, chacune avec son chemin.
+ */
+export declare function parseModuleConfig<T>(schema: ZodType<T>, input: unknown, packageName: string): T;
+export default parseModuleConfig;

package/dist/types/kernel/moduleGating.d.ts

@@ -0,0 +1,78 @@
+/**
+ * La règle qui décide QUELS modules du manifeste seront chargés — et lesquels
+ * disparaîtront.
+ *
+ * Extraite du Kernel pour une raison précise : cette décision se pose à DEUX
+ * moments, et pas seulement au démarrage. Le boot l'applique pour de vrai ; le
+ * diagnostic (`nodefony doctor --env production`) la rejoue à froid, sur un
+ * poste de développement, pour répondre à la question qu'on se pose AVANT de
+ * déployer — « qu'est-ce qui ne sera plus là, là-bas ? ». Deux copies de la
+ * règle divergeraient au premier cas particulier, et c'est précisément le
+ * silence qu'on veut casser qui reviendrait par la porte de derrière.
+ *
+ * Fonction PURE : ni `process.env`, ni kernel, ni journal. Ce qui la rend
+ * éprouvable pour un environnement dans lequel on ne tourne PAS — et c'est tout
+ * l'objet de son second lecteur.
+ */
+import type { IModuleManifest, IModuleManifestEntry } from "../types/IModuleManifest.js";
+/** Ce que la garde `when()` d'un manifeste reçoit — la config fusionnée du kernel. */
+export type GateConfig = Parameters<NonNullable<IModuleManifestEntry["when"]>>[0];
+/** Une entrée retenue, prête à charger. */
+export interface IModuleEntry {
+    name: string;
+    config?: Record<string, unknown>;
+}
+/** Un module volontairement écarté, avec la raison qui le dit. */
+export interface IModuleGated {
+    /** Nom d'entrée du manifeste (`config.modules`). */
+    module: string;
+    /** Raison lisible du non-chargement. */
+    reason: string;
+}
+/** Ce que la règle décide d'un manifeste, sans rien exécuter. */
+export interface IGatingOutcome {
+    /** Les entrées retenues, dans l'ordre du manifeste (= priorité de chargement). */
+    entries: IModuleEntry[];
+    /** Les entrées écartées, avec leur raison. */
+    gated: IModuleGated[];
+    /**
+     * Les modules `policy:"dev"` chargés en production PAR DÉROGATION.
+     *
+     * Rendus à part parce qu'ils appellent un geste que la règle pure ne peut pas
+     * faire : le crier au journal et armer l'auto-arrêt. Un module de banc dans
+     * un runtime de production est une surface offerte — personne ne doit la
+     * découvrir en lisant les routes.
+     */
+    derogated: string[];
+}
+/** Ce que la règle a besoin de savoir de l'environnement — jamais lu ici. */
+export interface IGatingInput {
+    /** `true` si le runtime visé est un runtime de production (collapse dev/prod). */
+    isProduction: boolean;
+    /** `true` si la dérogation `NF_WITH_DEV_MODULES=1` est posée. */
+    forceDevModules: boolean;
+    /**
+     * La config fusionnée, sur laquelle chaque `when()` est évalué.
+     *
+     * Le type est DÉRIVÉ de la garde du manifeste plutôt qu'importé du Kernel :
+     * la règle n'a besoin de rien savoir du Kernel, et l'y raccrocher rendrait
+     * ce module inatteignable depuis un diagnostic qui, justement, ne boote pas.
+     */
+    config: GateConfig;
+}
+/** La raison affichée quand la politique du module l'écarte d'un runtime de production. */
+export declare const GATED_BY_POLICY = "policy \"dev\" \u2014 runtime production";
+/** La raison affichée quand la garde `when(config)` du module refuse. */
+export declare const GATED_BY_CONDITION = "condition when(config) non remplie";
+/**
+ * Applique la règle de gating à un manifeste.
+ *
+ * `policy`/`when` ne font que FILTRER — jamais réordonner : l'ordre du tableau
+ * est la priorité de chargement, et un tri introduirait une dépendance que
+ * personne n'a écrite.
+ *
+ * @param manifest - le manifeste `config.modules`, tel qu'il est déclaré.
+ * @param input - ce qu'il faut savoir de l'environnement visé.
+ * @returns les entrées retenues, celles écartées, et les dérogations.
+ */
+export declare function gateModuleManifest(manifest: IModuleManifest | unknown, input: IGatingInput): IGatingOutcome;