nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/runtime/pageQuery.js

@@ -0,0 +1,160 @@
+import nodefonyError from "../Error.js";
+//#region src/runtime/pageQuery.ts
+/**
+* Erreur d'une requête de page mal formée ou non honorable par le point
+* d'entrée : `order` sur un endpoint qui ne trie pas, champ hors allowlist,
+* sens de tri inconnu.
+*
+* `code = 400` : la faute est au client. Le data plane admin
+* (`AdminApiController`) traduit ce `code` en statut HTTP, comme il le fait
+* déjà pour {@link PaginationModeError}.
+*/
+var PageQueryError = class extends nodefonyError {
+	constructor(message) {
+		super(message, 400);
+	}
+};
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+/**
+* Les clés que le contrat de page revendique sur le fil — **source unique**.
+*
+* Elle existe pour un consommateur : `parseFilters`, qui doit distinguer un
+* paramètre de pagination d'un filtre inconnu, et refuse le second. Recopier
+* cette liste là-bas aurait suffi à ce qu'un `?tenantId=` légitime devienne un
+* `400` le jour où le contrat gagne une clé ici et pas là.
+*
+* `tenantId` y figure bien qu'il ne soit pas encore lu (réserve multi-tenant du
+* contrat, `IPageQuery.tenantId`) : le front l'émet déjà sur les sessions.
+*/
+const PAGE_QUERY_KEYS = /* @__PURE__ */ new Set([
+	"limit",
+	"offset",
+	"cursor",
+	"order",
+	"withTotal",
+	"q",
+	"tenantId"
+]);
+/**
+* **La** lecture d'une valeur unique dans une source de page — partagée par
+* {@link parsePageQuery} et `parseFilters`.
+*
+* Une {@link PageQuerySource} peut porter plusieurs valeurs par clé (query
+* string répétée, tableau JSON d'un corps `QUERY`) : c'est le polymorphisme du
+* transport. Aucun des deux lecteurs ne sait quoi faire d'une seconde valeur —
+* ni le contrat de page, ni une spec de filtre n'expriment l'appartenance à un
+* ensemble. Prendre la première et **jeter les autres en silence** rendait une
+* page filtrée sur `a` à qui avait demandé `a` **et** `b`, sans rien dire : la
+* faute exacte que ce contrat bannit partout ailleurs.
+*
+* D'où le refus. Le jour où un point d'entrée doit accepter plusieurs valeurs,
+* ce sera une nature de filtre déclarée (`["in", …]`), pas une tolérance
+* implicite du lecteur.
+*
+* @throws {@link PageQueryError} (`400`) si la clé porte plus d'une valeur.
+*/
+const singleValue = (source, key) => {
+	const value = source[key];
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) return value;
+	if (value.length > 1) throw new PageQueryError(`Parameter "${key}" was given ${value.length} values; this endpoint reads a single value per parameter.`);
+	return value[0];
+};
+/** Alias interne — la lecture unique, sous le nom court du fichier. */
+const one = singleValue;
+/** Entier décimal strict — `undefined` si absent, vide ou non numérique. */
+const int = (source, key) => {
+	const raw = one(source, key);
+	if (raw === void 0 || raw === "") return void 0;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) ? n : void 0;
+};
+/**
+* Lit le tri `champ:sens[,champ:sens]*` et le valide contre l'allowlist.
+*
+* @throws {@link PageQueryError} si l'endpoint ne trie pas, si un champ n'est
+*   pas dans `sortable`, ou si un sens n'est ni `ASC` ni `DESC`.
+*/
+const parseOrder = (raw, sortable) => {
+	if (!sortable || sortable.length === 0) throw new PageQueryError(`This endpoint does not support sorting; drop the "order" parameter.`);
+	const order = [];
+	for (const part of raw.split(",")) {
+		const spec = part.trim();
+		if (spec === "") continue;
+		const sep = spec.lastIndexOf(":");
+		const field = sep === -1 ? spec : spec.slice(0, sep);
+		const rawDir = sep === -1 ? "ASC" : spec.slice(sep + 1);
+		if (!sortable.includes(field)) throw new PageQueryError(`Unsortable field "${field}". Sortable fields: ${sortable.join(", ")}.`);
+		const dir = rawDir.toUpperCase();
+		if (dir !== "ASC" && dir !== "DESC") throw new PageQueryError(`Invalid sort direction "${rawDir}" for field "${field}" (expected ASC or DESC).`);
+		order.push([field, dir]);
+	}
+	return order.length ? order : void 0;
+};
+/**
+* **Le** traducteur d'une requête de page : transforme une source clé→valeur en
+* {@link IPageQuery} borné et validé. Fonction **pure** — aucun accès au kernel,
+* à l'ALS ni à la requête HTTP.
+*
+* Il remplace les parseurs `limit`/`offset` que chaque data plane réécrivait
+* pour lui-même. Ces copies avaient déjà divergé (`Number.isNaN` d'un côté,
+* `Number.isFinite` de l'autre : `?limit=abc` bornait à `50` ici et plantait à
+* `NaN` là), et aucune ne validait le tri.
+*
+* Ce qui est lu, et rien d'autre — un paramètre inconnu est laissé à l'appelant,
+* qui compose ses propres filtres par-dessus (`interface XQuery extends
+* IPageQuery`) :
+*
+* | Paramètre    | Forme sur le fil            | Résultat                                    |
+* | ------------ | --------------------------- | ------------------------------------------- |
+* | `limit`      | `?limit=20`                 | borné à `[1, maxLimit]`, défaut `defaultLimit` |
+* | `offset`     | `?offset=40`                | `≥ 0` (négatif ou invalide → absent)        |
+* | `cursor`     | `?cursor=abc`               | posé si non vide                            |
+* | `order`      | `?order=name:ASC,age:DESC`  | validé contre `sortable`                    |
+* | `withTotal`  | `?withTotal=false`          | posé **seulement** si `false` (défaut `true`) |
+* | `q`          | `?q=jean`                   | trimé, posé si non vide — **refusé** sans `searchable` |
+*
+* `offset` et `cursor` peuvent tous deux être présents ici : ce n'est pas à ce
+* traducteur d'arbitrer, mais au store, qui seul connaît son mode — il l'énonce
+* en appelant `assertPageQuery(query, mode)` en première ligne de son `listPage`.
+*
+* @param source - la query string parsée, ou le corps d'une requête `QUERY`.
+* @param options - bornes et champs triables de ce point d'entrée.
+* @returns une requête de page conforme au contrat, prête pour un store.
+* @throws {@link PageQueryError} (`code` 400) si le tri demandé n'est pas
+*   honorable par ce point d'entrée.
+*
+* @example
+* ```ts
+* const query = parsePageQuery(request.query, {
+*   maxLimit: 200,
+*   sortable: ["username", "createdAt"],
+* });
+* return repository.listPage({ ...query, enabled: true });
+* ```
+*/
+function parsePageQuery(source, options = {}) {
+	const maxLimit = options.maxLimit ?? MAX_LIMIT;
+	const defaultLimit = Math.min(options.defaultLimit ?? DEFAULT_LIMIT, maxLimit);
+	const rawLimit = int(source, "limit");
+	const query = { limit: rawLimit === void 0 ? defaultLimit : Math.min(Math.max(rawLimit, 1), maxLimit) };
+	const offset = int(source, "offset");
+	if (offset !== void 0 && offset >= 0) query.offset = offset;
+	const cursor = one(source, "cursor");
+	if (cursor) query.cursor = cursor;
+	const rawOrder = one(source, "order");
+	if (rawOrder) {
+		const order = parseOrder(rawOrder, options.sortable);
+		if (order) query.order = order;
+	}
+	if (one(source, "withTotal") === "false") query.withTotal = false;
+	const q = one(source, "q")?.trim();
+	if (q) {
+		if (!options.searchable) throw new PageQueryError("This endpoint does not support full-text search (\"q\"). Use the declared filters instead.");
+		query.q = q;
+	}
+	return query;
+}
+//#endregion
+export { PAGE_QUERY_KEYS, PageQueryError, parsePageQuery, singleValue };

