nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/runtime/withTimeout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Borne une promesse par un délai maximum — utilitaire de **résilience de boot**
+ * (et de tout `await` susceptible de pendre indéfiniment).
+ *
+ * Motivation : un `await` sur une opération réseau dont le pair est injoignable
+ * peut **ne jamais se résoudre** (ex. l'offline-queue de `node-redis` met la
+ * Promise en attente sans la rejeter). Sans garde, un seul de ces `await` gèle
+ * tout le cycle de boot du Kernel → les serveurs ne montent jamais.
+ *
+ * ⚠️ **NE PAS utiliser dans le hot path HTTP/WS** : chaque appel alloue un timer
+ * + une Promise de course. Réservé au **boot / lifecycle / jobs** (≪ 1×/process).
+ * Le hot path utilise `Event.emitAsync` nu (aucun timer par requête).
+ *
+ * @module
+ */
+/**
+ * Erreur levée par {@link withTimeout} quand le délai est dépassé — distincte
+ * d'un rejet métier pour que l'appelant puisse différencier « lent/figé » de
+ * « a échoué » (ex. politique de boot : timeout d'un module critique en prod).
+ */
+export declare class TimeoutError extends Error {
+    /** Délai (ms) qui a été dépassé. */
+    readonly timeoutMs: number;
+    /**
+     * @param timeoutMs - délai dépassé, en millisecondes.
+     * @param label - libellé optionnel de l'opération (préfixe du message).
+     */
+    constructor(timeoutMs: number, label?: string);
+}
+/**
+ * Résout avec la valeur de `promise` si elle se règle avant `timeoutMs`,
+ * sinon rejette avec une {@link TimeoutError}.
+ *
+ * Robustesse :
+ * - le timer est `unref` (ne maintient pas l'event-loop vivant) et **toujours**
+ *   nettoyé (`finally`) → aucun handle qui fuit ;
+ * - un `.catch()` est posé sur la promesse d'origine : si elle rejette **après**
+ *   que le timeout a gagné la course, le rejet ne remonte pas en
+ *   `unhandledRejection` (qui crasherait le process) ;
+ * - `timeoutMs ≤ 0` (ou non fini) → **aucune garde**, on attend la promesse telle
+ *   quelle (permet de désactiver le timeout par config sans brancher de code).
+ *
+ * @typeParam T - type résolu par la promesse.
+ * @param promise - opération à borner.
+ * @param timeoutMs - délai max en millisecondes (≤ 0 = pas de timeout).
+ * @param label - libellé optionnel pour le message d'erreur.
+ * @returns la valeur résolue par `promise`.
+ * @throws {@link TimeoutError} si `timeoutMs` est dépassé.
+ * @throws l'erreur d'origine si `promise` rejette avant le timeout.
+ */
+export declare function withTimeout<T>(promise: PromiseLike<T>, timeoutMs: number, label?: string): Promise<T>;

package/dist/types/service/cluster/ClusterManager.d.ts

