nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/config/reservedEnv.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Les variables d'environnement que **Nodefony pose lui-même**, et qui ne
+ * relèvent donc jamais de la configuration d'une application.
+ *
+ * ## Pourquoi cette liste existe
+ *
+ * `nodefony env` range en « inconnues » toutes les `NF_*` qu'aucune déclaration
+ * n'explique, et il a raison de le faire : une faute de frappe sur une variable
+ * d'environnement ne se voit JAMAIS autrement — la valeur est ignorée et le
+ * défaut s'applique en silence.
+ *
+ * Mais le framework en pose lui-même, dans le dos de l'utilisateur : le lanceur
+ * marque sa délégation, les commandes de démarrage inscrivent le mode, le
+ * maître de grappe signale la grappe, la déclaration MCP porte le jeton. Elles
+ * arrivent alors dans le rapport avec une suggestion de faute de frappe —
+ * `NF_CLI_DELEGATED` « vouliez-vous dire NF_ADMIN_PASSWORD ? ». Le rapport
+ * accuse l'utilisateur d'une variable qu'il n'a pas écrite.
+ *
+ * Elles ne sont pas TUES pour autant : le rapport les rend dans sa propre
+ * section, avec leur rôle. Taire une variable présente, c'est refaire le défaut
+ * dans l'autre sens.
+ *
+ * ## Une seule implémentation
+ *
+ * C'est la source unique de ces noms : `resolveLocalCli` importe les siens
+ * d'ici plutôt que de les redéclarer. Deux listes divergent en silence, et
+ * chacune passe ses propres tests.
+ */
+/** Une variable posée par le framework : son nom et ce qu'elle signale. */
+export interface IReservedEnvVar {
+    /** Nom de la variable, préfixe compris. */
+    name: string;
+    /** Qui la pose, et ce qu'elle veut dire — rendu tel quel dans le rapport. */
+    role: string;
+}
+/**
+ * Le catalogue des variables réservées, indexé par nom.
+ *
+ * Ajouter une entrée ici est OBLIGATOIRE dès qu'un code du framework écrit une
+ * `NF_*` dans l'environnement d'un process : sans elle, la variable ressort en
+ * « inconnue » chez tout utilisateur qui lance la commande au mauvais moment.
+ */
+export declare const RESERVED_ENV: Readonly<{
+    NF_CLI_DELEGATED: {
+        name: string;
+        role: string;
+    };
+    NF_CLI_DEBUG: {
+        name: string;
+        role: string;
+    };
+    NF_MODE_START: {
+        name: string;
+        role: string;
+    };
+    NF_CLUSTER: {
+        name: string;
+        role: string;
+    };
+    NF_MCP_TOKEN: {
+        name: string;
+        role: string;
+    };
+    NF_ENV: {
+        name: string;
+        role: string;
+    };
+    NF_START: {
+        name: string;
+        role: string;
+    };
+    NF_WORKERS: {
+        name: string;
+        role: string;
+    };
+    NF_CLUSTER_PROBE: {
+        name: string;
+        role: string;
+    };
+    NF_POD_NAME: {
+        name: string;
+        role: string;
+    };
+    NF_INSTANCE_ID: {
+        name: string;
+        role: string;
+    };
+    NF_DEV_CHILD: {
+        name: string;
+        role: string;
+    };
+    NF_DEV_PORTS: {
+        name: string;
+        role: string;
+    };
+    NF_BOOT_TIMEOUT_MS: {
+        name: string;
+        role: string;
+    };
+    NF_BOOT_WARN_MS: {
+        name: string;
+        role: string;
+    };
+    NF_KERNEL_TRACE_FILE: {
+        name: string;
+        role: string;
+    };
+    NF_NO_TTY: {
+        name: string;
+        role: string;
+    };
+    NF_PERF_PROBE: {
+        name: string;
+        role: string;
+    };
+    NF_ORM_FLOW: {
+        name: string;
+        role: string;
+    };
+    NF_ORM_HEARTBEAT_MS: {
+        name: string;
+        role: string;
+    };
+    NF_REALTIME_DRIVER: {
+        name: string;
+        role: string;
+    };
+    NF_REALTIME_BACKPLANE_SECRET: {
+        name: string;
+        role: string;
+    };
+    NF_REALTIME_BACKPLANE_NAMESPACE: {
+        name: string;
+        role: string;
+    };
+}>;
+/** Cette variable est-elle posée par le framework lui-même ? */
+export declare function isReservedEnv(name: string): boolean;
+/**
+ * Le rôle d'une variable réservée, ou `null` si elle ne l'est pas.
+ *
+ * @param name - le nom lu dans l'environnement.
+ * @returns la phrase à rendre à l'utilisateur, ou `null`.
+ */
+export declare function reservedEnvRole(name: string): string | null;

