@nodefony/realtime 10.0.0-beta.4 → 10.0.0-beta.6

package/dist/nodefony/src/server/ServerRealtimeSocket.js

@@ -1,4 +1,5 @@
 import { getRealtimeHub } from "./RealtimeHub.js";
+import { isRealtimePayload, realtimePayloadError } from "nodefony";
 // nodefony/src/server/ServerRealtimeSocket.ts
 /**
 * **L4 — façade serveur « la socket Nodefony ».** Un handle SERVEUR qui implémente
@@ -38,6 +39,7 @@ var ServerRealtimeSocket = class {
 	}
 	/** Émet sur un canal — fan-out aux abonnés via le hub (+ backplane si broadcast). */
 	publish(channel, payload) {
+		if (!isRealtimePayload(payload)) throw realtimePayloadError(channel, payload);
 		this.hub.publish(channel, payload);
 	}
 	/**

package/dist/nodefony/src/server/admissionBudget.js

@@ -0,0 +1,176 @@
+// nodefony/src/server/admissionBudget.ts
+/**
+* Coupe-circuit des admissions (décision de l'auteur sur #622) : 50 délais
+* dépassés en 5 s suspendent les appels d'`allow` pendant 5 s. Constantes
+* internes : un exploitant règle le délai et les plafonds, pas la mécanique qui
+* protège sa base quand elle ne répond plus.
+*/
+const BREAKER_THRESHOLD = 50;
+const BREAKER_WINDOW_MS = 5e3;
+const BREAKER_OPEN_MS = 5e3;
+/** Un avertissement par cause et par fenêtre : sous une base bloquée, un journal par abonné serait un amplificateur. */
+const WARN_INTERVAL_MS = 1e4;
+/** Rendu par {@link AdmissionBudget.acquire} quand une place est réservée. */
+const ADMISSION_GRANTED = -1;
+/** Rendu par {@link AdmissionBudget.authenticateWithin} quand l'authentification n'a pas répondu à temps. */
+const AUTHENTICATE_TIMED_OUT = Symbol("authenticate-timed-out");
+/**
+* Budget des admissions d'UN exemplaire — appels d'`allow` en vol, coupe-circuit et compteurs de refus (ADR-0021 §S10 bis point 3, §S9).
+*
+* Partagé par toutes les connexions du hub ; chaque connexion garde sa propre
+* file ({@link ConnectionAdmission}). Aucune horloge n'est lue tant que le
+* coupe-circuit est fermé : une règle synchrone ne paie que deux incréments.
+*/
+var AdmissionBudget = class {
+	/** Délai de l'authentification à la poignée de main (ADR-0021 §S11). */
+	authenticateTimeoutMs = 1e4;
+	/** Délai d'un appel d'`allow`, compté depuis la réception du `subscribe`, file comprise. */
+	timeoutMs = 5e3;
+	/** Appels d'`allow` en vol par connexion ; au-delà, la demande attend son tour. */
+	maxPerConnection = 8;
+	#maxTotal = 512;
+	#pending = 0;
+	#timedOutTotal = 0;
+	#saturatedTotal = 0;
+	#authenticateTimedOutTotal = 0;
+	#windowStart = -Infinity;
+	#windowTimeouts = 0;
+	#openUntil = 0;
+	#lastTimeoutWarn = -Infinity;
+	#lastThrowWarn = -Infinity;
+	#lastAuthenticateWarn = -Infinity;
+	/** Applique les bornes de la configuration (boot, cold path). */
+	configure(limits) {
+		this.authenticateTimeoutMs = limits.authenticateTimeoutMs;
+		this.timeoutMs = limits.allowTimeoutMs;
+		this.maxPerConnection = limits.maxPendingAllowsPerConnection;
+		this.#maxTotal = limits.maxPendingAllowsTotal;
+	}
+	/**
+	* Réserve une place pour UN appel d'`allow`.
+	*
+	* @returns {@link ADMISSION_GRANTED} si la place est prise ; sinon la demande
+	*   est comptée dans `allowSaturatedTotal` et la valeur rendue est le délai à
+	*   annoncer au client (`retryAfterMs`, coupe-circuit ouvert), ou `0` quand il
+	*   n'est pas connu (plafond global atteint).
+	*/
+	acquire() {
+		if (this.#openUntil !== 0) {
+			const now = performance.now();
+			if (now < this.#openUntil) {
+				this.#saturatedTotal += 1;
+				return Math.ceil(this.#openUntil - now);
+			}
+			this.#openUntil = 0;
+		}
+		if (this.#pending >= this.#maxTotal) {
+			this.#saturatedTotal += 1;
+			return 0;
+		}
+		this.#pending += 1;
+		return -1;
+	}
+	/** Rend la place d'un appel terminé, dépassé ou abandonné à la fermeture. */
+	release() {
+		if (this.#pending > 0) this.#pending -= 1;
+	}
+	/** Un appel d'`allow` n'a pas répondu dans son délai : compté, et porté au coupe-circuit. */
+	recordTimeout(now) {
+		this.#timedOutTotal += 1;
+		if (now - this.#windowStart >= BREAKER_WINDOW_MS) {
+			this.#windowStart = now;
+			this.#windowTimeouts = 0;
+		}
+		this.#windowTimeouts += 1;
+		if (this.#windowTimeouts >= BREAKER_THRESHOLD) {
+			this.#openUntil = now + BREAKER_OPEN_MS;
+			this.#windowTimeouts = 0;
+		}
+	}
+	/** Une demande a épuisé son délai dans la file, sans appel d'`allow`. */
+	recordQueueExpired() {
+		this.#saturatedTotal += 1;
+	}
+	/** Délai restant du coupe-circuit à `now`, ou `undefined` s'il est fermé. */
+	retryAfter(now) {
+		return this.#openUntil > now ? Math.ceil(this.#openUntil - now) : void 0;
+	}
+	/** Faut-il journaliser cette cause maintenant ? Vrai au plus une fois par fenêtre et par cause. */
+	shouldWarn(kind, now) {
+		if (kind === "authenticate") {
+			if (now - this.#lastAuthenticateWarn < WARN_INTERVAL_MS) return false;
+			this.#lastAuthenticateWarn = now;
+			return true;
+		}
+		if (kind === "timeout") {
+			if (now - this.#lastTimeoutWarn < WARN_INTERVAL_MS) return false;
+			this.#lastTimeoutWarn = now;
+			return true;
+		}
+		if (now - this.#lastThrowWarn < WARN_INTERVAL_MS) return false;
+		this.#lastThrowWarn = now;
+		return true;
+	}
+	/**
+	* Borne l'authentification d'une poignée de main par `authenticateTimeoutMs` (ADR-0021 §S11).
+	*
+	* Une identité arrivée après le délai est IGNORÉE : la promesse rendue est
+	* déjà réglée sur {@link AUTHENTICATE_TIMED_OUT}, et un rejet tardif ne lève
+	* rien (la promesse d'origine garde son gestionnaire). Le minuteur est coupé
+	* dès la réponse et ne retient pas le processus à l'arrêt. Chaque dépassement
+	* compte une poignée de main dans `authenticateTimedOutTotal`.
+	*
+	* @param pending - la promesse rendue par `authenticate()`
+	* @returns le jeton, ou {@link AUTHENTICATE_TIMED_OUT} au dépassement
+	*/
+	authenticateWithin(pending) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.#authenticateTimedOutTotal++;
+				resolve(AUTHENTICATE_TIMED_OUT);
+			}, this.authenticateTimeoutMs);
+			timer.unref();
+			pending.then((value) => {
+				clearTimeout(timer);
+				resolve(value);
+			}, (error) => {
+				clearTimeout(timer);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
+		});
+	}
+	/** Appels d'`allow` en vol sur l'exemplaire. */
+	get pending() {
+		return this.#pending;
+	}
+	/** Cumul `allowTimedOutTotal` — unité : un appel d'`allow`. */
+	get timedOutTotal() {
+		return this.#timedOutTotal;
+	}
+	/** Cumul `allowSaturatedTotal` — unité : une demande d'abonnement. */
+	get saturatedTotal() {
+		return this.#saturatedTotal;
+	}
+	/** Cumul `authenticateTimedOutTotal` — unité : une poignée de main. */
+	get authenticateTimedOutTotal() {
+		return this.#authenticateTimedOutTotal;
+	}
+	/** Remet compteurs, coupe-circuit et bornes à leurs défauts (hub vidé). */
+	reset() {
+		this.authenticateTimeoutMs = 1e4;
+		this.#authenticateTimedOutTotal = 0;
+		this.#lastAuthenticateWarn = -Infinity;
+		this.timeoutMs = 5e3;
+		this.maxPerConnection = 8;
+		this.#maxTotal = 512;
+		this.#pending = 0;
+		this.#timedOutTotal = 0;
+		this.#saturatedTotal = 0;
+		this.#windowStart = -Infinity;
+		this.#windowTimeouts = 0;
+		this.#openUntil = 0;
+		this.#lastTimeoutWarn = -Infinity;
+		this.#lastThrowWarn = -Infinity;
+	}
+};
+export { ADMISSION_GRANTED, AUTHENTICATE_TIMED_OUT, AdmissionBudget };

package/dist/nodefony/src/server/channelPolicyRegistry.js

@@ -0,0 +1,73 @@
+import { declaresAction, getChannelPoliciesOf, isAdmissionClass } from "../../decorators/realtimeDecorators.js";
+import { BootConfigurationError, Injector } from "nodefony";
+// nodefony/src/server/channelPolicyRegistry.ts
+/**
+* Inscrit au hub les politiques déclarées par une classe de contrôleur — une fois par classe et par hub, et seulement si l'inscription entière réussit.
+*
+* Appelée pour chaque contrôleur connu au démarrage du noyau, puis à la
+* poignée de main pour une classe qui y aurait échappé : celle-ci ne paie alors
+* qu'un `has`. Une politique refusée ne marque PAS la classe — elle est refusée
+* de nouveau à la poignée de main suivante plutôt que de laisser le canal
+* ouvert.
+*
+* @param hub - le hub qui porte le registre.
+* @param ctor - constructeur du contrôleur.
+* @param resolveAdmission - résolution des classes d'admission ; `null` hors
+*   démarrage, et le hub refuse alors une politique qui en désigne une.
+* @throws BootConfigurationError Politique illisible, `allow` posé sur une
+*   action, ou classe d'admission non résolue.
+*/
+function registerControllerPolicies(hub, ctor, resolveAdmission) {
+	if (hub.hasPolicyOwner(ctor)) return;
+	const policies = getChannelPoliciesOf(ctor);
+	if (policies !== null) for (const name in policies) {
+		const policy = policies[name];
+		if (policy === void 0) continue;
+		const allow = policy.allow;
+		let admission;
+		if (allow !== void 0) {
+			if (declaresAction(ctor, name)) throw new BootConfigurationError(`${typeof ctor === "function" ? ctor.name : "(contrôleur)"} : « allow » est posé sur l'action « ${name} » — il ne s'applique qu'aux canaux (demandé au subscribe). Une action se garde par authenticated, roles ou scopes.`);
+			if (isAdmissionClass(allow) && resolveAdmission !== null) admission = resolveAdmission(allow, name);
+		}
+		hub.registerChannelPolicy(name, policy, admission);
+	}
+	hub.addPolicyOwner(ctor);
+}
+/**
+* Fabrique la résolution des classes d'admission du démarrage : portée singleton exigée, instance du conteneur réutilisée, sinon construite UNE fois par l'injecteur.
+*
+* @param get - l'instance déjà construite d'une classe : le démarrage la lit
+*   dans le conteneur du noyau par sa clé (`null` tant que la classe n'y a
+*   jamais été rangée), le harnais de test parmi les instances que le test lui
+*   donne. `undefined` → construite par l'injecteur.
+* @param log - journal du module (une ligne par canal résolu).
+* @returns le résolveur, qui mémorise l'instance de chaque classe.
+*/
+function createAdmissionResolver(get, log) {
+	const resolved = /* @__PURE__ */ new Map();
+	return (admissionClass, channel) => {
+		let admission = resolved.get(admissionClass);
+		if (admission === void 0) {
+			admission = resolveAdmissionInstance(admissionClass, channel, get);
+			resolved.set(admissionClass, admission);
+		}
+		log(`canal ${channel}, admission ${admissionClass.name}, résolue`);
+		return admission;
+	};
+}
+/** Résout l'instance d'une classe d'admission ou refuse le démarrage en nommant la classe ET le canal. */
+function resolveAdmissionInstance(admissionClass, channel, get) {
+	const where = `canal temps réel « ${channel} » : la classe d'admission ${admissionClass.name}`;
+	if (!Injector.isInjectable(admissionClass)) throw new BootConfigurationError(`${where} ne porte pas @injectable`);
+	const scope = Injector.scopeOf(admissionClass);
+	if (scope !== "singleton") throw new BootConfigurationError(`${where} est de portée « ${scope} » : une seule instance sert tous les abonnés en même temps, elle doit être un singleton (et ne garder aucun état par abonné).`);
+	let instance = get(Injector.containerKeyOf(admissionClass), admissionClass);
+	if (!(instance instanceof admissionClass)) try {
+		instance = Injector.instantiate(admissionClass);
+	} catch (error) {
+		throw new BootConfigurationError(`${where} ne se résout pas — ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (!(instance instanceof admissionClass) || typeof instance.allow !== "function") throw new BootConfigurationError(`${where} n'a pas de méthode allow`);
+	return instance;
+}
+export { createAdmissionResolver, registerControllerPolicies };

package/dist/nodefony/src/server/connectionAdmission.js

@@ -0,0 +1,242 @@
+import "./admissionBudget.js";
+import resolveBackplaneOriginId from "../backplane/originId.js";
+import { isPromise } from "nodefony";
+// nodefony/src/server/connectionAdmission.ts
+const QUEUED = 0;
+const IN_FLIGHT = 1;
+const DONE = 2;
+/**
+* Admission des abonnements d'UNE connexion aux canaux qui déclarent `allow` — appels bornés, file d'attente, délai, verdict (ADR-0021 §S10 et §S10 bis).
+*
+* Coûts, par construction :
+* - une règle qui répond `true`/`false` sans promesse ne crée ni minuteur, ni
+*   promesse, ni entrée d'attente ;
+* - au-delà de `maxPendingAllowsPerConnection` appels en vol, la demande ATTEND
+*   son tour (jamais `limit` : le rejeu au `welcome` renvoie tous les canaux
+*   d'un coup) ; la file reste `null` tant que personne n'attend ;
+* - un seul minuteur par connexion, armé sur l'échéance de tête : les demandes
+*   arrivent dans l'ordre de leurs échéances, la plus ancienne non tranchée est
+*   donc toujours la prochaine à expirer.
+*
+* Seul `=== true` admet ; une exception ou un rejet valent `forbidden` ; un
+* délai dépassé ou une saturation valent `unavailable`, et un verdict arrivé
+* après coup est ignoré.
+*/
+var ConnectionAdmission = class {
+	#host;
+	#budget;
+	#who;
+	#explain;
+	#pending = null;
+	#inFlight = 0;
+	#timer = null;
+	#onTimer = null;
+	/**
+	* @param host - la connexion qui ouvre ou refuse.
+	* @param budget - le budget de l'exemplaire (plafond global, coupe-circuit).
+	* @param who - identité d'admission gelée de la connexion.
+	* @param explain - rédiger le détail des refus (hors production).
+	*/
+	constructor(host, budget, who, explain) {
+		this.#host = host;
+		this.#budget = budget;
+		this.#who = who;
+		this.#explain = explain;
+	}
+	/** Demandes en attente de verdict — comptées dans le plafond de canaux de la connexion. */
+	get unsettled() {
+		return this.#pending === null ? 0 : this.#pending.size;
+	}
+	/**
+	* Un abonnement à ce canal attend-il déjà son verdict ? S'il avait été annulé par un `unsubscribe`, il est ranimé : le verdict à venir répondra.
+	*
+	* @returns `true` si la demande est déjà en attente (rien d'autre à faire).
+	*/
+	revive(channel) {
+		const record = this.#pending?.get(channel);
+		if (record === void 0) return false;
+		record.cancelled = false;
+		return true;
+	}
+	/** `unsubscribe` pendant l'attente : le verdict à venir sera jeté sans réponse. */
+	cancel(channel) {
+		const record = this.#pending?.get(channel);
+		if (record !== void 0) record.cancelled = true;
+	}
+	/**
+	* Demande l'admission sur `channel` selon sa règle — l'anonyme est refusé d'office sauf `anonymous: true`.
+	*
+	* @param channel - nom exact du canal demandé.
+	* @param rule - règle résolue par le hub pour ce canal.
+	*/
+	request(channel, rule) {
+		if (!this.#who.authenticated && !rule.anonymous) {
+			this.#host.deny(channel, "forbidden", this.#explain ? `le canal « ${channel} » déclare une règle d'admission (allow) : une connexion anonyme n'y entre pas sans \`anonymous: true\` dans sa politique` : void 0);
+			return;
+		}
+		if (this.#inFlight >= this.#budget.maxPerConnection) {
+			this.#track(channel, rule, QUEUED);
+			return;
+		}
+		this.#call(channel, rule, null);
+	}
+	/** Fermeture de la connexion : minuteur coupé, places rendues, verdicts à venir jetés. */
+	close() {
+		if (this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+		const pending = this.#pending;
+		if (pending !== null) {
+			for (const record of pending.values()) {
+				if (record.status === IN_FLIGHT) this.#budget.release();
+				record.status = DONE;
+			}
+			this.#pending = null;
+		}
+		this.#inFlight = 0;
+	}
+	/** Appelle `allow` ; `record` est `null` pour une demande qui n'a pas attendu. */
+	#call(channel, rule, record) {
+		const granted = this.#budget.acquire();
+		if (granted !== -1) {
+			if (record !== null) this.#finish(record);
+			this.#host.deny(channel, "unavailable", !this.#explain ? void 0 : granted > 0 ? `admissions suspendues pendant ${granted} ms après une série de règles allow sans réponse sur ce serveur — réessaie après ce délai` : "trop d'admissions en cours sur ce serveur (maxPendingAllowsTotal) — réessaie", granted > 0 ? granted : void 0);
+			return;
+		}
+		let verdict;
+		try {
+			verdict = rule.allow(channel, this.#who);
+		} catch (error) {
+			this.#budget.release();
+			if (record !== null) this.#finish(record);
+			this.#refuseOnError(channel, error);
+			return;
+		}
+		if (!isPromise(verdict)) {
+			this.#budget.release();
+			if (record !== null) this.#finish(record);
+			this.#conclude(channel, verdict);
+			return;
+		}
+		const tracked = record ?? this.#track(channel, rule, IN_FLIGHT);
+		tracked.status = IN_FLIGHT;
+		this.#inFlight += 1;
+		verdict.then((value) => {
+			if (this.#settle(tracked)) this.#conclude(tracked.channel, value);
+			this.#pump();
+		}, (error) => {
+			if (this.#settle(tracked)) this.#refuseOnError(tracked.channel, error);
+			this.#pump();
+		});
+	}
+	/** Verdict d'une règle : seul `true` admet. */
+	#conclude(channel, verdict) {
+		if (verdict === true) {
+			this.#open(channel);
+			return;
+		}
+		this.#host.deny(channel, "forbidden", !this.#explain ? void 0 : verdict === false ? `la règle d'admission (allow) du canal « ${channel} » a refusé cette identité` : `la règle d'admission (allow) du canal « ${channel} » a rendu une valeur de type ${typeof verdict} : seul \`true\` admet`);
+	}
+	/** Une règle qui lève ou rejette refuse (fail-closed) ; le message ne part au client qu'hors production. */
+	#refuseOnError(channel, error) {
+		const warn = this.#budget.shouldWarn("throw", performance.now());
+		const message = warn || this.#explain ? error instanceof Error ? error.message : String(error) : "";
+		if (warn) this.#host.warn(`règle d'admission (allow) du canal « ${channel} » en échec : ${message}`);
+		this.#host.deny(channel, "forbidden", this.#explain ? `la règle d'admission (allow) du canal « ${channel} » a levé : ${message}` : void 0);
+	}
+	/** Ouvre le canal admis ; un échec d'ouverture est journalisé, jamais propagé (rappel de promesse ou de minuteur). */
+	#open(channel) {
+		try {
+			this.#host.open(channel);
+		} catch (error) {
+			this.#host.warn(`canal « ${channel} » admis mais non ouvert : ` + (error instanceof Error ? error.message : String(error)));
+		}
+	}
+	/**
+	* Termine un appel en vol dont le verdict arrive.
+	*
+	* @returns `false` si la demande est déjà tranchée (délai dépassé, connexion
+	*   fermée) ou annulée : le verdict est alors jeté.
+	*/
+	#settle(record) {
+		if (record.status === DONE) return false;
+		this.#inFlight -= 1;
+		this.#budget.release();
+		this.#finish(record);
+		return !record.cancelled;
+	}
+	/** Inscrit une demande qui attend ; arme le minuteur s'il ne l'est pas déjà sur une échéance plus proche. */
+	#track(channel, rule, status) {
+		const deadline = performance.now() + this.#budget.timeoutMs;
+		const record = {
+			channel,
+			rule,
+			deadline,
+			status,
+			cancelled: false
+		};
+		(this.#pending ??= /* @__PURE__ */ new Map()).set(channel, record);
+		if (this.#timer === null) this.#arm(deadline);
+		return record;
+	}
+	/** Marque une demande tranchée et la retire ; plus rien en attente → minuteur coupé. */
+	#finish(record) {
+		record.status = DONE;
+		const pending = this.#pending;
+		if (pending === null) return;
+		pending.delete(record.channel);
+		if (pending.size === 0 && this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+	}
+	/** Lance les demandes en attente, dans l'ordre, tant que des places se libèrent. */
+	#pump() {
+		while (this.unsettled > this.#inFlight && this.#inFlight < this.#budget.maxPerConnection) {
+			const record = this.#nextQueued();
+			if (record === null) return;
+			if (record.cancelled) {
+				this.#finish(record);
+				continue;
+			}
+			this.#call(record.channel, record.rule, record);
+		}
+	}
+	/** Première demande qui n'a pas encore appelé `allow` — les appels en vol, au plus `maxPerConnection`, la précèdent. */
+	#nextQueued() {
+		if (this.#pending === null) return null;
+		for (const record of this.#pending.values()) if (record.status === QUEUED) return record;
+		return null;
+	}
+	#arm(deadline) {
+		this.#timer = setTimeout(this.#onTimer ??= () => this.#expire(), Math.max(1, Math.ceil(deadline - performance.now())));
+		this.#timer.unref();
+	}
+	/** Échéance de tête atteinte : tranche en `unavailable` toutes les demandes échues, puis réarme sur la suivante. */
+	#expire() {
+		this.#timer = null;
+		const pending = this.#pending;
+		if (pending === null) return;
+		const now = performance.now();
+		let timedOut = null;
+		for (const record of pending.values()) {
+			if (record.deadline > now) {
+				this.#arm(record.deadline);
+				break;
+			}
+			const called = record.status === IN_FLIGHT;
+			if (called) {
+				this.#inFlight -= 1;
+				this.#budget.release();
+				this.#budget.recordTimeout(now);
+				timedOut = record.channel;
+			} else this.#budget.recordQueueExpired();
+			this.#finish(record);
+			if (!record.cancelled) this.#host.deny(record.channel, "unavailable", !this.#explain ? void 0 : called ? `la règle d'admission (allow) du canal « ${record.channel} » n'a pas répondu en ${this.#budget.timeoutMs} ms (allowTimeoutMs) — réessaie` : `demande d'abonnement à « ${record.channel} » restée en attente ${this.#budget.timeoutMs} ms derrière les admissions de cette connexion (allowTimeoutMs) — réessaie`, this.#budget.retryAfter(now));
+		}
+		if (timedOut !== null && this.#budget.shouldWarn("timeout", now)) this.#host.warn(`règle d'admission (allow) du canal « ${timedOut} » sans réponse en ${this.#budget.timeoutMs} ms (exemplaire ${resolveBackplaneOriginId()})`);
+		this.#pump();
+	}
+};
+export { ConnectionAdmission };

package/dist/nodefony/src/server/contractRoutes.js

@@ -0,0 +1,85 @@
+import { isRecord } from "../guards.js";
+import { BootConfigurationError, isSimpleRouteTemplate } from "nodefony";
+// nodefony/src/server/contractRoutes.ts
+const BRIDGE_VERBS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+const ROUTE_PARTS = [
+	"body",
+	"query",
+	"params"
+];
+/** Chemin comparable : barres finales retirées, la racine reste `/`. */
+function normalizePath(path) {
+	let end = path.length;
+	while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+	return end === path.length ? path : path.slice(0, end);
+}
+/**
+* La route sert-elle CE verbe par le pont ? Le pont résout sur le transport
+* `WEBSOCKET` ; une écriture exige EN PLUS sa méthode logique
+* (`Router.resolve`, `methodOverride`).
+*/
+function servesByBridge(methods, verb) {
+	if (methods === void 0) return true;
+	if (!methods.has("WEBSOCKET")) return false;
+	return verb === "GET" || methods.has(verb);
+}
+/**
+* Lit la table `serverRoutes` qu'une classe de contrôleur déclare en statique —
+* `null` quand elle n'en déclare pas (aucun contrôle).
+*
+* @param ctor - la classe du contrôleur.
+* @returns la table, ou `null`.
+* @throws BootConfigurationError si la table n'est pas un objet.
+*/
+function readContractRoutes(ctor) {
+	const table = Reflect.get(ctor, "serverRoutes");
+	if (table === void 0) return null;
+	if (!isRecord(table)) throw new BootConfigurationError(`${typeof ctor === "function" ? ctor.name : "(contrôleur)"} : « serverRoutes » doit être un objet { "<VERBE> <chemin>": { body?, query? } }.`);
+	return table;
+}
+/**
+* Vérifie, au démarrage, que chaque route du contrat est SERVIE par le pont :
+* une route montée au même chemin, qui accepte le verbe par la socket, et dont
+* les schémas sont LES MÊMES OBJETS que ceux que la table déclare. Coût nul par
+* requête : la vérification n'a lieu qu'une fois.
+*
+* Sans elle, un contrat qui type `chat.post("/chat/send", …)` compilerait
+* contre une route absente, servie en HTTP seulement, ou validant un autre
+* schéma — et l'erreur n'apparaîtrait qu'au premier appel.
+*
+* @param owner - nom de la classe qui déclare la table (pour le message).
+* @param table - la table `serverRoutes` (`"<VERBE> <chemin>"` → `{ body?, query? }`).
+* @param mounted - les routes montées.
+* @throws BootConfigurationError à la première entrée qui n'est pas servie ;
+*   le message nomme la classe, l'entrée et la cause.
+*/
+function assertContractRoutes(owner, table, mounted) {
+	for (const entry in table) {
+		const where = `${owner}.serverRoutes « ${entry} »`;
+		const space = entry.indexOf(" ");
+		const verb = space === -1 ? "" : entry.slice(0, space);
+		const rawPath = space === -1 ? "" : entry.slice(space + 1);
+		if (!BRIDGE_VERBS.has(verb) || rawPath.charCodeAt(0) !== 47) throw new BootConfigurationError(`${where} : la clé s'écrit "<VERBE> <chemin>", VERBE parmi ${[...BRIDGE_VERBS].join(", ")}, chemin commençant par « / ».`);
+		const declared = table[entry];
+		if (!isRecord(declared)) throw new BootConfigurationError(`${where} : la valeur s'écrit { body?, query?, params? } (les schémas de la route).`);
+		for (const key in declared) if (key !== "body" && key !== "query" && key !== "params") throw new BootConfigurationError(`${where} : clé « ${key} » inconnue — seuls body, query et params se déclarent.`);
+		if (!isSimpleRouteTemplate(rawPath)) throw new BootConfigurationError(`${where} : seuls des segments « {nom} » entiers se déclarent dans un contrat — pas de contrainte en ligne « {id}(\\d+) », de segment facultatif « {slug}? » ni de variable collée « .{format} ». Contraindre la variable par « requirements » sur la route.`);
+		const path = normalizePath(rawPath);
+		const atPath = mounted.filter((r) => normalizePath(r.path) === path);
+		if (atPath.length === 0) throw new BootConfigurationError(`${where} : aucune route montée au chemin ${path}.`);
+		const route = atPath.find((r) => servesByBridge(r.methods, verb));
+		if (route === void 0) throw new BootConfigurationError(`${where} : la route ${path} ne sert pas ${verb} par la socket — ses méthodes doivent inclure ${verb === "GET" ? "" : `"${verb}" et `}"WEBSOCKET".`);
+		for (const part of ROUTE_PARTS) {
+			const expected = declared[part];
+			const actual = route.schema?.[part];
+			if (expected !== actual) throw new BootConfigurationError(`${where} : le schéma « ${part} » ${expected === void 0 ? "n'est pas déclaré, mais la route en valide un" : actual === void 0 ? "est déclaré, mais la route n'en valide aucun" : "n'est pas celui que la route valide (même objet attendu)"}.`);
+		}
+	}
+}
+export { assertContractRoutes, readContractRoutes };

package/dist/nodefony/src/server/deniedDetail.js

@@ -22,7 +22,14 @@
 *   sinon un objet vide.
 */
 function deniedDetail(env, detail) {
-	if (!env || env === "production") return {};
-	return { detail };
+	return explainsDenials(env) ? { detail } : {};
 }
-export { deniedDetail };
+/**
+* Le détail d'un refus part-il au client dans ce mode ? Hors production seulement — la règle de {@link deniedDetail}, lue AVANT de rédiger la phrase : en production, aucune chaîne n'est composée pour être jetée.
+*
+* @param env - le mode du kernel serveur, s'il est connu ; une absence vaut production.
+*/
+function explainsDenials(env) {
+	return !!env && env !== "production";
+}
+export { deniedDetail, explainsDenials };