nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/kernel/commands/runtimeLauncher.js

@@ -0,0 +1,95 @@
+import "../../cli/sysexits.js";
+import { defaultDevPorts, discoverDevProcesses, findRuntimeConflict, probePorts, splitByProject } from "../../service/dev/devProcess.js";
+import { startClusterMaster } from "../../service/cluster/clusterMaster.js";
+import cluster from "node:cluster";
+//#region src/kernel/commands/runtimeLauncher.ts
+/** Libellé FR d'un mode runtime, pour les messages d'erreur. */
+function modeLabelFr(mode) {
+	if (mode === "dev") return "développement";
+	if (mode === "cluster") return "cluster";
+	return "production";
+}
+/**
+* Garde anti-collision (symétrique du superviseur dev) : un runtime prod/cluster ne
+* démarre PAS par-dessus un AUTRE runtime **de CE projet** (dev/prod/cluster d'un mode
+* différent). Fail-loud + exit — jamais de kill auto cross-mode (le runtime préexistant
+* est intentionnel). Primaire seulement (les workers forkés héritent d'un primaire déjà
+* validé). `ps` indisponible → liste vide → on retombe sur l'`EADDRINUSE` natif
+* (best-effort, ex. conteneur minimaliste sans `ps`).
+*
+* **Scopé au projet** (`splitByProject`, égalité stricte du cwd — la MÊME règle que
+* `stop`, `status` et le superviseur : une seconde implémentation dériverait). Le motif
+* du garde est la collision de PORTS ; or deux projets Nodefony cohabitent désormais
+* (`servers.portPolicy: "auto"` en dev, ports déclarés en prod). Refuser un `production`
+* parce que le dev d'une AUTRE app tourne, c'était crier au loup sur le cas nominal —
+* et un garde qui se déclenche sur le cas nominal n'est plus lu.
+*
+* **La collision se CONSTATE, elle ne se déduit pas d'une présence de process.** Un
+* process enregistré ne détient pas forcément un port : un superviseur de développement
+* dont l'enfant a été tué (kill -9 d'un banc, OOM, plantage) survit orphelin, n'écoute
+* RIEN, et reste visible de `ps`. Refuser la production sur sa seule existence, c'est
+* l'interdire à cause d'un fantôme — sur un pod, un démarrage qui échoue sans qu'aucun
+* port ne soit pris. Le chemin dev le constatait déjà (`detachedStart` → `probePorts`) ;
+* cette dissymétrie était le défaut. On sonde donc les ports DÉCLARÉS
+* (`defaultDevPorts` — même source que `status` et `stop`) : aucun tenu ⇒ on AVERTIT et
+* on laisse démarrer, l'`EADDRINUSE` natif restant le filet ultime.
+*/
+async function assertNoConflictingRuntime(intended, log, deps = {}) {
+	const cwd = deps.cwd ?? process.cwd();
+	const { mine } = splitByProject((deps.discover ?? discoverDevProcesses)(), cwd, deps.getCwd);
+	const conflict = findRuntimeConflict(mine, intended);
+	if (conflict.length === 0) return;
+	const pids = conflict.map((p) => p.pid).join(", ");
+	const held = (await (deps.probe ?? probePorts)(defaultDevPorts(cwd))).filter((p) => p.listening).map((p) => p.port);
+	if (held.length === 0) {
+		log(`un runtime Nodefony ${modeLabelFr(conflict[0].mode)} de CE projet est enregistré (pid ${pids}) mais ne détient AUCUN port — résidu probable (son serveur a été tué). Démarrage ${modeLabelFr(intended)} MAINTENU. Pour nettoyer : nodefony stop`, "WARNING");
+		return;
+	}
+	log(`⛔ un runtime Nodefony ${modeLabelFr(conflict[0].mode)} de CE projet tourne déjà (pid ${pids}) et tient le(s) port(s) ${held.join(", ")} — démarrage ${modeLabelFr(intended)} refusé. Arrête-le d'abord : nodefony stop`, "CRITIC");
+	(deps.exit ?? ((c) => process.exit(c)))(69);
+}
+/**
+* Applique la topologie résolue — flow **PARTAGÉ** par les commandes de lancement
+* (`cluster`, `production`). Appelé depuis leur `onKernelStart` (phase `onStart`),
+* donc AVANT que l'unique Kernel ne démarre ses serveurs (`onReady → initServers`).
+*
+* **Un seul Kernel par process** (fin du double-boot historique) :
+* - `workers >= 2` && process primaire → **MASTER** : {@link startClusterMaster}
+*   (fork N workers + relay IPC + sonde pod). Ne boote AUCUN serveur HTTP ; le Kernel
+*   courant reste en `CONSOLE` et on **park** le flow (le master est un superviseur
+*   pur, gardé vivant par les listeners cluster + les timers de la sonde).
+* - sinon (mono-process `workers:1` OU process **worker** forké) → on bascule le Kernel
+*   courant en `SERVER` et on **rend la main** : son pipeline de boot continue de
+*   lui-même (`onReady → initServers → onPostReady`), les serveurs HTTP/WS montent et
+*   le process reste vivant via leurs handles. Plus aucun `new Kernel` ici.
+*
+* Vit dans `kernel/commands/` (et non `service/cluster/`) pour garder le service
+* cluster **kernel-free**.
+*/
+async function launchTopology(opts) {
+	const { cli, topo, log } = opts;
+	if (cluster.isPrimary) await assertNoConflictingRuntime(topo.workers >= 2 ? "cluster" : "prod", log);
+	if (cluster.isPrimary && topo.workers >= 2) {
+		log(`Cluster topology: ${topo.workers} workers (source: ${topo.source})`, "INFO");
+		cli.setRunProfile({
+			servers: false,
+			lifetime: "longrunning",
+			interactive: false
+		});
+		cli.releaseSignalListeners();
+		startClusterMaster({
+			workers: topo.workers,
+			log
+		});
+		await cli.kernel.park();
+		return;
+	}
+	if (cluster.isPrimary) log(`Topology: 1 process (source: ${topo.source}) — mono-process, no cluster machinery`, "INFO");
+	cli.setRunProfile({
+		servers: true,
+		lifetime: "longrunning",
+		interactive: false
+	});
+}
+//#endregion
+export { assertNoConflictingRuntime, launchTopology };