package/dist/types/config/schema.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Schéma Zod de la config d'application — validé au resolve de `defineConfig` (D1).
+ *
+ * Vit dans le CORE (zod = peerDep core, back-only) : `import { defineConfig } from
+ * "nodefony"` valide tout seul, sans que chaque app porte son propre schéma. But :
+ * planter PROPREMENT au boot (message clair) sur une config malformée, plutôt qu'un
+ * `Cannot read properties of undefined` plus tard en runtime.
+ *
+ * Le schéma DÉCRIT (il ne dérive pas les défauts — ceux-ci sont dans `./defaults`).
+ * Tous les champs sont `.optional()` : il rejette les TYPES/valeurs invalides, pas
+ * l'absence (le merge a déjà rempli les défauts ; le Kernel a des fallbacks
+ * résiduels). Les clés inconnues — `module-<x>` (overrides validés par chaque
+ * module), `App`, `cluster`… — sont ignorées (objet zod non-strict).
+ */
+import { z } from "zod";
+/**
+ * Schéma de la config app résolue. Exposé pour l'introspection (Studio :
+ * `z.toJSONSchema(appConfigSchema)` → panneau de config + formulaire éditable).
+ *
+ * Chaque champ porte un `.describe()` FR (rôle + défaut) → consommé par le
+ * panneau de config Studio (`/nodefony/config`, carte de l'app).
+ */
+export declare const appConfigSchema: z.ZodObject<{
+    modules: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    locale: z.ZodOptional<z.ZodString>;
+    templating: z.ZodOptional<z.ZodString>;
+    orm: z.ZodOptional<z.ZodString>;
+    packageManager: z.ZodOptional<z.ZodEnum<{
+        bun: "bun";
+        npm: "npm";
+        pnpm: "pnpm";
+        yarn: "yarn";
+    }>>;
+    domain: z.ZodOptional<z.ZodString>;
+    domainAlias: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    domainCheck: z.ZodOptional<z.ZodBoolean>;
+    servers: z.ZodOptional<z.ZodObject<{
+        statics: z.ZodOptional<z.ZodBoolean>;
+        http: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            port: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodLiteral<false>]>>;
+        https: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            port: z.ZodOptional<z.ZodNumber>;
+            protocol: z.ZodOptional<z.ZodEnum<{
+                1.1: "1.1";
+                "2.0": "2.0";
+            }>>;
+        }, z.core.$strip>, z.ZodLiteral<false>]>>;
+        ws: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+        wss: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+        portPolicy: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            strict: "strict";
+        }>>;
+        portRetryAttempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cluster: z.ZodOptional<z.ZodUnknown>;
+    timing: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        verbose: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    shutdownDeadline: z.ZodOptional<z.ZodNumber>;
+    log: z.ZodOptional<z.ZodObject<{
+        active: z.ZodOptional<z.ZodBoolean>;
+        debug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        requestFormat: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            default: "default";
+            json: "json";
+            pretty: "pretty";
+        }>>;
+        buffered: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
+        driver: z.ZodOptional<z.ZodEnum<{
+            file: "file";
+            null: "null";
+            stdout: "stdout";
+        }>>;
+        dir: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            sync: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        maxStack: z.ZodOptional<z.ZodNumber>;
+        queryFile: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            maxScanBytes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        queryDriver: z.ZodOptional<z.ZodString>;
+        loki: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        opensearch: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Type inféré de la config app (source unique TS ↔ runtime). */
+export type AppConfig = z.infer<typeof appConfigSchema>;
+/**
+ * JSON Schema introspectable de la config d'application — destiné au panneau de
+ * config Studio (`/nodefony/config`, carte de l'app). Documenté via les
+ * `.describe()` du schéma (rôle + défaut de chaque champ).
+ */
+export declare function appConfigJsonSchema(): unknown;
+/**
+ * Valide la config app résolue ; lève une erreur au message agrégé si invalide.
+ *
+ * Appelée par `defineConfig().resolve()` après le deep-merge avec les défauts.
+ *
+ * @param options - config app résolue à valider.
+ * @throws Error si la config ne respecte pas {@link appConfigSchema}.
+ */
+export declare function validateAppConfig(options: unknown): void;