package/dist/node/runtime/pageSort.js

@@ -0,0 +1,114 @@
+//#region src/runtime/pageSort.ts
+/** Une valeur absente ne se compare pas — elle se range à part. */
+const missing = (v) => v === null || v === void 0;
+/**
+* Compare deux valeurs de tri **présentes**, tous types confondus. Le cas des
+* absentes est traité par {@link compareByOrder}, en dehors de l'inversion de
+* sens : les y laisser reviendrait à les faire remonter en tête d'un tri `DESC`,
+* ce qui n'a jamais renseigné personne.
+*/
+function compareValues(a, b) {
+	if (a instanceof Date || b instanceof Date) return Number(a) - Number(b);
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+	return String(a).localeCompare(String(b));
+}
+/**
+* Réécrit les noms de champs d'un `order` selon une table d'alias — le pont
+* entre le vocabulaire **public** (celui de l'URL) et le schéma d'un backend.
+*
+* Il existe parce que chaque store le refaisait : trois fonctions strictement
+* identiques traduisaient `id` vers `_id` ou `session_id`, une par ressource.
+* La règle (« réécrire les noms ») est la même partout ; seule la TABLE change,
+* et c'est elle qui est une donnée du backend, pas du code.
+*
+* Un champ absent de la table passe inchangé — l'immense majorité des noms
+* publics sont déjà ceux du schéma.
+*
+* @param order - l'ordre demandé, en vocabulaire public.
+* @param aliases - `{ nomPublic: nomDansLeSchéma }`.
+* @returns le même ordre, exprimé dans le schéma du backend.
+*
+* @example
+* ```ts
+* // Mongo stocke la clé primaire en `_id`, il n'existe aucun champ `id`.
+* renameOrderFields(order, { id: "_id" });
+* ```
+*/
+function renameOrderFields(order, aliases) {
+	return order.map(([field, dir]) => [aliases[field] ?? field, dir]);
+}
+/**
+* Retient d'un `order` demandé les seuls couples dont le champ est **déclaré
+* triable**, et retombe sur l'ordre par défaut s'il n'en reste aucun.
+*
+* C'est le dernier étage d'une garde à deux niveaux, et il n'est pas redondant :
+* le data plane refuse déjà en 400 un champ hors allowlist, mais tout appelant
+* interne (un autre service, un test, un futur endpoint) peut fabriquer un
+* `IPageQuery` à la main. Sans ce filtre, deux backends répondraient
+* différemment à la même requête — celui qui lit l'objet en mémoire trierait sur
+* un champ jamais annoncé, celui qui compose du SQL l'ignorerait — et le contrat
+* partagé ne décrirait plus un comportement mais deux.
+*
+* 🔒 Côté SQL, ce filtre est une **garde d'injection** : un nom de colonne ne se
+* lie pas en paramètre, il se concatène dans le `ORDER BY`.
+*
+* @param order - l'ordre demandé (peut être absent ou vide).
+* @param allowed - les champs que le store déclare savoir trier.
+* @param fallback - l'ordre contractuel appliqué à défaut.
+* @returns un ordre non vide, garanti clos sur `allowed` ∪ `fallback`.
+*
+* @example
+* ```ts
+* const order = pickOrder(query.order, this.sortableFields, DEFAULT_ORDER);
+* rows.sort(compareByOrder(order, (r, f) => r[f as keyof Row]));
+* ```
+*/
+function pickOrder(order, allowed, fallback) {
+	if (!order || order.length === 0) return fallback;
+	const kept = order.filter(([field]) => allowed.includes(field));
+	return kept.length > 0 ? kept : fallback;
+}
+/**
+* Fabrique le comparateur d'un `order` du contrat de page — **le** tri en
+* mémoire de Nodefony, partagé par tous les stores qui n'ont pas de moteur pour
+* le faire à leur place.
+*
+* Il existe parce que chaque store mémoire réécrivait le sien, en dur et inline :
+* le tri d'un backend mémoire différait alors de celui du backend SQL de la même
+* ressource, si bien qu'un test vert en mémoire ne disait rien de la production.
+* Les backends SQL et Mongo, eux, n'en ont pas besoin — ils poussent l'`order`
+* dans la requête, où il est infiniment moins cher.
+*
+* Les couples sont appliqués **dans l'ordre** : le premier qui départage
+* l'emporte, les suivants ne servent qu'aux ex æquo. Un `order` vide rend un
+* comparateur neutre (`0` partout), ce qui laisse `Array.prototype.sort` stable
+* et préserve donc l'ordre d'origine.
+*
+* @param order - les couples `[champ, sens]` du contrat.
+* @param read - comment lire un champ sur un élément.
+* @returns un comparateur utilisable tel quel dans `.sort()`.
+*
+* @example
+* ```ts
+* const order = query.order?.length ? query.order : DEFAULT_ORDER;
+* rows.sort(compareByOrder(order, (r, field) => r[field as keyof Row]));
+* ```
+*/
+function compareByOrder(order, read) {
+	return (a, b) => {
+		for (const [field, dir] of order) {
+			const va = read(a, field);
+			const vb = read(b, field);
+			if (missing(va) || missing(vb)) {
+				if (missing(va) && missing(vb)) continue;
+				return missing(va) ? 1 : -1;
+			}
+			const cmp = compareValues(va, vb);
+			if (cmp !== 0) return dir === "DESC" ? -cmp : cmp;
+		}
+		return 0;
+	};
+}
+//#endregion
+export { compareByOrder, pickOrder, renameOrderFields };