package/dist/node/kernel/decorators/kernelDecorator.js

@@ -0,0 +1,110 @@
+import Injector from "../injector/injector.js";
+import { orderServicesByDependencies } from "../injector/serviceOrder.js";
+import "reflect-metadata";
+//#region src/kernel/decorators/kernelDecorator.ts
+/**
+* Déclare les services qu'un module enregistre dans son conteneur au démarrage.
+*
+* Décorateur de **classe de module**. Les services sont instanciés au hook
+* `onPreBoot`, et **l'ordre écrit ici n'a aucune importance** : il est recalculé
+* depuis les dépendances déclarées (`@inject`), de sorte qu'un service réclamé
+* soit présent avant son consommateur. Le hook est tagué au nom du module : un
+* service qui échoue suit la politique de criticité de SON module — fatal en
+* production, dégradation annoncée ailleurs — au lieu de faire tomber le boot
+* anonymement.
+*
+* @param nameOrPath - Une classe de service, un chemin de fichier, ou un tableau
+*   mêlant les deux.
+* @returns Le décorateur de classe, qui renvoie le module enrichi du hook.
+* @example
+* ```typescript
+* @services([Router, Eta, AdminBroker])
+* class FrameworkModule extends Module {}
+* ```
+*/
+function services(nameOrPath) {
+	return function(constructor) {
+		class NewConstructorService extends constructor {
+			constructor(...args) {
+				super(...args);
+				this.hookKernel("onPreBoot", async () => {
+					return await this.initDecoratorServices();
+				});
+			}
+			async initDecoratorServices() {
+				if (Array.isArray(nameOrPath)) {
+					const ordered = orderServicesByDependencies(nameOrPath);
+					for (const path of ordered) if (typeof path !== "string") await this.addService(path).catch((e) => {
+						this.handleServiceBootError(e, path);
+					});
+					else await this.loadService(path).catch((e) => {
+						this.handleServiceBootError(e, path);
+					});
+				} else {
+					if (typeof nameOrPath === "string") return await this.loadService(nameOrPath).catch((e) => {
+						this.handleServiceBootError(e, nameOrPath);
+					});
+					return await this.addService(nameOrPath).catch((e) => {
+						this.handleServiceBootError(e, nameOrPath);
+					});
+				}
+			}
+		}
+		return NewConstructorService;
+	};
+}
+/**
+* Rend une classe de service résoluble par le conteneur d'injection.
+*
+* Décorateur de **classe**. Il inscrit la classe à l'annuaire d'injection sous
+* un nom — celui de la classe par défaut — et fige sa portée. Sans lui, la
+* classe reste une classe ordinaire : elle ne peut être ni découverte, ni
+* injectée, et un `@inject("…")` qui la réclame échouera à la résolution.
+*
+* @param nameOrOptions - Le nom d'enregistrement, ou `{ name?, scope? }`. La
+*   portée vaut `"singleton"` par défaut — une seule instance pour le
+*   processus ; `"transient"` en fabrique une par résolution.
+* @returns Le décorateur de classe, qui renvoie la classe inchangée.
+* @example
+* ```typescript
+* @injectable()
+* class Router extends Service {}
+*
+* @injectable({ name: "pdfRenderer", scope: "transient" })
+* class PdfRenderer extends Service {}
+* ```
+*/
+function injectable(nameOrOptions) {
+	return function(constructor) {
+		let regName;
+		let scope = "singleton";
+		if (typeof nameOrOptions === "string") regName = nameOrOptions || constructor.name;
+		else if (nameOrOptions && typeof nameOrOptions === "object") {
+			regName = nameOrOptions.name || constructor.name;
+			scope = nameOrOptions.scope ?? "singleton";
+		} else regName = constructor.name;
+		Injector.register(regName, constructor);
+		Reflect.defineMetadata("di:scope", scope, constructor);
+		return constructor;
+	};
+}
+/**
+* Injecter une Service avec son nom dans le constructeur.
+*
+* @param serviceName - Le nom du service à injecter (doit correspondre à un @injectable)
+*
+* @example
+*  class MyService extends Service {
+*    constructor(@inject("Fetch") private fetch: Fetch) { super("my", ...) }
+*  }
+*/
+function inject(serviceName) {
+	return function(target, _propertyKey, parameterIndex) {
+		if (!serviceName) throw new Error(`Inject decorator requires a valid service name`);
+		const existing = Reflect.getMetadata("inject:services", target) || [];
+		existing[parameterIndex] = serviceName;
+		Reflect.defineMetadata("inject:services", existing, target);
+	};
+}
+//#endregion
+export { inject, injectable, services };