package/dist/types/config/types.d.ts

@@ -0,0 +1,374 @@
+/**
+ * Types publics du moteur de configuration `defineConfig` (back-only, D1).
+ *
+ * Pilier #1 du chantier configuration : **typage impeccable**. Chaque clé de
+ * {@link AppConfigInput} porte un bloc TSDoc auto-suffisant (1ʳᵉ phrase + `@default`
+ * + `@reactivity`) → dans l'éditeur, taper `{` dans `defineConfig` propose toutes
+ * les clés avec leur explication en hover.
+ *
+ * `@reactivity hot` : la valeur peut s'appliquer À CHAUD (sans redémarrer le
+ * serveur — futur `Kernel.applyConfigPatch`). `@reactivity boot` : figée au boot
+ * (un changement exige un redémarrage). La métadonnée structurée est dans
+ * `./reactivity` (exploitable par Studio + le mécanisme hot-apply).
+ *
+ * Ces types ne dépendent PAS du Kernel (importables/testables sans serveur).
+ */
+import type { ModulePolicy } from "../types/IModuleManifest.js";
+import type { IInfra } from "./infra.js";
+/**
+ * Noms de modules connus du framework — proposés à l'autocomplétion tout en
+ * **acceptant n'importe quel module tiers** (astuce `string & {}` : conserve les
+ * littéraux connus dans la complétion sans fermer le type aux strings arbitraires).
+ */
+export type KnownModule = "@nodefony/http" | "@nodefony/framework" | "@nodefony/security" | "@nodefony/user" | "@nodefony/frontend" | "@nodefony/studio" | "@nodefony/documentation" | "@nodefony/realtime" | "@nodefony/redis" | "@nodefony/drizzle" | "@nodefony/mongoose" | (string & {});
+/**
+ * Entrée détaillée du manifeste `modules` (forme objet). Une `string` nue
+ * équivaut à `{ name, policy: "optional" }`.
+ */
+export interface ModuleEntryInput {
+    /** Nom du module à charger (résolu par `import()` dynamique au boot). */
+    name: KnownModule;
+    /** Politique de chargement. Défaut `"optional"`. `"dev"` = hors production. */
+    policy?: ModulePolicy;
+    /** Garde évaluée sur la config résolue ; `false` → module ignoré (0 coût). */
+    when?: (config: ResolvedAppConfig) => boolean;
+    /**
+     * Config colocalisée du module (deep-mergée sous sa config DEFAULT au boot par
+     * le Kernel, avant la validation Zod du module). Remplace les clés legacy
+     * `module-<nom>` à la racine. À écrire via {@link use} pour un typage par module
+     * (les clés proposées sont celles du module ciblé).
+     */
+    config?: Record<string, unknown>;
+}
+/**
+ * Manifeste ORDONNÉ des modules de l'application (position = ordre de chargement).
+ * `policy`/`when` filtrent, ne réordonnent jamais.
+ */
+export type ModuleManifestInput = ReadonlyArray<KnownModule | ModuleEntryInput>;
+/** Métadonnées d'identité de l'application (affichées dans la CLI et les logs d'init). */
+export interface AppMeta {
+    /** Année du projet (copyright, bannières). */
+    projectYear?: string;
+    /** Locale d'affichage des métadonnées. */
+    locale?: string;
+    /** Nom de l'auteur / mainteneur. */
+    authorName?: string;
+    /** E-mail de contact de l'auteur. */
+    authorMail?: string;
+}
+/** Serveur HTTP plain. */
+export interface HttpServerConfig {
+    /**
+     * Port d'écoute HTTP plain.
+     * @default 5151
+     * @reactivity boot
+     */
+    port?: number;
+}
+/** Serveur HTTPS (+ WSS hérité). */
+export interface HttpsServerConfig {
+    /**
+     * Port d'écoute HTTPS.
+     * @default 5152
+     * @reactivity boot
+     */
+    port?: number;
+    /**
+     * Protocole TLS : `"2.0"` (HTTP/2 + ALPN fallback 1.1) ou `"1.1"` strict.
+     * @default "2.0"
+     * @reactivity boot
+     */
+    protocol?: "1.1" | "2.0";
+}
+/** Serveurs réseau HTTP/HTTPS/WS/WSS (un seul domaine, pas de vhost). */
+export interface ServersConfig {
+    /**
+     * Active le serveur de fichiers statiques (assets, uploads).
+     * @default true
+     * @reactivity boot
+     */
+    statics?: boolean;
+    /** Serveur HTTP plain. `false` = désactivé (déploiement TLS-only). */
+    http?: HttpServerConfig | false;
+    /**
+     * Serveur HTTPS (le WSS en hérite). `false` = désactivé — cas NOMINAL
+     * cloud-native : TLS terminé à l'ingress/LB, le pod sert en clair.
+     */
+    https?: HttpsServerConfig | false;
+    /** Serveur WebSocket (hérite du HTTP associé). */
+    ws?: Record<string, unknown>;
+    /** Serveur WebSocket Secure (hérite du HTTPS associé). */
+    wss?: Record<string, unknown>;
+    /**
+     * Que faire quand le port désiré est DÉJÀ OCCUPÉ.
+     *
+     * - `auto` : prendre le prochain port libre. L'app boote au lieu de mourir, et
+     *   le décalage est **annoncé** (jamais silencieux). Confort de dev : plusieurs
+     *   apps Nodefony côte à côte.
+     * - `strict` : échec fatal (EADDRINUSE).
+     *
+     * Le défaut dépend de l'environnement, et c'est délibéré :
+     * - **production → `strict`.** Le port y est un CONTRAT (service k8s, ingress,
+     *   sonde de santé). Écouter ailleurs en silence produirait un pod « sain »
+     *   que personne n'atteint — une panne invisible.
+     * - **test → `strict`.** Un port occupé signale un serveur resté debout ; le
+     *   banc doit s'arrêter net, pas taper à côté.
+     * - **développement → `auto`.** Là, un port pris est une nuisance, pas un contrat.
+     *
+     * @default "auto" en développement, "strict" en production et en test
+     * @reactivity boot
+     */
+    portPolicy?: "auto" | "strict";
+    /**
+     * En `portPolicy: "auto"`, nombre de ports essayés après le port désiré.
+     * @default 20
+     * @reactivity boot
+     */
+    portRetryAttempts?: number;
+}
+/** Sortie fichier du Syslog. */
+export interface LogFileConfig {
+    /**
+     * Chemin explicite du fichier de log (sink `file`). À défaut, le sink écrit
+     * `<dir>/nodefony-<pid>.log` (un fichier par worker, 0 lock d'inode partagé).
+     * @reactivity boot
+     */
+    path?: string;
+    /**
+     * Écriture synchrone (`writeSync`) par worker au lieu du buffer async.
+     * @default false
+     * @reactivity boot
+     */
+    sync?: boolean;
+}
+/** Options du driver de RELECTURE `file` du log backplane (query plane JSONL). */
+export interface LogQueryFileConfig {
+    /**
+     * Chemin du fichier JSONL relu par le driver de query `file`. À défaut, dérivé
+     * du répertoire de logs.
+     * @reactivity boot
+     */
+    path?: string;
+    /**
+     * Plafond d'octets scannés en fin de fichier lors d'une query (garde-fou I/O).
+     * @reactivity boot
+     */
+    maxScanBytes?: number;
+}
+/** Destination prod queryable du log backplane (Loki / OpenSearch). */
+export interface LogDestinationConfig {
+    /** URL HTTP de la destination. */
+    url: string;
+}
+/** Observabilité — Syslog Nodefony + log backplane. */
+export interface LogConfig {
+    /**
+     * Master switch des logs. `false` = silence total (tests).
+     * @default true
+     * @reactivity hot
+     */
+    active?: boolean;
+    /**
+     * Filtre des sources DEBUG : `"*"` (tout), `[]` (aucun), `["router"]` (ciblé).
+     * @default []
+     * @reactivity hot
+     */
+    debug?: string | string[];
+    /**
+     * Format de log émis par HttpKernel pour chaque requête finie.
+     * `"auto"` choisit selon l'environnement (dev=pretty, prod=json).
+     * @default "auto"
+     * @reactivity hot
+     */
+    requestFormat?: "auto" | "default" | "pretty" | "json";
+    /**
+     * Bufférisation de la sortie console (`"auto"` = bufférise hors TTY).
+     * @default "auto"
+     * @reactivity boot
+     */
+    buffered?: boolean | "auto";
+    /**
+     * Sink d'écriture des logs : `"stdout"` (cloud-native), `"file"`, `"null"` (bench).
+     * @default "stdout"
+     * @reactivity boot
+     */
+    driver?: "stdout" | "file" | "null";
+    /**
+     * Répertoire des logs (fichiers `.log` + JSONL queryable + viewer Studio),
+     * résolu sous `process.cwd()`.
+     * @default "logs"
+     * @reactivity boot
+     */
+    dir?: string;
+    /** Options du sink fichier. */
+    file?: LogFileConfig;
+    /**
+     * Profondeur du ring de relecture du backplane de log (driver `memory`). Non
+     * défini = 2000 en développement (trace d'une requête lisible), sinon repli
+     * prod-safe interne.
+     * @reactivity boot
+     */
+    maxStack?: number;
+    /** Options du driver de relecture `file` (query plane JSONL). */
+    queryFile?: LogQueryFileConfig;
+    /**
+     * Driver de RELECTURE du log backplane (≠ sink d'écriture). `auto` (défaut)
+     * s'adapte au mode : mono → `memory`, worker de cluster → `cluster-file` (vue
+     * unifiée). Toute valeur explicite (`memory`/`file`/`loki`/…) surcharge.
+     * @default "auto"
+     * @reactivity boot
+     */
+    queryDriver?: string;
+    /** Destination Loki (active si `queryDriver === "loki"`). @reactivity boot */
+    loki?: LogDestinationConfig;
+    /** Destination OpenSearch (active si `queryDriver === "opensearch"`). @reactivity boot */
+    opensearch?: LogDestinationConfig;
+}
+/**
+ * Forme de la configuration d'une application Nodefony, telle qu'écrite par
+ * l'utilisateur dans `nodefony.config.ts`. Tous les champs sont optionnels : ce
+ * que l'app n'écrit pas vient de {@link defaultAppConfig} (deep-merge au resolve).
+ */
+export interface AppConfigInput {
+    /**
+     * Manifeste ordonné des modules chargés (liste + policy + gating `when`).
+     * Seule source de vérité du chargement (le Kernel l'orchestre à `onPreRegister`).
+     * @reactivity boot
+     */
+    modules?: ModuleManifestInput;
+    /**
+     * Locale par défaut de l'app (fallback translation/dates), override par requête.
+     * @default "en_en"
+     * @reactivity boot
+     */
+    locale?: string;
+    /** Métadonnées d'identité de l'app (auteur, année) — affichées CLI + logs. */
+    App?: AppMeta;
+    /**
+     * Moteur de templates des vues controllers (`renderView`). Unique : Eta.
+     * @default "eta"
+     * @reactivity boot
+     */
+    templating?: string;
+    /**
+     * ORM par défaut (commandes CLI + modules sans ORM explicite). Multi-ORM :
+     * la forme cible (`{ driver: "drizzle" }`) et le défaut sont définis par le
+     * chantier ORM — pas de défaut framework figé ici.
+     * @reactivity boot
+     */
+    orm?: string;
+    /**
+     * Gestionnaire de paquets Node.js (commandes install/outdated/build).
+     * @default "npm"
+     * @reactivity boot
+     */
+    packageManager?: "npm" | "yarn" | "pnpm" | "bun";
+    /**
+     * Domaine d'écoute (un seul, pas de vhost). Prod : `"0.0.0.0"` ou IP fixe.
+     * @default "localhost"
+     * @reactivity boot
+     */
+    domain?: string;
+    /**
+     * Alias de domaines acceptés (regexps stringifiées), actif si `domainCheck` —
+     * validation Host kernel-level (compilée en RegExp). En cours de consolidation
+     * avec `http.trustedHosts` (deux barrières Host concurrentes à unifier).
+     * @reactivity boot
+     */
+    domainAlias?: string[];
+    /**
+     * Active la validation Host kernel-level (`domain` + `domainAlias`) avant le
+     * routing. Off par défaut (opt-in) ; en cours de consolidation avec
+     * `http.trustedHosts`.
+     * @reactivity boot
+     */
+    domainCheck?: boolean;
+    /** Serveurs HTTP/HTTPS/WS/WSS. */
+    servers?: ServersConfig;
+    /**
+     * Topologie cluster (cloud-native, sans PM2). Résolue par `resolveTopology`
+     * (override runtime : CLI `--workers` > `NF_WORKERS` > ce champ).
+     * @reactivity boot
+     */
+    cluster?: Record<string, unknown>;
+    /**
+     * Deadline GLOBALE du shutdown (ms) — au-delà, `Kernel.terminate` force la
+     * sortie `code 1` même si un listener `onTerminate` pend (SSE ouvert, store
+     * bloqué, module tiers). Filet cloud-native : garder < grace period de
+     * l'orchestrateur (30 s k8s, 10 s Docker). Distinct de
+     * `http.servers.*.shutdownTimeout` (drain PAR SERVEUR, borne le nominal) :
+     * ici c'est le filet de TOUT le terminate. `0` = désactivé. Défaut : `15000`.
+     * @reactivity boot
+     */
+    shutdownDeadline?: number;
+    /**
+     * Instrumentation du pipeline — la sonde de phases qui alimente le waterfall
+     * (Studio/Playground, debug bar, profiler).
+     *
+     * `enabled: null` (défaut) = pas d'avis → la règle d'environnement s'applique
+     * (active hors production, éteinte en production). Un booléen explicite gagne :
+     * `true` allume la sonde EN PRODUCTION (diagnostic à chaud, coût assumé),
+     * `false` l'éteint partout. Override sans redéploiement :
+     * `NF__APP__TIMING__ENABLED=true`.
+     * @reactivity boot
+     */
+    timing?: {
+        enabled?: boolean | null;
+        /** Trace DEBUG d'une ligne par requête détaillant chaque phase. Implique `enabled`. */
+        verbose?: boolean;
+    };
+    /** Observabilité (Syslog + log backplane). */
+    log?: LogConfig;
+    /**
+     * Surcharge de la config DEFAULT d'un module chargé (clé `module-<nom>`).
+     * Exemple : `"module-http": { upload: { uploadDir: "/var/upload" } }`.
+     * Fusion récursive (deep merge) appliquée par le Kernel à `preRegister`.
+     */
+    [moduleOverride: `module-${string}`]: unknown;
+}
+/**
+ * Configuration résolue : {@link AppConfigInput} après deep-merge avec les
+ * défauts framework et validation Zod. Même forme structurelle (le merge remplit
+ * les valeurs ; le Kernel lit défensivement avec ses propres fallbacks résiduels).
+ */
+export type ResolvedAppConfig = AppConfigInput;
+/**
+ * Contexte passé à la forme fonction de `defineConfig` — permet de différencier
+ * la config par environnement SANS fichier `config.<env>.ts` parallèle (D3).
+ *
+ * @typeParam E - forme du catalogue d'env typé (inféré de `defineEnv`, Lot 2).
+ *
+ * @example
+ * ```ts
+ * defineConfig((ctx) => ({
+ *   domain: ctx.isProd ? "0.0.0.0" : "127.0.0.1",
+ * }));
+ * ```
+ */
+export interface ConfigContext<E = Record<string, unknown>> {
+    /** Catalogue des variables d'environnement typées (`defineEnv`, Lot 2). */
+    readonly env: E;
+    /**
+     * Infra déclarée résolus depuis l'environnement (modèle « infra déclarée »,
+     * Phase 0.8) — `database`/`cache`/`logs`. Sert au gating de modules
+     * (ex. `when: () => !!ctx.infra.cache` pour redis) sans relire `process.env`.
+     */
+    readonly infra: IInfra;
+    /** Environnement applicatif libre (`APP_ENV`/`NF_ENV`) — granularité métier. */
+    readonly appEnv: string;
+    /** Environnement runtime canonisé (`NODE_ENV`). */
+    readonly runtimeEnv: string;
+    /** Raccourci `runtimeEnv === "production"`. */
+    readonly isProd: boolean;
+    /** Raccourci `runtimeEnv === "development"`. */
+    readonly isDev: boolean;
+    /** Raccourci `runtimeEnv === "test"`. */
+    readonly isTest: boolean;
+}
+/**
+ * Entrée de `defineConfig` : soit un objet de config, soit une fonction
+ * `(ctx) => objet` pour différencier par environnement (D3).
+ *
+ * @typeParam E - forme du catalogue d'env typé (Lot 2).
+ */
+export type ConfigInput<E = Record<string, unknown>> = AppConfigInput | ((ctx: ConfigContext<E>) => AppConfigInput);