package/dist/node/runtime/redact.js

@@ -0,0 +1,43 @@
+//#region src/runtime/redact.ts
+/**
+* Redaction de secrets dans une ligne de texte (logs, SQL profilé, payloads).
+*
+* **Défense en profondeur, pas un contrôle d'accès** : la source de vérité reste
+* « ne pas logger de secret ». Cette passe masque les fuites résiduelles avant
+* d'exposer du texte hors du process (viewer de logs Studio, profiler dev, debug
+* bar). Pure et isomorphe (zéro dépendance Node) → utilisable serveur ET browser.
+*
+* Couvre trois familles fréquentes :
+*  - paires clé/valeur JSON `"password":"x"` / `"token": x` ;
+*  - paires clé/valeur texte `password=x` / `Authorization: x` ;
+*  - schémas d'auth porteurs `Bearer <jwt>` / `Basic <b64>`.
+*
+* Les regex sont compilées une fois (coût nul par appel hormis le `replace`).
+* Hors hot-path requête (admin plane / dev) — l'usage en boucle reste correct
+* mais préférer un appel par ligne.
+*/
+/** Clés dont la valeur est considérée sensible (insensible à la casse). */
+const SENSITIVE_KEYS = "password|passwd|pwd|secret|client[_-]?secret|token|access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|x-api-key|authorization|cookie|set-cookie|session[_-]?id|private[_-]?key";
+/** JSON : `"key": "value"` ou `"key": value` → valeur masquée. */
+const JSON_PAIR = new RegExp(`("(?:${SENSITIVE_KEYS})"\\s*:\\s*)("(?:[^"\\\\]|\\\\.)*"|[^\\s,}\\]]+)`, "gi");
+/** Texte : `key=value` / `key: value` (avec ou sans quotes) → valeur masquée. */
+const KV_PAIR = new RegExp(`\\b(${SENSITIVE_KEYS})(\\s*[:=]\\s*)("[^"]*"|'[^']*'|[^\\s,;]+)`, "gi");
+/** Schémas d'auth porteurs : `Bearer <token>` / `Basic <b64>`. */
+const BEARER = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{4,}/gi;
+/** Placeholder unique de remplacement. */
+const MASK = "***";
+/**
+* Renvoie `line` avec les secrets connus masqués par `***`.
+*
+* Idempotent (re-rédiger une ligne déjà masquée ne change rien). Conserve la
+* structure (clés, ponctuation) pour que la ligne reste lisible/diffable.
+*
+* @param line - ligne de log/texte brute.
+* @returns la même ligne, valeurs sensibles remplacées par `***`.
+*/
+function redactSecrets(line) {
+	if (!line) return line;
+	return line.replace(BEARER, `$1 ${MASK}`).replace(JSON_PAIR, `$1"${MASK}"`).replace(KV_PAIR, `$1$2${MASK}`);
+}
+//#endregion
+export { redactSecrets };