@@ -0,0 +1,112 @@
+import { Severity } from "../../syslog/Pdu.js";
+/**
+ * Calcule le délai de respawn d'un worker mort selon un backoff exponentiel.
+ *
+ * Anti crash-loop : un worker qui crashe en boucle ne doit pas être re-forké en
+ * rafale (CPU 100 %, logs noyés). Le délai double à chaque crash consécutif, plafonné.
+ *
+ * @param crashes - nombre de crashs consécutifs (>= 1).
+ * @param baseMs - délai du 1er respawn.
+ * @param maxMs - plafond du délai.
+ * @returns délai en ms, dans `[baseMs, maxMs]`.
+ */
+export declare function computeBackoff(crashes: number, baseMs: number, maxMs: number): number;
+/** Handle minimal d'un worker — sous-ensemble de `cluster.Worker` réellement utilisé (testable). */
+export interface IClusterWorker {
+    readonly id: number;
+    /** Envoie un signal au process worker (déconnecte + signale, cf `cluster.Worker.kill`). */
+    kill(signal?: NodeJS.Signals): void;
+    /** `true` si le process est mort. */
+    isDead(): boolean;
+}
+/** Runtime cluster — abstrait `node:cluster` pour piloter fork/exit dans les tests sans forker de process. */
+export interface IClusterRuntime {
+    readonly isPrimary: boolean;
+    fork(): IClusterWorker;
+    onExit(cb: (worker: IClusterWorker, code: number | null, signal: string | null) => void): void;
+}
+/** Planificateur (setTimeout/clearTimeout) — injectable pour tester backoff + timeout sans horloge réelle. */
+export interface ClusterScheduler {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** Options du {@link ClusterManager}. Tous les effets de bord (runtime, timers, exit, log) sont injectables. */
+export interface ClusterManagerOptions {
+    /** Nombre de workers à forker (résolu par {@link resolveWorkerCount}). */
+    workers: number;
+    log?: (msg: string, severity?: Severity) => void;
+    runtime?: IClusterRuntime;
+    scheduler?: ClusterScheduler;
+    /** Sortie process — injectable pour ne pas tuer le process de test. Défaut : `process.exit`. */
+    exit?: (code: number) => void;
+    /** Délai du 1er respawn (ms). Défaut 200. */
+    respawnBaseMs?: number;
+    /** Plafond du délai de respawn (ms). Défaut 10 000. */
+    respawnMaxMs?: number;
+    /** Durée de vie minimale d'un worker pour réinitialiser le backoff (ms). Défaut 30 000. */
+    stableMs?: number;
+    /** Délai de drain gracieux avant SIGKILL des survivants (ms). Défaut 10 000. */
+    shutdownTimeoutMs?: number;
+}
+/**
+ * Superviseur cluster du process MASTER (Phase 2 du mode cluster sans PM2).
+ *
+ * Le master ne sert AUCUN HTTP : il fork N workers, les respawn avec backoff en cas
+ * de crash, et coordonne un arrêt gracieux (drain SIGTERM → SIGKILL après timeout).
+ * Cgroup-aware via {@link resolveWorkerCount} (le `workers` passé est déjà résolu).
+ *
+ * Toute la mécanique runtime (`node:cluster`, timers, `process.exit`, signaux) est
+ * derrière des seams injectables : le state machine respawn/shutdown est testé sans
+ * forker un seul process réel.
+ */
+export declare class ClusterManager {
+    #private;
+    constructor(opts: ClusterManagerOptions);
+    /** Nombre de workers actuellement vivants. */
+    get size(): number;
+    /** `true` une fois `shutdown()` enclenché (plus aucun respawn). */
+    get shuttingDown(): boolean;
+    /**
+     * Fork les workers initiaux et arme le respawn. Idempotent.
+     *
+     * @returns `this`.
+     */
+    start(): this;
+    /**
+     * Arrêt gracieux : déconnecte/SIGTERM chaque worker (drain), puis SIGKILL les
+     * survivants après `shutdownTimeoutMs`, et sort le process. Idempotent.
+     *
+     * @param signal - signal d'origine (log uniquement).
+     */
+    shutdown(signal?: NodeJS.Signals): void;
+    /**
+     * Branche SIGTERM/SIGINT du process MASTER sur {@link shutdown}.
+     *
+     * Le master prend la main sur ces signaux : `Cli.handleSignals` les mapperait
+     * sinon vers un `terminate()` immédiat (process.exit) qui tuerait le master
+     * AVANT que les workers aient drainé. À n'appeler que dans le vrai process
+     * master.
+     *
+     * 🔴 **On n'arrache que ce qu'on a posé soi-même.** Cette méthode commençait
+     * par `process.removeAllListeners(sig)` — ce qui effaçait AUSSI le
+     * gestionnaire qu'un module tiers avait branché sur `SIGTERM` pour son propre
+     * arrêt propre. Ce module ne recevait plus rien, et rien ne le lui disait :
+     * son code était juste, ses tests passaient, et son nettoyage cessait de
+     * s'exécuter le jour où l'application passait en cluster. Le gestionnaire du
+     * CLI, lui, se retire NOMMÉMENT — c'est le lanceur qui le fait
+     * (`Cli.releaseSignalListeners`), parce que lui seul sait de quelle instance
+     * il s'agit.
+     */
+    installSignalHandlers(): void;
+    /**
+     * Retire les gestionnaires que {@link installSignalHandlers} a posés.
+     *
+     * Symétrique, et pour la même raison qu'il ne faut pas arracher ceux des
+     * autres : un master qui s'arrête laisse sinon deux listeners sur un process
+     * qui peut lui survivre (tests, outils qui enchaînent des commandes).
+     *
+     * @returns le nombre de gestionnaires retirés.
+     */
+    removeSignalHandlers(): number;
+}
+export default ClusterManager;

package/dist/types/service/cluster/ClusterProbeAggregator.d.ts

@@ -0,0 +1,68 @@
+import { Severity } from "../../syslog/Pdu.js";
+/**
+ * Handle master-side d'un worker, vu par l'agrégateur — sous-ensemble **testable** de
+ * `cluster.Worker` (même seam que `IRelayWorker`). Prouve la collecte + la diffusion
+ * sans forker de process réel.
+ */
+export interface IProbeWorker {
+    readonly id: number;
+    /** PID OS du worker (`worker.process.pid`) — clé de ciblage du drill-down (Phase 2). */
+    readonly pid: number;
+    /** Envoie un message IPC à CE worker (master → worker). */
+    send(msg: unknown): void;
+    /** Enregistre le récepteur des messages de CE worker (worker → master). */
+    onMessage(cb: (msg: unknown) => void): void;
+}
+/** Options du {@link ClusterProbeAggregator}. */
+export interface ClusterProbeAggregatorOptions {
+    /** Cadence de diffusion du snapshot agrégé (ms). Défaut 2000. */
+    intervalMs?: number;
+    log?: (msg: string, severity?: Severity) => void;
+}
+/**
+ * **Agrégateur de sondes** master-side du mode cluster (Phase 4c) — le « gardien » qui
+ * collecte la santé de chaque worker et **rediffuse la vue d'ensemble** à tous.
+ *
+ * Pourquoi : chaque worker n'a que SA sonde (`RealtimeHub.probe()`) ; l'endpoint
+ * `/nodefony/realtime/api/health` tombe sur UN worker au hasard → vue partielle. Le master
+ * (qui ne sert aucun HTTP) collecte les remontées `CLUSTER_PROBE_KIND` de tous les workers
+ * et **pousse** périodiquement le snapshot agrégé (`CLUSTER_PROBE_SNAPSHOT_KIND`) vers chacun
+ * → n'importe quel worker peut alors servir la vue POD instantanément (modèle push, pas pull :
+ * 0 latence de requête, cohérent avec les tickers Nodefony).
+ *
+ * **Opaque** comme le {@link "./ClusterRelay"} : le master ne lit JAMAIS le contenu d'une
+ * sonde (il garde le dernier payload par workerId et diffuse la liste) → 0 dépendance à
+ * `@nodefony/framework` (la consolidation des champs se fait côté worker, qui connaît le type).
+ *
+ * Cycle de vie d'un worker : `attach` au `fork` (collecte ses remontées), `detach` au `exit`
+ * (le worker mort SORT de l'agrégat → le snapshot suivant ne le contient plus). Diffusion
+ * sur timer `unref` (cloud-native).
+ */
+export declare class ClusterProbeAggregator {
+    #private;
+    constructor(opts?: ClusterProbeAggregatorOptions);
+    /** Nombre de workers rattachés. */
+    get size(): number;
+    /** Total de snapshots diffusés (sonde de la gateway). */
+    get broadcastTotal(): number;
+    /**
+     * Rattache un worker : cible de diffusion + récepteur de ses remontées de sonde.
+     * Idempotent par `id` (un respawn réattache proprement).
+     */
+    attach(worker: IProbeWorker): void;
+    /** Détache un worker (au `exit`) : il sort de l'agrégat. No-op s'il est déjà parti. */
+    detach(id: number): void;
+    /** Démarre la diffusion périodique du snapshot agrégé. Idempotent. Timer `unref`. */
+    start(): void;
+    /**
+     * Diffuse immédiatement le snapshot courant (liste des dernières sondes connues) à
+     * tous les workers vivants. Appelable directement (tests) ou par le timer. N'envoie
+     * rien s'il n'y a aucun worker.
+     */
+    broadcast(): void;
+    /** Arrête le timer de diffusion. Idempotent. */
+    stop(): void;
+    /** Vide l'agrégateur (arrêt du master). */
+    clear(): void;
+}
+export default ClusterProbeAggregator;

package/dist/types/service/cluster/ClusterRelay.d.ts

@@ -0,0 +1,57 @@
+import { Severity } from "../../syslog/Pdu.js";
+/**
+ * Handle master-side d'un worker, vu par le relay — sous-ensemble **testable** de
+ * `cluster.Worker` réellement utilisé (même approche que `IClusterWorker` du
+ * ClusterManager). Permet de prouver le routage sans forker de process réel.
+ */
+export interface IRelayWorker {
+    readonly id: number;
+    /** Envoie un message IPC à CE worker (master → worker). */
+    send(msg: unknown): void;
+    /** Enregistre le récepteur des messages de CE worker (worker → master). */
+    onMessage(cb: (msg: unknown) => void): void;
+}
+/** Options du {@link ClusterRelay}. Effets de bord (log) injectables. */
+export interface ClusterRelayOptions {
+    log?: (msg: string, severity?: Severity) => void;
+}
+/**
+ * **Master-gateway** du backplane realtime cluster (Phase 3) — routeur IPC qui vit dans
+ * le process MASTER (lequel ne sert AUCUN HTTP, cf {@link ClusterManager}).
+ *
+ * Les workers d'un cluster Node natif ne se parlent **jamais** directement : un worker
+ * n'envoie qu'au master. Le relay reçoit les publications realtime d'un worker et les
+ * **rebroadcast aux AUTRES** workers — ce qui réalise le fan-out cross-process intra-pod
+ * « comme si Redis était là », sans aucune infra (cf vision cluster-backplane).
+ *
+ * Anti-echo de routage : le message **n'est jamais renvoyé à sa source** (le worker
+ * filtre AUSSI son `originId` côté `ClusterBackplane` — ceinture + bretelles).
+ *
+ * Tri par `kind` : seuls les messages realtime (`CLUSTER_RT_KIND`) sont rebroadcastés.
+ * Les autres messages de contrôle (ex. remontées de sondes à **agréger** au master,
+ * Phase 4) sont laissés à un autre consommateur — le relay les ignore (il ne les fan-out
+ * surtout PAS). Messages malformés ignorés silencieusement (robustesse IPC).
+ *
+ * Le master ne tient aucun hub realtime : il route des messages **opaques** (`channel`,
+ * `payload`, `originId` ne sont pas inspectés) → 0 dépendance à `@nodefony/framework`
+ * (respect du sens des dépendances framework→core).
+ */
+export declare class ClusterRelay {
+    #private;
+    constructor(opts?: ClusterRelayOptions);
+    /** Nombre de workers actuellement rattachés au relay. */
+    get size(): number;
+    /** Total des messages realtime rebroadcastés (sonde gateway). */
+    get relayedTotal(): number;
+    /**
+     * Rattache un worker : l'enregistre comme cible de broadcast et branche la réception
+     * de ses messages. Idempotent par `id` (un respawn réattache proprement). À appeler
+     * au `fork` (et à chaque respawn) côté ClusterManager.
+     */
+    attach(worker: IRelayWorker): void;
+    /** Détache un worker (au `exit`). No-op s'il est déjà parti. */
+    detach(id: number): void;
+    /** Vide le relay (arrêt du master). Les workers sont tués par le ClusterManager. */
+    clear(): void;
+}
+export default ClusterRelay;

package/dist/types/service/cluster/clusterMaster.d.ts

@@ -0,0 +1,40 @@
+import { Severity } from "../../syslog/Pdu.js";
+import { ClusterManager } from "./ClusterManager.js";
+import { ClusterRelay } from "./ClusterRelay.js";
+import { ClusterProbeAggregator } from "./ClusterProbeAggregator.js";
+/** Logger des composants cluster — aligné sur `ClusterManager`/`Relay`/`Aggregator`. */
+export type ClusterLog = (msg: string, severity?: Severity) => void;
+/** Poignées du process master, conservées par l'appelant (référence vivante). */
+export interface ClusterMasterHandles {
+    /** Superviseur fork/respawn/graceful shutdown. */
+    manager: ClusterManager;
+    /** Gateway IPC : fan-out des publications realtime cross-process. */
+    relay: ClusterRelay;
+    /** Agrégateur de sondes (vue pod, push) — `null` si `NF_CLUSTER_PROBE=0`. */
+    probes: ClusterProbeAggregator | null;
+}
+/**
+ * Démarre le process MASTER d'un cluster multi-worker — bootstrap partagé par les
+ * commandes de lancement (`cluster` et `production`).
+ *
+ * Le master ne sert **aucun HTTP** : il est superviseur + gateway IPC. Il
+ * 1. marque `NF_CLUSTER=1` (hérité au fork → le module Framework branche le
+ *    ClusterBackplane sur son RealtimeHub),
+ * 2. branche le {@link ClusterRelay} (fan-out realtime cross-process intra-pod) et,
+ *    sauf `NF_CLUSTER_PROBE=0`, le {@link ClusterProbeAggregator} (vue pod, push),
+ * 3. fork N workers via {@link ClusterManager} (respawn backoff + graceful shutdown).
+ *
+ * Les handlers `fork`/`exit` GLOBAUX couvrent forks initiaux ET respawns → un worker
+ * relancé est (ré)attaché. Attachés AVANT `manager.start()` (aucun fork manqué).
+ *
+ * ⚠️ À appeler uniquement quand `cluster.isPrimary` ET `workers >= 2` (le mono-process
+ * `workers: 1` ne passe jamais par ici — zéro machinerie cluster).
+ *
+ * @param opts.workers - nombre de workers à forker (déjà résolu, `>= 2`).
+ * @param opts.log - logger (msg + sévérité).
+ * @returns les poignées vivantes (manager/relay/probes) à conserver par l'appelant.
+ */
+export declare function startClusterMaster(opts: {
+    workers: number;
+    log: ClusterLog;
+}): ClusterMasterHandles;

package/dist/types/service/cluster/clusterMessage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Protocole de fil IPC du cluster Nodefony (mode sans PM2).
+ *
+ * Le master est le **gateway** : tout message worker↔worker transite par lui via IPC
+ * (`process.send` côté worker / `worker.send` côté master). Ce canal IPC est **partagé**
+ * par plusieurs usages (publications realtime, et — Phase 4 — remontées de sondes à
+ * agréger). Un **discriminant `kind`** permet à chaque consommateur (relay realtime,
+ * agrégateur de sondes) de ne traiter que ce qui le concerne.
+ *
+ * Ce protocole vit dans le **core** (et non dans `@nodefony/framework`) car le gateway
+ * est un composant core et le core est la dépendance commune : le worker realtime
+ * (`ClusterBackplane`, framework) importe `CLUSTER_RT_KIND` d'ici via `"nodefony"`, le
+ * master (`ClusterRelay`, core) l'utilise aussi → **une seule source**, pas de magic
+ * string dupliqué (anti-drift).
+ */
+/**
+ * `kind` d'une publication **realtime** (port `IBackplane`). Le {@link "./ClusterRelay"}
+ * rebroadcast ces messages aux **autres** workers ; le `ClusterBackplane` (framework)
+ * les produit/consomme.
+ */
+export declare const CLUSTER_RT_KIND: "nf:rt";
+/**
+ * `kind` d'une **remontée de sonde** worker → master (Phase 4c). Chaque worker envoie
+ * périodiquement sa santé per-instance (opaque pour le master) ; le
+ * {@link "./ClusterProbeAggregator"} les collecte. Le {@link "./ClusterRelay"} IGNORE
+ * ce kind (ce n'est pas une publication realtime à rebroadcaster).
+ */
+export declare const CLUSTER_PROBE_KIND: "nf:probe";
+/**
+ * `kind` du **snapshot agrégé** master → workers (Phase 4c). Le master diffuse
+ * périodiquement la liste des sondes de TOUS les workers (`{ ts, instances }`) ; chaque
+ * worker la met en cache pour servir la vue POD sur son endpoint santé (push, pas pull).
+ */
+export declare const CLUSTER_PROBE_SNAPSHOT_KIND: "nf:probe:snap";
+/**
+ * `kind` d'un **ordre d'enrichissement** worker → master (Phase 2 drill-down). Un worker
+ * (celui qui tient la connexion navigateur) demande au master d'activer/couper la sonde
+ * **riche** (GC/heap-spaces/handles/ELU/ctx — cf `RichProcessProbe`) sur le worker `pid`
+ * ciblé. Routé par le {@link "./ClusterProbeAggregator"} vers ce worker via {@link
+ * CLUSTER_PROBE_ENRICH_KIND}. « On paie ce qu'on regarde » : aucun rich produit hors drill.
+ */
+export declare const CLUSTER_PROBE_CTL_KIND: "nf:probe:ctl";
+/**
+ * `kind` de l'**ordre ciblé** master → worker (Phase 2 drill-down). Dit au worker
+ * d'inclure (ou non) son blob de sonde **riche** dans son report périodique
+ * (`CLUSTER_PROBE_KIND`). Le rich voyage ensuite dans le snapshot agrégé EXISTANT
+ * (aucun nouveau flux de données — juste un champ `rich` de plus pour ce worker).
+ */
+export declare const CLUSTER_PROBE_ENRICH_KIND: "nf:probe:enrich";
+/**
+ * **Facette** de sonde riche ciblée par un ordre d'enrichissement (drill-down) :
+ *  - `"process"` : sonde process riche (GC/heap-spaces/handles/ELU/ctx — `RichProcessProbe`) ;
+ *  - `"orm"` : sonde ORM riche (diagnostic connexions + flux — `connection/health` + `flow`).
+ *
+ * Indépendantes : un worker peut être enrichi sur l'une, l'autre, ou les deux à la fois (deux
+ * pages de drill distinctes). « On paie ce qu'on regarde » par sonde — activer le drill ORM
+ * n'allume PAS la sonde process (et inversement). Absente sur le fil ⇒ `"process"` (rétro-compat).
+ */
+export type ClusterProbeFacet = "process" | "orm";
+/**
+ * Base de tout message du protocole IPC cluster — seul le `kind` est imposé. Les autres
+ * champs sont opaques pour le master (il route/agrège sans les inspecter).
+ */
+export interface IClusterMessage {
+    readonly kind: string;
+}
+/**
+ * Ordre d'enrichissement (worker → master, {@link CLUSTER_PROBE_CTL_KIND}). `op` =
+ * `"enrich"` (activer) | `"stop"` (couper) ; `pid` = worker à (dés)enrichir ; `facet` =
+ * quelle sonde riche cibler (défaut `"process"` si absent → rétro-compat supervision).
+ */
+export interface IClusterProbeCtl extends IClusterMessage {
+    readonly kind: typeof CLUSTER_PROBE_CTL_KIND;
+    readonly op: "enrich" | "stop";
+    readonly pid: number;
+    readonly facet?: ClusterProbeFacet;
+}
+/**
+ * Ordre ciblé (master → worker, {@link CLUSTER_PROBE_ENRICH_KIND}). `enabled` = le worker
+ * doit-il joindre sa sonde riche à ses prochains reports ; `facet` = laquelle (défaut
+ * `"process"`).
+ */
+export interface IClusterProbeEnrich extends IClusterMessage {
+    readonly kind: typeof CLUSTER_PROBE_ENRICH_KIND;
+    readonly enabled: boolean;
+    readonly facet?: ClusterProbeFacet;
+}
+/** Type-guard d'un {@link IClusterProbeCtl} — narrowing sûr du canal IPC partagé. */
+export declare function isClusterProbeCtl(m: unknown): m is IClusterProbeCtl;
+/** Type-guard d'un {@link IClusterProbeEnrich} — narrowing sûr du canal IPC partagé. */
+export declare function isClusterProbeEnrich(m: unknown): m is IClusterProbeEnrich;
+/** Type-guard d'un message IPC cluster — narrowing sûr d'un message `unknown` du canal partagé. */
+export declare function isClusterMessage(m: unknown): m is IClusterMessage;
+export default CLUSTER_RT_KIND;

package/dist/types/service/cluster/cpuQuota.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lecteur de fichier système — abstrait pour rendre la résolution cgroup testable
+ * sans conteneur. Retourne le contenu du fichier, ou `null` si absent / illisible.
+ */
+export type FileReader = (path: string) => string | null;
+/**
+ * Lit le quota CPU effectif depuis les cgroups Linux — cgroup v2 (`cpu.max`) puis
+ * v1 (`cpu.cfs_quota_us` / `cpu.cfs_period_us`).
+ *
+ * C'est LA correction du bug de l'ancien cluster JS : `os.cpus().length` lit l'hôte
+ * (ex. 64 cœurs) et IGNORE la limite cgroup du conteneur (ex. 2 cœurs) → fork de 64
+ * workers throttlés + OOM. Le quota cgroup est la seule source de vérité en conteneur.
+ *
+ * @param read - lecteur de fichier injectable (tests). Défaut : `fs.readFileSync`.
+ * @returns le nombre de cœurs alloués (fractionnaire possible, ex. `0.5`, `2.5`), ou
+ *   `null` si illimité (`max`) / cgroup absent (hors conteneur ou non-Linux).
+ */
+export declare function readCgroupCpuQuota(read?: FileReader): number | null;
+/** Options de {@link resolveWorkerCount} — tous les seams sont injectables pour les tests. */
+export interface ResolveWorkerOptions {
+    /** `--workers N` explicite. Prioritaire et NON borné (harnais : forker plus de workers que de cœurs pour tester le backplane). */
+    requested?: number;
+    /** Quota cgroup pré-calculé (tests). Si omis → lecture cgroup réelle. `null` = illimité. */
+    cgroupQuota?: number | null;
+    /** Parallélisme schedulable (tests). Défaut : `os.availableParallelism()`. */
+    availableParallelism?: number;
+}
+/**
+ * Résout le nombre de workers à forker, dans l'ordre de priorité :
+ *
+ * 1. `requested` explicite (`--workers N`) si `> 0` — honoré **tel quel**, jamais borné.
+ * 2. Quota CPU cgroup (conteneur) → arrondi au plus proche, borné par le parallélisme schedulable.
+ * 3. `os.availableParallelism()` (Node 19+, respecte l'affinité CPU) — fallback hors conteneur.
+ *
+ * @returns un entier `>= 1` (jamais 0).
+ */
+export declare function resolveWorkerCount(opts?: ResolveWorkerOptions): number;

package/dist/types/service/cluster/instanceProbe.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Contrats de **santé per-instance NON realtime** (ORM + erreurs) qui voyagent dans le
+ * report de sonde cluster, à côté de {@link IProcessHealth} (process) et de la sonde de la
+ * socket. Généralise l'agrégation pod « aux 3 sondes » (process / socket / ORM+erreurs) sans
+ * toucher au `ClusterProbeAggregator` (opaque) : on enrichit juste le colis remonté par chaque
+ * worker, le merge pod les somme → « santé du framework » complète par pod.
+ *
+ * **Dépendance propre** : ces contrats vivent dans le CORE (comme `IProcessHealth`) →
+ * `@nodefony/framework` (assemble le report) et `@nodefony/orm-core` (produit la lecture lean)
+ * partagent UNE source de vérité sans dépendre l'un de l'autre. La lecture ORM réelle est
+ * branchée par le **driver** via {@link setOrmHealthProvider} (seam, comme `setClusterProbeClient`).
+ */
+/**
+ * Santé ORM **agrégée per-instance** (lean) — somme process-wide de tous les connecteurs
+ * enregistrés, dérivée des singletons `queryFlowMonitor` + `connectionMonitor` (0 ping, 0
+ * `toSQL`, O(N connecteurs)). Rejoint le report de sonde du worker à chaque tick (≥ 1 s).
+ * Tous les cumuls sont **monotones** → débit/s dérivé côté lecteur (delta/ts, comme le CPU%).
+ */
+export interface IOrmLeanHealth {
+    /** Connecteurs ORM enregistrés (registre). */
+    connectors: number;
+    /** Connecteurs actuellement connectés (`isConnected()`). */
+    connected: number;
+    /**
+     * Parmi les connectés, ceux dont l'état est **SUPPOSÉ** et non constaté :
+     * leur adapter n'a aucun signal de cycle de vie à traduire (base embarquée,
+     * driver muet), donc « connecté » y veut seulement dire « la connexion a
+     * été ouverte et n'a pas été fermée ».
+     *
+     * Sans ce compte, une readiness ne peut pas distinguer un connecteur qu'on
+     * SAIT vivant d'un connecteur dont on ne sait rien — et c'est le second qui
+     * fait prendre les mauvaises décisions.
+     */
+    assumed: number;
+    /** Requêtes ORM cumulées, tous connecteurs (monotone ; 0 si flux OFF en prod). */
+    queryTotal: number;
+    /** Requêtes lentes cumulées (au-dessus du seuil `slowMs`) (monotone). */
+    slowTotal: number;
+    /** Erreurs de connexion ORM cumulées (monotone). */
+    errorTotal: number;
+    /** Reconnexions ORM cumulées (monotone). */
+    reconnectTotal: number;
+    /** Pire latence EWMA (ms) parmi les connecteurs (instantané), ou `null` si non observé. */
+    maxEwmaMs: number | null;
+}
+/**
+ * Santé **erreurs per-instance** — compteurs Syslog monotones (cf `Syslog.errorTotal` /
+ * `Syslog.criticTotal`). Permet une carte « erreurs par worker » + un taux d'erreur pod
+ * (delta côté lecteur). Lecture pure d'entiers, 0 scan du ring buffer.
+ */
+export interface IInstanceErrorHealth {
+    /** Logs ERROR/CRITIC/ALERT/EMERGENCY cumulés (sévérité 0–3) (monotone). */
+    errorTotal: number;
+    /** Sous-ensemble CRITIQUE : CRITIC/ALERT/EMERGENCY (sévérité 0–2) (monotone). */
+    criticTotal: number;
+}
+/**
+ * Branche (ou débranche avec `null`) le fournisseur de santé ORM lean. Idempotent
+ * (dernier gagne) — plusieurs drivers branchant la même fonction globale est sûr.
+ *
+ * @param fn - lecture lean de la santé ORM du process, ou `null` pour débrancher.
+ */
+export declare function setOrmHealthProvider(fn: (() => IOrmLeanHealth) | null): void;
+/**
+ * Lit la santé ORM lean du process via le fournisseur branché, ou `null` si aucun ORM
+ * n'est branché (le champ `orm` du report est alors omis). Lecture pure, jamais throw.
+ */
+export declare function readOrmHealth(): IOrmLeanHealth | null;
+/**
+ * Branche (ou débranche avec `null`) le fournisseur de diagnostic ORM riche. Idempotent
+ * (dernier gagne). Coût NUL hors drill : ce fournisseur n'est appelé que quand le master
+ * a demandé l'enrichissement ORM de CE worker.
+ *
+ * @param fn - producteur async du blob `{ health, flow }`, ou `null` pour débrancher.
+ */
+export declare function setOrmRichProvider(fn: (() => Promise<unknown>) | null): void;
+/**
+ * Appelle le fournisseur ORM riche branché (async), ou `null` si aucun driver ne l'a posé.
+ * Le résultat est un blob OPAQUE (forme connue de Studio seul). Ne throw pas pour son propre
+ * compte : la propagation d'un rejet du provider reste à l'appelant (qui catch dans son tick).
+ */
+export declare function readOrmRich(): Promise<unknown> | null;

package/dist/types/service/cluster/podEnvironment.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Détection de l'environnement d'orchestration (pod Kubernetes).
+ *
+ * Utilité : un driver de VUE local (logs `memory`/`file`/`cluster-file`, hub
+ * realtime `cluster`) ne couvre QUE le process/pod courant. En multi-pod, une vue
+ * globale exige une agrégation centralisée (Loki/OpenSearch pour les logs, Redis
+ * pour le realtime) — dont la destination est un secret d'infra fourni par
+ * l'environnement (12-factor), JAMAIS devinable depuis le process. Ce module sert
+ * donc à **avertir** l'opérateur, jamais à choisir un driver cross-pod à sa place.
+ */
+/**
+ * Indique si le process tourne dans un pod Kubernetes.
+ *
+ * Signal fiable et gratuit : le kubelet injecte `KUBERNETES_SERVICE_HOST` (+
+ * `KUBERNETES_SERVICE_PORT`) dans TOUT conteneur d'un pod — présence = k8s. Ne dit
+ * RIEN du nombre de replicas (un pod ignore ses pairs) : à consommer comme un
+ * indice « multi-pod POSSIBLE », pas comme un compte de pods.
+ *
+ * @param env - table d'environnement (défaut `process.env`) — injectable pour les tests.
+ * @returns `true` si des marqueurs Kubernetes sont présents.
+ */
+export declare function isInKubernetes(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Décide s'il faut AVERTIR que la vue des logs est limitée à un pod. Vrai quand on
+ * tourne en Kubernetes (multi-pod possible), que le driver de relecture actif est
+ * LOCAL (per-pod), et qu'AUCUNE destination d'agrégation cross-pod (Loki/OpenSearch)
+ * n'est configurée. Pur (aucun accès système) → testable ; prend le NOM du driver
+ * (string) pour interdire le piège du comparer-un-objet-driver (bug de type réel).
+ *
+ * @param inKubernetes - résultat de {@link isInKubernetes}.
+ * @param activeDriverName - nom du driver de relecture actif (`ILogDriver.name`).
+ * @param hasAggregation - une destination Loki/OpenSearch est configurée.
+ * @returns true si un avertissement « vue par pod » est pertinent.
+ */
+export declare function shouldWarnPerPodView(inKubernetes: boolean, activeDriverName: string | undefined, hasAggregation: boolean): boolean;

package/dist/types/service/cluster/processProbe.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Santé PROCESS d'un worker — lue par {@link ProcessProbe}, agrégée par worker dans le
+ * snapshot pod (cf `ClusterProbeAggregator`). Volontairement **lean** (sérialisée par
+ * worker à chaque tick de report ≥ 1 s) : juste de quoi peupler une grille « salle des
+ * machines » (1 carte/worker). Les sondes lourdes (GC, heap-spaces, ctx-switches) restent
+ * au canal `nodefony:supervision` per-process pour le drill-down.
+ */
+export interface IProcessHealth {
+    /** PID du worker (= instanceId de la vue pod). */
+    pid: number;
+    /** Uptime du process (secondes). */
+    uptime: number;
+    /** % d'UN cœur sur l'intervalle (comme `top` : un Node mono-thread sature ~100). */
+    cpuPercent: number;
+    /** Lag moyen de l'event-loop sur l'intervalle (ms) — blocage synchrone. */
+    eventLoopMs: number;
+    /** Saturation de la boucle (ELU) sur l'intervalle, 0–1 (~1 = thread saturé). */
+    eluUtilization: number;
+    /** Resident Set Size (octets). */
+    rss: number;
+    /** Heap V8 utilisé (octets). */
+    heapUsed: number;
+    /** Heap V8 total (octets). */
+    heapTotal: number;
+    /** Plafond heap V8 (octets, constant) — pour `heapUsed/heapLimit` (% avant OOM). */
+    heapLimit: number;
+    /** Mémoire hors-heap (buffers, etc.) (octets). */
+    external: number;
+    /** Horodatage de la mesure. */
+    ts: number;
+}
+/**
+ * Sonde PROCESS **stateful** d'un worker — calcule les métriques par INTERVALLE (CPU,
+ * event-loop lag, ELU sont des deltas entre 2 `read()`). Une instance par process worker.
+ *
+ * Perf (worker uniquement, JAMAIS hot path request) : `read()` appelé au tick de report
+ * (≥ 1 s) → 1 `process.cpuUsage()` + 1 `memoryUsage()` + lecture histogramme. Le monitor
+ * event-loop natif est **activé au 1ᵉʳ `read()`** (lazy — pas d'overhead « au cas où » à la
+ * simple construction) puis reset à chaque tick (lag moyen sur l'intervalle). SERVEUR
+ * uniquement (`node:perf_hooks`/`process`) → non importé par le bundle client.
+ */
+export declare class ProcessProbe {
+    #private;
+    /**
+     * Lit la santé process courante (métriques par intervalle depuis le dernier `read()`).
+     *
+     * @returns {@link IProcessHealth} prêt à être joint au report de sonde du worker.
+     */
+    read(): IProcessHealth;
+    /** Libère le monitor event-loop natif (à l'arrêt du worker). Idempotent. */
+    dispose(): void;
+}
+export default ProcessProbe;