nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/service/cluster/ClusterProbeAggregator.js

@@ -0,0 +1,120 @@
+import { CLUSTER_PROBE_ENRICH_KIND, CLUSTER_PROBE_SNAPSHOT_KIND, isClusterMessage, isClusterProbeCtl } from "./clusterMessage.js";
+//#region src/service/cluster/ClusterProbeAggregator.ts
+/**
+* **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).
+*/
+var ClusterProbeAggregator = class {
+	#workers = /* @__PURE__ */ new Map();
+	/** pid → worker (ciblage du drill-down Phase 2 ; le front identifie un worker par pid). */
+	#byPid = /* @__PURE__ */ new Map();
+	/** workerId → dernier payload de sonde (opaque). */
+	#probes = /* @__PURE__ */ new Map();
+	#intervalMs;
+	#log;
+	#timer = null;
+	#broadcastTotal = 0;
+	constructor(opts = {}) {
+		this.#intervalMs = opts.intervalMs ?? 2e3;
+		this.#log = opts.log ?? (() => {});
+	}
+	/** Nombre de workers rattachés. */
+	get size() {
+		return this.#workers.size;
+	}
+	/** Total de snapshots diffusés (sonde de la gateway). */
+	get broadcastTotal() {
+		return this.#broadcastTotal;
+	}
+	/**
+	* Rattache un worker : cible de diffusion + récepteur de ses remontées de sonde.
+	* Idempotent par `id` (un respawn réattache proprement).
+	*/
+	attach(worker) {
+		this.#workers.set(worker.id, worker);
+		this.#byPid.set(worker.pid, worker);
+		worker.onMessage((msg) => this.#collect(worker.id, msg));
+	}
+	/** Détache un worker (au `exit`) : il sort de l'agrégat. No-op s'il est déjà parti. */
+	detach(id) {
+		const w = this.#workers.get(id);
+		if (w) this.#byPid.delete(w.pid);
+		this.#workers.delete(id);
+		this.#probes.delete(id);
+	}
+	/**
+	* Traite un message d'un worker. Deux usages sur le canal partagé :
+	*  - **remontée de sonde** (`CLUSTER_PROBE_KIND`) → mémorise le dernier payload (opaque) ;
+	*  - **ordre d'enrichissement** (`CLUSTER_PROBE_CTL_KIND`, drill-down Phase 2) émis par le
+	*    worker qui tient le navigateur → **route ciblé** vers le worker `pid` concerné
+	*    (`CLUSTER_PROBE_ENRICH_KIND`). Le master ne lit toujours PAS le contenu d'une sonde
+	*    (opacité), il route juste l'ordre via la map pid→worker. Autres kinds / malformés ignorés.
+	*/
+	#collect(fromId, msg) {
+		if (isClusterProbeCtl(msg)) {
+			this.#byPid.get(msg.pid)?.send({
+				kind: CLUSTER_PROBE_ENRICH_KIND,
+				enabled: msg.op === "enrich",
+				facet: msg.facet ?? "process"
+			});
+			return;
+		}
+		if (!isClusterMessage(msg) || msg.kind !== "nf:probe") return;
+		this.#probes.set(fromId, msg.payload);
+	}
+	/** Démarre la diffusion périodique du snapshot agrégé. Idempotent. Timer `unref`. */
+	start() {
+		if (this.#timer !== null) return;
+		this.#log(`probe aggregator: diffusion snapshot toutes les ${this.#intervalMs}ms`, "DEBUG");
+		this.#timer = setInterval(() => this.broadcast(), this.#intervalMs);
+		this.#timer.unref?.();
+	}
+	/**
+	* 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() {
+		if (this.#workers.size === 0) return;
+		const snap = {
+			kind: CLUSTER_PROBE_SNAPSHOT_KIND,
+			ts: Date.now(),
+			instances: [...this.#probes.values()]
+		};
+		for (const w of this.#workers.values()) try {
+			w.send(snap);
+		} catch {}
+		this.#broadcastTotal += 1;
+	}
+	/** Arrête le timer de diffusion. Idempotent. */
+	stop() {
+		if (this.#timer !== null) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+	}
+	/** Vide l'agrégateur (arrêt du master). */
+	clear() {
+		this.stop();
+		this.#workers.clear();
+		this.#byPid.clear();
+		this.#probes.clear();
+	}
+};
+//#endregion
+export { ClusterProbeAggregator, ClusterProbeAggregator as default };

package/dist/node/service/cluster/ClusterRelay.js

@@ -0,0 +1,74 @@
+import { isClusterMessage } from "./clusterMessage.js";
+//#region src/service/cluster/ClusterRelay.ts
+/**
+* **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).
+*/
+var ClusterRelay = class {
+	#workers = /* @__PURE__ */ new Map();
+	#log;
+	#relayedTotal = 0;
+	constructor(opts = {}) {
+		this.#log = opts.log ?? (() => {});
+	}
+	/** Nombre de workers actuellement rattachés au relay. */
+	get size() {
+		return this.#workers.size;
+	}
+	/** Total des messages realtime rebroadcastés (sonde gateway). */
+	get relayedTotal() {
+		return this.#relayedTotal;
+	}
+	/**
+	* 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) {
+		this.#workers.set(worker.id, worker);
+		worker.onMessage((msg) => this.#route(worker.id, msg));
+		this.#log(`relay: worker ${worker.id} attaché au fan-out (${this.#workers.size} au total)`, "DEBUG");
+	}
+	/** Détache un worker (au `exit`). No-op s'il est déjà parti. */
+	detach(id) {
+		this.#workers.delete(id);
+	}
+	/**
+	* Route un message reçu du worker `fromId` : si c'est une publication realtime, la
+	* rebroadcast à tous les **autres** workers vivants. Sinon, ignore (autre kind /
+	* malformé). N'alloue rien sur le chemin (réutilise le message IPC tel quel).
+	*/
+	#route(fromId, msg) {
+		if (!isClusterMessage(msg) || msg.kind !== "nf:rt") return;
+		for (const [id, w] of this.#workers) {
+			if (id === fromId) continue;
+			try {
+				w.send(msg);
+			} catch {}
+		}
+		this.#relayedTotal += 1;
+	}
+	/** Vide le relay (arrêt du master). Les workers sont tués par le ClusterManager. */
+	clear() {
+		this.#workers.clear();
+	}
+};
+//#endregion
+export { ClusterRelay, ClusterRelay as default };

package/dist/node/service/cluster/clusterMaster.js

@@ -0,0 +1,65 @@
+import { ClusterManager } from "./ClusterManager.js";
+import { ClusterRelay } from "./ClusterRelay.js";
+import { ClusterProbeAggregator } from "./ClusterProbeAggregator.js";
+import cluster from "node:cluster";
+//#region src/service/cluster/clusterMaster.ts
+/**
+* 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.
+*/
+function startClusterMaster(opts) {
+	const { workers, log } = opts;
+	process.title = `nodefony master [cluster ${workers}w]`;
+	process.env.NF_CLUSTER = "1";
+	const relay = new ClusterRelay({ log });
+	const probes = process.env.NF_CLUSTER_PROBE !== "0" ? new ClusterProbeAggregator({ log }) : null;
+	cluster.on("fork", (w) => {
+		const handle = {
+			id: w.id,
+			pid: w.process?.pid ?? -1,
+			send: (m) => {
+				try {
+					w.send(m);
+				} catch {}
+			},
+			onMessage: (cb) => w.on("message", cb)
+		};
+		relay.attach(handle);
+		probes?.attach(handle);
+	});
+	cluster.on("exit", (w) => {
+		relay.detach(w.id);
+		probes?.detach(w.id);
+	});
+	probes?.start();
+	const manager = new ClusterManager({
+		workers,
+		log
+	});
+	manager.start();
+	manager.installSignalHandlers();
+	return {
+		manager,
+		relay,
+		probes
+	};
+}
+//#endregion
+export { startClusterMaster };

package/dist/node/service/cluster/clusterMessage.js

@@ -0,0 +1,70 @@
+//#region src/service/cluster/clusterMessage.ts
+/**
+* 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.
+*/
+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).
+*/
+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).
+*/
+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.
+*/
+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).
+*/
+const CLUSTER_PROBE_ENRICH_KIND = "nf:probe:enrich";
+/** `true` si `f` est une facette valide ou absente (absente ⇒ défaut `"process"`). */
+function isValidFacet(f) {
+	return f === void 0 || f === "process" || f === "orm";
+}
+/** Type-guard d'un {@link IClusterProbeCtl} — narrowing sûr du canal IPC partagé. */
+function isClusterProbeCtl(m) {
+	if (!isClusterMessage(m) || m.kind !== "nf:probe:ctl") return false;
+	const c = m;
+	return (c.op === "enrich" || c.op === "stop") && typeof c.pid === "number" && isValidFacet(c.facet);
+}
+/** Type-guard d'un {@link IClusterProbeEnrich} — narrowing sûr du canal IPC partagé. */
+function isClusterProbeEnrich(m) {
+	return isClusterMessage(m) && m.kind === "nf:probe:enrich" && typeof m.enabled === "boolean" && isValidFacet(m.facet);
+}
+/** Type-guard d'un message IPC cluster — narrowing sûr d'un message `unknown` du canal partagé. */
+function isClusterMessage(m) {
+	return typeof m === "object" && m !== null && typeof m.kind === "string";
+}
+//#endregion
+export { CLUSTER_PROBE_CTL_KIND, CLUSTER_PROBE_ENRICH_KIND, CLUSTER_PROBE_KIND, CLUSTER_PROBE_SNAPSHOT_KIND, CLUSTER_RT_KIND, CLUSTER_RT_KIND as default, isClusterMessage, isClusterProbeCtl, isClusterProbeEnrich };