package/dist/node/kernel/injector/injector.js

@@ -0,0 +1,137 @@
+import { Nodefony } from "../../Nodefony.js";
+import Service from "../../Service.js";
+import Fetch from "../../service/fetchService.js";
+import "reflect-metadata";
+//#region src/kernel/injector/injector.ts
+const injectables = Object.create(null);
+const containerKeys = /* @__PURE__ */ new Map();
+var Injector = class Injector extends Service {
+	static injectables = injectables;
+	constructor(kernel) {
+		super("injector", kernel.container, kernel.notificationsCenter);
+		Injector.register("Fetch", Fetch);
+		kernel.set("Fetch", new Fetch(kernel));
+	}
+	static register(serviceName, service) {
+		if (!serviceName || !service) throw new Error(`Injector register  bad argument`);
+		return injectables[serviceName] = service;
+	}
+	static isRegistered(serviceName) {
+		return serviceName in injectables;
+	}
+	/**
+	* Mémorise la clé sous laquelle une classe de service vit RÉELLEMENT dans le
+	* container — apprise au moment où l'instance y est posée.
+	*
+	* @remarks Sans elle, `@inject("Router")` interrogeait le container avec
+	*   `"Router"` alors que l'instance y est rangée sous `"router"` (le nom de son
+	*   `super()`) : le container répondait `null` et le service était RECONSTRUIT,
+	*   son cache vide, silencieusement. Un seul des 7 `@injectable` échappait au
+	*   piège — `HttpKernel`, par coïncidence de casse.
+	*
+	* @param service - le constructeur, tel qu'enregistré par `@injectable`.
+	* @param containerKey - `instance.name`, la clé réelle du container.
+	*/
+	static rememberContainerKey(service, containerKey) {
+		if (!service || !containerKey) return;
+		containerKeys.set(service, containerKey);
+	}
+	/**
+	* Clé container connue d'une classe de service, ou `null` si elle n'a jamais
+	* été posée au container (rien à apprendre encore).
+	*/
+	static containerKeyOf(service) {
+		return containerKeys.get(service) ?? null;
+	}
+	static getScope(serviceName) {
+		const Ctor = injectables[serviceName];
+		if (!Ctor) return "singleton";
+		return Reflect.getMetadata("di:scope", Ctor) ?? "singleton";
+	}
+	static get(serviceName) {
+		const service = injectables[serviceName];
+		if (!service) throw new Error(`Service ${serviceName} not found or not injectable`);
+		return service;
+	}
+	static inject(service, ...args) {
+		return Injector.instantiate(service, ...args);
+	}
+	instantiate(constructor, ...args) {
+		return Injector.instantiate(constructor, ...args);
+	}
+	static instantiate(constructor, ...argsClass) {
+		return Injector._instantiateWithStack(constructor, [], argsClass);
+	}
+	static _resolveWithStack(serviceName, stack) {
+		if (Injector.isRegistered(serviceName)) {
+			const Ctor = Injector.get(serviceName);
+			if ((Reflect.getMetadata("di:scope", Ctor) ?? "singleton") === "transient") return Injector._instantiateWithStack(Ctor, stack, []);
+			const kernel = Nodefony.getKernel();
+			const key = Injector.containerKeyOf(Ctor) ?? serviceName;
+			if (kernel && kernel.get(key)) return kernel.get(key);
+			let instance;
+			try {
+				instance = Injector._instantiateWithStack(Ctor, stack, []);
+			} catch (error) {
+				const requester = stack[stack.length - 1];
+				throw new Error(`Cannot resolve service "${serviceName}"` + (requester ? ` required by "${requester}"` : "") + `: it is @injectable but absent from the kernel container, so it was constructed without arguments — and its constructor threw (${error instanceof Error ? error.message : String(error)}). If "${serviceName}" is declared in @services([...]), list it BEFORE its consumers: services are instantiated in order, and a service must be in the container before anyone injects it.`, { cause: error });
+			}
+			const canonicalKey = instance.name || serviceName;
+			Injector.rememberContainerKey(Ctor, canonicalKey);
+			kernel?.set(canonicalKey, instance);
+			return instance;
+		}
+		const kernel = Nodefony.getKernel();
+		if (kernel) {
+			const existing = kernel.get(serviceName);
+			if (existing) return existing;
+		}
+		throw new Error(`Service ${serviceName} not found or not injectable`);
+	}
+	static _applyPropertyInjection(constructor, instance, stack) {
+		const propMetas = Reflect.getMetadata("inject:properties", constructor.prototype) || [];
+		for (const { key, name } of propMetas) instance[key] = Injector._resolveWithStack(name, stack);
+		return instance;
+	}
+	static _instantiateWithStack(constructor, stack, argsClass) {
+		const ctorName = constructor.name;
+		if (stack.includes(ctorName)) throw new Error(`Circular dependency detected: ${[...stack, ctorName].join(" → ")}`);
+		const nextStack = [...stack, ctorName];
+		const injectExplicit = Reflect.getMetadata("inject:services", constructor) || [];
+		const paramTypes = Reflect.getMetadata("design:paramtypes", constructor) || [];
+		if (!(injectExplicit.some(Boolean) || paramTypes.length > 0)) {
+			const instance = Reflect.construct(constructor, argsClass);
+			return Injector._applyPropertyInjection(constructor, instance, nextStack);
+		}
+		const totalParams = Math.max(paramTypes.length, injectExplicit.length);
+		const resolvedArgs = [];
+		let explicitIdx = 0;
+		for (let i = 0; i < totalParams; i++) {
+			const explicitName = injectExplicit[i];
+			if (explicitName) {
+				resolvedArgs.push(Injector._resolveWithStack(explicitName, nextStack));
+				continue;
+			}
+			const type = paramTypes[i];
+			if (type?.name && Injector.isRegistered(type.name)) {
+				resolvedArgs.push(Injector._resolveWithStack(type.name, nextStack));
+				continue;
+			}
+			resolvedArgs.push(argsClass[explicitIdx++]);
+		}
+		while (explicitIdx < argsClass.length) resolvedArgs.push(argsClass[explicitIdx++]);
+		const instance = Reflect.construct(constructor, resolvedArgs);
+		return Injector._applyPropertyInjection(constructor, instance, nextStack);
+	}
+	reflect(constructor, ...args) {
+		try {
+			return Reflect.construct(constructor, args);
+		} catch (e) {
+			const message = e instanceof Error ? e.message : String(e);
+			this.log(`ERROR SERVICE CLASS ${this.name} ${message}`, "ERROR");
+			throw e;
+		}
+	}
+};
+//#endregion
+export { Injector as default };