package/dist/node/runtime/withTimeout.js

@@ -0,0 +1,71 @@
+//#region src/runtime/withTimeout.ts
+/**
+* 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).
+*/
+var TimeoutError = class extends Error {
+	/** Délai (ms) qui a été dépassé. */
+	timeoutMs;
+	/**
+	* @param timeoutMs - délai dépassé, en millisecondes.
+	* @param label - libellé optionnel de l'opération (préfixe du message).
+	*/
+	constructor(timeoutMs, label) {
+		super(`${label ? `${label}: ` : ""}timeout après ${timeoutMs}ms`);
+		this.name = "TimeoutError";
+		this.timeoutMs = timeoutMs;
+	}
+};
+/**
+* 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.
+*/
+async function withTimeout(promise, timeoutMs, label) {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return await promise;
+	const p = Promise.resolve(promise);
+	p.catch(() => {});
+	let timer;
+	try {
+		return await Promise.race([p, new Promise((_, reject) => {
+			timer = setTimeout(() => reject(new TimeoutError(timeoutMs, label)), timeoutMs);
+			timer.unref?.();
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+//#endregion
+export { TimeoutError, withTimeout };

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

@@ -0,0 +1,202 @@
+import cluster from "node:cluster";
+//#region src/service/cluster/ClusterManager.ts
+/**
+* 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]`.
+*/
+function computeBackoff(crashes, baseMs, maxMs) {
+	return Math.min(baseMs * 2 ** (Math.max(1, Math.floor(crashes)) - 1), maxMs);
+}
+const nodeScheduler = {
+	set: (fn, ms) => setTimeout(fn, ms),
+	clear: (h) => clearTimeout(h)
+};
+/** Adapter de production : `node:cluster`. */
+const nodeClusterRuntime = {
+	get isPrimary() {
+		return cluster.isPrimary;
+	},
+	fork() {
+		const w = cluster.fork();
+		return {
+			id: w.id,
+			kill: (s) => w.kill(s),
+			isDead: () => w.isDead()
+		};
+	},
+	onExit(cb) {
+		cluster.on("exit", (w, code, signal) => cb({
+			id: w.id,
+			kill: (s) => w.kill(s),
+			isDead: () => w.isDead()
+		}, code, signal));
+	}
+};
+/**
+* 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.
+*/
+var ClusterManager = class {
+	#workers;
+	#log;
+	#runtime;
+	#scheduler;
+	#exit;
+	#base;
+	#max;
+	#stableMs;
+	#shutdownTimeoutMs;
+	#live = /* @__PURE__ */ new Map();
+	#consecutiveCrashes = 0;
+	#shuttingDown = false;
+	#shutdownTimer = null;
+	#started = false;
+	constructor(opts) {
+		this.#workers = Math.max(1, opts.workers);
+		this.#log = opts.log ?? (() => {});
+		this.#runtime = opts.runtime ?? nodeClusterRuntime;
+		this.#scheduler = opts.scheduler ?? nodeScheduler;
+		this.#exit = opts.exit ?? ((code) => process.exit(code));
+		this.#base = opts.respawnBaseMs ?? 200;
+		this.#max = opts.respawnMaxMs ?? 1e4;
+		this.#stableMs = opts.stableMs ?? 3e4;
+		this.#shutdownTimeoutMs = opts.shutdownTimeoutMs ?? 1e4;
+	}
+	/** Nombre de workers actuellement vivants. */
+	get size() {
+		return this.#live.size;
+	}
+	/**
+	* Les gestionnaires de signaux POSÉS PAR CE MANAGER, avec leur signal.
+	*
+	* Garder la référence est ce qui permet de retirer les siens sans toucher à
+	* ceux des autres — la raison d'être de {@link removeSignalHandlers}.
+	*/
+	#signalHandlers = [];
+	/** `true` une fois `shutdown()` enclenché (plus aucun respawn). */
+	get shuttingDown() {
+		return this.#shuttingDown;
+	}
+	/**
+	* Fork les workers initiaux et arme le respawn. Idempotent.
+	*
+	* @returns `this`.
+	*/
+	start() {
+		if (this.#started) return this;
+		this.#started = true;
+		this.#runtime.onExit((w, code, signal) => this.#onExit(w, code, signal));
+		for (let i = 0; i < this.#workers; i += 1) this.#fork();
+		this.#log(`cluster master up — ${this.#workers} worker(s)`, "INFO");
+		return this;
+	}
+	#fork() {
+		const worker = this.#runtime.fork();
+		this.#live.set(worker.id, {
+			worker,
+			forkedAt: Date.now()
+		});
+	}
+	#onExit(worker, code, signal) {
+		const rec = this.#live.get(worker.id);
+		this.#live.delete(worker.id);
+		const cause = signal ?? `code ${code}`;
+		if (this.#shuttingDown) {
+			this.#log(`worker ${worker.id} exited (${cause}) — ${this.#live.size} remaining`, "INFO");
+			if (this.#live.size === 0) this.#finishShutdown(0);
+			return;
+		}
+		if ((rec ? Date.now() - rec.forkedAt : 0) >= this.#stableMs) this.#consecutiveCrashes = 0;
+		this.#consecutiveCrashes += 1;
+		const delay = computeBackoff(this.#consecutiveCrashes, this.#base, this.#max);
+		this.#log(`worker ${worker.id} died (${cause}) — respawn in ${delay}ms (crash #${this.#consecutiveCrashes})`, "WARNING");
+		this.#scheduler.set(() => {
+			if (!this.#shuttingDown) this.#fork();
+		}, delay);
+	}
+	/**
+	* 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 = "SIGTERM") {
+		if (this.#shuttingDown) return;
+		this.#shuttingDown = true;
+		this.#log(`${signal} — draining ${this.#live.size} worker(s)`, "CRITIC");
+		if (this.#live.size === 0) {
+			this.#finishShutdown(0);
+			return;
+		}
+		for (const { worker } of this.#live.values()) if (!worker.isDead()) worker.kill("SIGTERM");
+		this.#shutdownTimer = this.#scheduler.set(() => {
+			this.#log(`graceful timeout — SIGKILL ${this.#live.size} worker(s)`, "ERROR");
+			for (const { worker } of this.#live.values()) if (!worker.isDead()) worker.kill("SIGKILL");
+			this.#finishShutdown(1);
+		}, this.#shutdownTimeoutMs);
+	}
+	#finishShutdown(code) {
+		if (this.#shutdownTimer !== null) {
+			this.#scheduler.clear(this.#shutdownTimer);
+			this.#shutdownTimer = null;
+		}
+		this.#log(`cluster master down (exit ${code})`, "INFO");
+		this.#exit(code);
+	}
+	/**
+	* 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() {
+		for (const sig of ["SIGTERM", "SIGINT"]) {
+			const handler = () => this.shutdown(sig);
+			this.#signalHandlers.push([sig, handler]);
+			process.on(sig, handler);
+		}
+	}
+	/**
+	* 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() {
+		const n = this.#signalHandlers.length;
+		for (const [sig, handler] of this.#signalHandlers) process.removeListener(sig, handler);
+		this.#signalHandlers = [];
+		return n;
+	}
+};
+//#endregion
+export { ClusterManager, ClusterManager as default, computeBackoff };