package/dist/node/service/cluster/cpuQuota.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import os from "node:os";
+//#region src/service/cluster/cpuQuota.ts
+/** Lecteur par défaut : lecture synchrone, `null` au lieu de throw (fichier cgroup absent hors conteneur). */
+const defaultRead = (path) => {
+	try {
+		return fs.readFileSync(path, "utf8");
+	} catch {
+		return 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).
+*/
+function readCgroupCpuQuota(read = defaultRead) {
+	const v2 = read("/sys/fs/cgroup/cpu.max");
+	if (v2 !== null) {
+		const [quota, period] = v2.trim().split(/\s+/);
+		if (quota === "max") return null;
+		const q = Number(quota);
+		const p = Number(period);
+		return q > 0 && p > 0 ? q / p : null;
+	}
+	const quotaStr = read("/sys/fs/cgroup/cpu/cpu.cfs_quota_us");
+	const periodStr = read("/sys/fs/cgroup/cpu/cpu.cfs_period_us");
+	if (quotaStr !== null && periodStr !== null) {
+		const q = Number(quotaStr.trim());
+		const p = Number(periodStr.trim());
+		if (q > 0 && p > 0) return q / p;
+	}
+	return null;
+}
+/**
+* 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).
+*/
+function resolveWorkerCount(opts = {}) {
+	if (opts.requested !== void 0 && Number.isFinite(opts.requested) && opts.requested > 0) return Math.max(1, Math.floor(opts.requested));
+	const parallelism = opts.availableParallelism ?? os.availableParallelism();
+	const quota = opts.cgroupQuota !== void 0 ? opts.cgroupQuota : readCgroupCpuQuota();
+	if (quota !== null && quota > 0) return Math.max(1, Math.min(Math.round(quota), parallelism));
+	return Math.max(1, parallelism);
+}
+//#endregion
+export { readCgroupCpuQuota, resolveWorkerCount };

package/dist/node/service/cluster/instanceProbe.js

@@ -0,0 +1,52 @@
+//#region src/service/cluster/instanceProbe.ts
+/**
+* Seam ORM : fournisseur de la santé ORM lean du process. Branché par le **module driver**
+* (Drizzle/Mongoose) à son boot ; lu par l'assembleur du report (framework).
+* `null` par défaut → 0 coût et `readOrmHealth()` renvoie `null` (pas d'ORM → champ omis).
+*/
+let _ormHealthProvider = null;
+/**
+* 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.
+*/
+function setOrmHealthProvider(fn) {
+	_ormHealthProvider = fn;
+}
+/**
+* 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.
+*/
+function readOrmHealth() {
+	return _ormHealthProvider?.() ?? null;
+}
+/**
+* Seam ORM **riche** (drill-down @pid) : fournisseur du diagnostic ORM complet du process
+* (par connecteur : ping/latence/stockage/pool via `connection/health` + flux requêtes via
+* `flow`). **Opaque** côté core/framework (qui ne font que le transporter) — seul le
+* consommateur (Studio) connaît la forme `{ health, flow }`. **Async** (le `connection/health`
+* émet un ping) — branché par le **driver** (Drizzle) à son boot, lu par le worker UNIQUEMENT
+* pendant un drill (« on paie ce qu'on regarde »). `null` par défaut → 0 coût.
+*/
+let _ormRichProvider = 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.
+*/
+function setOrmRichProvider(fn) {
+	_ormRichProvider = fn;
+}
+/**
+* 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).
+*/
+function readOrmRich() {
+	return _ormRichProvider?.() ?? null;
+}
+//#endregion
+export { readOrmHealth, readOrmRich, setOrmHealthProvider, setOrmRichProvider };

package/dist/node/service/cluster/podEnvironment.js

@@ -0,0 +1,48 @@
+//#region src/service/cluster/podEnvironment.ts
+/**
+* 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.
+*/
+function isInKubernetes(env = process.env) {
+	return Boolean(env.KUBERNETES_SERVICE_HOST || env.KUBERNETES_SERVICE_PORT);
+}
+/** Drivers de relecture LOCAUX (per-pod) : ne couvrent que le process courant. */
+const LOCAL_VIEW_DRIVERS = /* @__PURE__ */ new Set([
+	"memory",
+	"file",
+	"cluster-file"
+]);
+/**
+* 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.
+*/
+function shouldWarnPerPodView(inKubernetes, activeDriverName, hasAggregation) {
+	return inKubernetes && !hasAggregation && LOCAL_VIEW_DRIVERS.has(activeDriverName ?? "");
+}
+//#endregion
+export { isInKubernetes, shouldWarnPerPodView };

package/dist/node/service/cluster/processProbe.js

@@ -0,0 +1,70 @@
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+import v8 from "node:v8";
+//#region src/service/cluster/processProbe.ts
+const HEAP_LIMIT = v8.getHeapStatistics().heap_size_limit;
+/**
+* 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.
+*/
+var ProcessProbe = class {
+	#prevCpu = process.cpuUsage();
+	#prevTs = Date.now();
+	#prevElu = performance.eventLoopUtilization();
+	#eld = monitorEventLoopDelay({ resolution: 20 });
+	#enabled = false;
+	/**
+	* 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() {
+		if (!this.#enabled) {
+			this.#eld.enable();
+			this.#enabled = true;
+		}
+		const now = Date.now();
+		const cur = process.cpuUsage();
+		const userDelta = cur.user - this.#prevCpu.user;
+		const sysDelta = cur.system - this.#prevCpu.system;
+		const elapsedMs = Math.max(now - this.#prevTs, 1);
+		this.#prevCpu = cur;
+		this.#prevTs = now;
+		const cpuPercent = Math.min(100, Math.round((userDelta + sysDelta) / 1e3 / elapsedMs * 100));
+		const mean = this.#eld.mean;
+		const eventLoopMs = Number.isFinite(mean) ? Math.round(mean / 1e6 * 100) / 100 : 0;
+		this.#eld.reset();
+		const curElu = performance.eventLoopUtilization();
+		const eluDelta = performance.eventLoopUtilization(curElu, this.#prevElu);
+		this.#prevElu = curElu;
+		const elu = Number.isFinite(eluDelta.utilization) ? Math.round(eluDelta.utilization * 1e3) / 1e3 : 0;
+		const mem = process.memoryUsage();
+		return {
+			pid: process.pid,
+			uptime: Math.round(process.uptime()),
+			cpuPercent,
+			eventLoopMs,
+			eluUtilization: elu,
+			rss: mem.rss,
+			heapUsed: mem.heapUsed,
+			heapTotal: mem.heapTotal,
+			heapLimit: HEAP_LIMIT,
+			external: mem.external,
+			ts: now
+		};
+	}
+	/** Libère le monitor event-loop natif (à l'arrêt du worker). Idempotent. */
+	dispose() {
+		if (this.#enabled) {
+			this.#eld.disable();
+			this.#enabled = false;
+		}
+	}
+};
+//#endregion
+export { ProcessProbe, ProcessProbe as default };

package/dist/node/service/cluster/richProcessProbe.js

@@ -0,0 +1,115 @@
+import os from "node:os";
+import { PerformanceObserver, constants, performance } from "node:perf_hooks";
+import v8 from "node:v8";
+//#region src/service/cluster/richProcessProbe.ts
+/**
+* Sonde process **riche stateful** d'un worker — calcule les métriques par INTERVALLE
+* (GC, ELU active/idle, changements de contexte sont des deltas entre deux `read()`).
+* Une instance par process worker, **lazy & opt-in** : créée seulement quand un drill
+* est actif sur ce worker (« on paie ce qu'on regarde »).
+*
+* Perf (worker uniquement, JAMAIS hot path request) : l'observer GC n'est attaché qu'à
+* {@link enable} (1ᵉʳ `read()` sinon) et **détaché à {@link disable}** (aucun listener
+* orphelin). Les sondes lourdes (`getHeapSpaceStatistics`, `getActiveResourcesInfo`,
+* `getrusage`) ne tournent qu'au `read()` (au tick de report, ≥ 1 s). SERVEUR uniquement
+* (`node:v8`/`node:perf_hooks`/`node:os`) → non importé par le bundle client.
+*
+* Logique portée de `createStatsTicker` (`@nodefony/studio`) en classe réutilisable :
+* source unique de la sonde process riche, partagée par le drill cluster et la
+* supervision mono-process.
+*/
+var RichProcessProbe = class {
+	#heapLimit = v8.getHeapStatistics().heap_size_limit;
+	#cpuCount = os.cpus().length || 1;
+	#prevElu = performance.eventLoopUtilization();
+	#prevRu = process.resourceUsage();
+	#gcObs = null;
+	#gcCount = 0;
+	#gcPauseMs = 0;
+	#gcMajor = 0;
+	#gcMinor = 0;
+	#enabled = false;
+	/**
+	* Attache l'observer GC et réinitialise les baselines de delta (ELU/ctx). Idempotent.
+	* Appelé automatiquement au 1ᵉʳ `read()` ; explicite pour démarrer la collecte GC tôt.
+	*/
+	enable() {
+		if (this.#enabled) return;
+		this.#enabled = true;
+		this.#prevElu = performance.eventLoopUtilization();
+		this.#prevRu = process.resourceUsage();
+		this.#gcCount = this.#gcPauseMs = this.#gcMajor = this.#gcMinor = 0;
+		this.#gcObs = new PerformanceObserver((list) => {
+			for (const e of list.getEntries()) {
+				this.#gcCount += 1;
+				this.#gcPauseMs += e.duration;
+				const kind = e.detail?.kind;
+				if (kind === constants.NODE_PERFORMANCE_GC_MAJOR) this.#gcMajor += 1;
+				else if (kind === constants.NODE_PERFORMANCE_GC_MINOR) this.#gcMinor += 1;
+			}
+		});
+		try {
+			this.#gcObs.observe({ entryTypes: ["gc"] });
+		} catch {}
+	}
+	/**
+	* Lit la sonde riche courante (deltas depuis le dernier `read()`, snapshots heap/handles).
+	*
+	* @returns {@link IProcessRich} prêt à être joint au report du worker drillé.
+	*/
+	read() {
+		if (!this.#enabled) this.enable();
+		const gc = {
+			count: this.#gcCount,
+			pauseMs: Math.round(this.#gcPauseMs * 100) / 100,
+			major: this.#gcMajor,
+			minor: this.#gcMinor
+		};
+		this.#gcCount = this.#gcPauseMs = this.#gcMajor = this.#gcMinor = 0;
+		const heapSpaces = v8.getHeapSpaceStatistics().map((s) => ({
+			name: s.space_name,
+			used: s.space_used_size,
+			size: s.space_size
+		}));
+		const resources = process.getActiveResourcesInfo();
+		const byType = Object.create(null);
+		for (const r of resources) byType[r] = (byType[r] ?? 0) + 1;
+		const curElu = performance.eventLoopUtilization();
+		const eluDelta = performance.eventLoopUtilization(curElu, this.#prevElu);
+		this.#prevElu = curElu;
+		const elu = {
+			active: Number.isFinite(eluDelta.active) ? Math.round(eluDelta.active * 100) / 100 : 0,
+			idle: Number.isFinite(eluDelta.idle) ? Math.round(eluDelta.idle * 100) / 100 : 0
+		};
+		const ru = process.resourceUsage();
+		const ctx = {
+			voluntary: ru.voluntaryContextSwitches - this.#prevRu.voluntaryContextSwitches,
+			involuntary: ru.involuntaryContextSwitches - this.#prevRu.involuntaryContextSwitches
+		};
+		this.#prevRu = ru;
+		return {
+			gc,
+			heapSpaces,
+			handles: {
+				total: resources.length,
+				byType
+			},
+			elu,
+			ctx,
+			loadavg: os.loadavg(),
+			heapLimit: this.#heapLimit,
+			cpuCount: this.#cpuCount,
+			ts: Date.now()
+		};
+	}
+	/** Détache l'observer GC (fin du drill / arrêt du worker). Idempotent. */
+	disable() {
+		if (this.#gcObs !== null) {
+			this.#gcObs.disconnect();
+			this.#gcObs = null;
+		}
+		this.#enabled = false;
+	}
+};
+//#endregion
+export { RichProcessProbe, RichProcessProbe as default };