package/dist/node/kernel/injector/serviceOrder.js

@@ -0,0 +1,106 @@
+import Injector from "./injector.js";
+import "reflect-metadata";
+//#region src/kernel/injector/serviceOrder.ts
+/**
+* Nom sous lequel un constructeur est enregistré au registre `@injectable`, ou
+* `null` s'il ne l'est pas.
+*
+* @remarks Recherche inversée (valeur → clé) : `@injectable(nom)` n'écrit sa clé
+*   nulle part sur la classe — seul le registre la connaît. C'est une
+*   conséquence du divorce registre/container ; le jour où le token sera la
+*   classe, cette fonction disparaîtra.
+*/
+const registeredNameOf = (ctor) => {
+	const registry = Injector.injectables;
+	for (const name of Object.keys(registry)) if (registry[name] === ctor) return name;
+	return null;
+};
+/**
+* Noms des services dont un constructeur dépend, tels que le DI les résoudra :
+* `@inject("nom")` (priorité) puis l'auto-injection par type (`design:paramtypes`,
+* résolue sur le nom de classe).
+*/
+const declaredDependencyNames = (ctor) => {
+	const explicit = Reflect.getMetadata("inject:services", ctor) || [];
+	const paramTypes = Reflect.getMetadata("design:paramtypes", ctor) || [];
+	const names = [];
+	for (const name of explicit) if (name) names.push(name);
+	for (const type of paramTypes) {
+		const name = type?.name;
+		if (name && Injector.isRegistered(name)) names.push(name);
+	}
+	return names;
+};
+/**
+* Réordonne les services d'un `@services([...])` selon leurs dépendances
+* **déclarées**, pour que l'ordre d'écriture cesse de compter.
+*
+* `@services` instancie séquentiellement et pose chaque instance au container :
+* un service réclamé par un autre doit donc exister AVANT lui, sinon le DI le
+* reconstruit sans argument et son constructeur casse. Faire reposer ça sur
+* l'ordre d'une liste écrite à la main est un piège : déplacer `HttpKernel` de
+* trois lignes dans `@nodefony/http` suffisait à rendre 499 sur chaque requête.
+* Les dépendances étant déjà déclarées (`@inject` / `design:paramtypes`), l'ordre
+* correct se **calcule** — c'est ce que font Symfony (container compilé) et
+* NestJS (résolution du graphe).
+*
+* Tri topologique **stable** : à contrainte égale, l'ordre d'écriture est
+* conservé — un `@services` déjà correct sort inchangé.
+*
+* Ne touche pas aux entrées dont les dépendances sont inconnaissables sans les
+* charger (chemins `string`) ni aux constructeurs hors registre : elles gardent
+* leur position relative.
+*
+* @param entries - la liste telle qu'écrite dans `@services([...])`.
+* @returns la même liste, réordonnée ; jamais une entrée perdue ou dupliquée.
+* @throws Si les dépendances déclarées forment un cycle (message nommant le cycle).
+*/
+function orderServicesByDependencies(entries) {
+	if (entries.length < 2) return [...entries];
+	const indexByName = /* @__PURE__ */ new Map();
+	entries.forEach((entry, i) => {
+		if (typeof entry === "string") return;
+		const name = registeredNameOf(entry);
+		if (name !== null && !indexByName.has(name)) indexByName.set(name, i);
+	});
+	const dependsOn = entries.map(() => /* @__PURE__ */ new Set());
+	let hasEdge = false;
+	entries.forEach((entry, i) => {
+		if (typeof entry === "string") return;
+		for (const depName of declaredDependencyNames(entry)) {
+			const j = indexByName.get(depName);
+			if (j === void 0 || j === i) continue;
+			dependsOn[i].add(j);
+			hasEdge = true;
+		}
+	});
+	if (!hasEdge) return [...entries];
+	const remaining = new Set(entries.map((_, i) => i));
+	const ordered = [];
+	while (remaining.size > 0) {
+		let picked = -1;
+		for (const i of remaining) {
+			let ready = true;
+			for (const dep of dependsOn[i]) if (remaining.has(dep)) {
+				ready = false;
+				break;
+			}
+			if (ready) {
+				picked = i;
+				break;
+			}
+		}
+		if (picked === -1) {
+			const cycle = [...remaining].map((i) => {
+				const e = entries[i];
+				return typeof e === "string" ? e : e.name;
+			}).join(" → ");
+			throw new Error(`Circular service dependency in @services([...]): ${cycle}. Services are instantiated in dependency order; a cycle has no valid order.`);
+		}
+		ordered.push(entries[picked]);
+		remaining.delete(picked);
+	}
+	return ordered;
+}
+//#endregion
+export { orderServicesByDependencies };

package/dist/node/kernel/inspect/adminSubjects.js

@@ -0,0 +1,194 @@
+import { resolveAdminRole } from "../adminPlane/adminRbac.js";
+import { executeAdminEndpoint, normalizeAdminResult } from "../adminPlane/executeAdmin.js";
+//#region src/kernel/inspect/adminSubjects.ts
+/**
+* Sujets inspectables, et l'endpoint d'administration qui les sert.
+*
+* **Aucune donnée n'est calculée ici.** Chaque sujet pointe le producteur qui
+* répond déjà en HTTP : toutes les portes rendent le même objet, parce que
+* c'est le même code qui le produit. Une table de correspondance peut se
+* périmer ; une réimplémentation, elle, diverge en silence — et c'est la porte
+* secondaire qu'on croirait sur parole.
+*
+* ⚠️ Cette table est la SOURCE UNIQUE des sujets. La commande `inspect`, le
+* serveur MCP et toute porte future la lisent ici — aucune n'en tient une
+* copie.
+*/
+const INSPECT_SUBJECTS = {
+	routes: {
+		namespace: "framework",
+		path: "routes",
+		summary: "toutes les routes (chemin, méthodes, controller, action)"
+	},
+	modules: {
+		namespace: "kernel",
+		path: "modules",
+		summary: "modules chargés, avec leur version"
+	},
+	services: {
+		namespace: "kernel",
+		path: "services",
+		summary: "services enregistrés, et le module qui les porte"
+	},
+	config: {
+		namespace: "kernel",
+		path: "config",
+		summary: "config effective de chaque module (+ schéma, + provenance)"
+	},
+	module: {
+		namespace: "kernel",
+		path: "module/{name}",
+		summary: "un module en détail (config, services, dépendances)",
+		param: "name"
+	},
+	stores: {
+		namespace: "kernel",
+		path: "stores",
+		summary: "où sont réellement écrites les données (sessions, cache…)"
+	},
+	entities: {
+		namespace: "orm",
+		path: "entities",
+		summary: "entités déclarées à l'ORM"
+	},
+	graph: {
+		namespace: "orm",
+		path: "graph",
+		summary: "graphe des entités et de leurs relations"
+	}
+};
+/**
+* Extrait la donnée d'une réponse d'administration.
+*
+* Un handler rend soit la donnée, soit une enveloppe `{status, body}` (pour
+* porter un 404). Même discrimination que le pont HTTP : enveloppe **si et
+* seulement si** `body` est présent AVEC `status` ou `headers` — un objet
+* métier qui posséderait un champ `body` n'est pas une enveloppe.
+*/
+function unwrapAdminResult(result) {
+	const { status, body } = normalizeAdminResult(result);
+	return {
+		status,
+		data: body
+	};
+}
+/**
+* Appelle un endpoint du plan d'administration, hors HTTP.
+*
+* ⭐ **Une source, plusieurs portes** : cette fonction ne fait que RÉSOUDRE
+* l'endpoint (par producteur et chemin, là où la route HTTP le résout par nom
+* de route), puis délègue à {@link ../adminPlane/executeAdmin.executeAdminEndpoint} —
+* la même exécution que le transport HTTP. Autorisation, normalisation du
+* retour et traduction des erreurs sont donc identiques par CONSTRUCTION, et
+* non par vigilance.
+*
+* Ce que la version précédente perdait : elle appelait le handler directement
+* et ne gardait, d'un statut d'erreur, que le nombre. Le corps préparé par le
+* producteur — le plan d'une page, les valeurs acceptées — disparaissait, et
+* l'appelant concluait l'inverse de la vérité. Il voyage désormais entier
+* ({@link InspectResult}`.body`).
+*
+* Le rôle d'administrateur est **annoncé**, pas contourné : certains
+* producteurs graduent leur réponse selon les rôles, et un appelant qui se
+* présenterait en anonyme obtiendrait une vue amputée — il mentirait par
+* omission face à la même donnée lue en HTTP. Le contrôle d'accès du plan
+* d'administration protège le RÉSEAU ; la redaction des secrets, elle, vit dans
+* les producteurs et s'applique donc à toutes les portes.
+*
+* @param broker - le service `adminBroker` du conteneur
+* @param call - producteur, chemin, et ce qu'on lui passe
+* @returns la donnée du producteur, ou la raison précise de l'échec
+*/
+async function callAdminEndpoint(broker, call, caller) {
+	const label = call.label ?? `${call.namespace}/${call.path}`;
+	const producer = broker?.list().find((api) => api.adminNamespace === call.namespace);
+	if (!producer) return {
+		ok: false,
+		reason: "producer-missing",
+		message: `« ${label} » est servi par le module « ${call.namespace} », qui n'est pas chargé dans cette app`
+	};
+	const method = call.method ?? "GET";
+	const endpoint = producer.adminEndpoints().find((candidate) => candidate.path === call.path && (candidate.method ?? "GET") === method);
+	if (!endpoint) return {
+		ok: false,
+		reason: "endpoint-missing",
+		message: `endpoint « ${method} ${call.namespace}/${call.path} » introuvable — version de module incompatible ?`
+	};
+	const request = {
+		params: call.params ?? {},
+		query: call.query ?? {},
+		body: null,
+		user: caller.user,
+		roles: caller.roles
+	};
+	let thrown = null;
+	const execution = await executeAdminEndpoint({
+		endpoint,
+		request,
+		requiredRole: resolveAdminRole(endpoint),
+		gate: null,
+		onServerError: (error) => {
+			thrown = error;
+		}
+	});
+	if (thrown) return {
+		ok: false,
+		reason: "handler-failed",
+		message: `« ${label} » n'a pas pu être lu — le producteur a échoué`,
+		cause: thrown.message
+	};
+	if (execution.status === 403) {
+		const required = execution.body?.required;
+		return {
+			ok: false,
+			reason: "forbidden",
+			status: 403,
+			message: `« ${label} » refusé — ${caller.label}` + (required ? ` ne porte pas le rôle « ${required} »` : " n'a pas le droit de lire ceci"),
+			body: execution.body
+		};
+	}
+	if (execution.status >= 400) return {
+		ok: false,
+		reason: "not-found",
+		status: execution.status,
+		message: `« ${label} » introuvable (${execution.status})`,
+		body: execution.body
+	};
+	return {
+		ok: true,
+		status: execution.status,
+		data: execution.body
+	};
+}
+/**
+* Lit un sujet d'inspection dans le plan d'administration.
+*
+* Résout le sujet dans {@link INSPECT_SUBJECTS}, puis délègue à
+* {@link callAdminEndpoint} — ce qui vaut pour l'appel vaut donc ici.
+*
+* @param broker - le service `adminBroker` du conteneur
+* @param subject - clé de {@link INSPECT_SUBJECTS}
+* @param target - valeur du paramètre, pour les sujets qui en portent un
+* @returns la donnée du producteur, ou la raison précise de l'échec
+*/
+async function readAdminSubject(broker, subject, caller, target) {
+	const spec = INSPECT_SUBJECTS[subject];
+	if (!spec) return {
+		ok: false,
+		reason: "unknown-subject",
+		message: `sujet inconnu « ${subject} » — attendus : ${Object.keys(INSPECT_SUBJECTS).join(", ")}`
+	};
+	if (spec.param && !target) return {
+		ok: false,
+		reason: "missing-target",
+		message: `« ${subject} » attend un argument : ${spec.param}`
+	};
+	return callAdminEndpoint(broker, {
+		namespace: spec.namespace,
+		path: spec.path,
+		params: spec.param && target ? { [spec.param]: target } : {},
+		label: target ?? subject
+	}, caller);
+}
+//#endregion
+export { INSPECT_SUBJECTS, callAdminEndpoint, readAdminSubject, unwrapAdminResult };