@nodefony/realtime 10.0.0-alpha.8 → 10.0.0-beta.1

package/dist/_virtual/{_@oxc-project_runtime@0.150.0 → _@oxc-project_runtime@0.151.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.150.0 → _@oxc-project_runtime@0.151.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/index.js

@@ -15,8 +15,8 @@ import { ClusterBackplane, processIpcTransport } from "./nodefony/src/backplane/
 import { getBackplaneDriver, listBackplaneDrivers, registerBackplaneDriver } from "./nodefony/src/backplane/backplaneRegistry.js";
 import { ClusterProbeClient, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient } from "./nodefony/src/cluster/ClusterProbeClient.js";
 import { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi } from "./nodefony/src/server/RealtimeAdminApi.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
 import { Kernel, Module, services, withTimeout } from "nodefony";
 //#region index.ts
 /**

package/dist/nodefony/src/backplane/envelope.js

@@ -99,7 +99,8 @@ function openBackplaneEnvelope(raw, secret) {
 	if (!secret) return msg;
 	const provided = parsed[SEAL_FIELD];
 	if (typeof provided !== "string") return null;
-	const expected = seal(JSON.stringify(msg.originId), JSON.stringify(msg.channel), JSON.stringify(msg.payload) ?? "null", secret);
+	const payloadText = JSON.stringify(msg.payload);
+	const expected = seal(JSON.stringify(msg.originId), JSON.stringify(msg.channel), payloadText ?? "null", secret);
 	const a = Buffer.from(provided, "base64url");
 	const b = Buffer.from(expected, "base64url");
 	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;

package/dist/nodefony/src/cluster/ClusterProbeClient.js

@@ -136,7 +136,7 @@ var ClusterProbeClient = class {
 	#report(buildOwn) {
 		const payload = buildOwn();
 		if (this.#richEnabled) {
-			if (this.#richProbe === null) this.#richProbe = new RichProcessProbe();
+			this.#richProbe ??= new RichProcessProbe();
 			payload.rich = this.#richProbe.read();
 		}
 		if (this.#ormRich !== null) payload.ormRich = this.#ormRich;

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

@@ -5,7 +5,7 @@ import { createSyslogUplinkHandler } from "./syslogUplink.js";
 import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
 import { welcomeEnv } from "./welcomeEnv.js";
 import { deniedDetail } from "./deniedDetail.js";
-import { JsonRpcPeer, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, identityHint } from "nodefony";
+import { BootConfigurationError, JsonRpcPeer, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint } from "nodefony";
 import { readBackpressureOptions } from "@nodefony/http";
 import { Controller } from "@nodefony/framework";
 //#region nodefony/src/server/RealtimeController.ts
@@ -77,6 +77,36 @@ let warnedUnenforcedPolicies = false;
 * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
 */
 var RealtimeController = class extends Controller {
+	/**
+	* Une instance PAR CONNEXION, par construction — le défaut `singleton` des
+	* contrôleurs ne s'applique pas ici. Le pair JSON-RPC de la connexion capture
+	* l'instance du handshake, et {@link notifyClient} / {@link requestClient}
+	* désignent « CETTE connexion » par l'instance : partagée, ils liraient
+	* l'ALS de celui qui ÉMET (un écouteur du hub, un minuteur), donc une autre
+	* connexion, ou aucune. Cf {@link assertScope}.
+	*/
+	static scope = "request";
+	/**
+	* Refuse qu'une sous-classe se déclare singleton — au démarrage
+	* (`Router.setController`), et au constructeur pour qui construit par `new`
+	* hors du routeur (harnais de test). Sans ce refus, la socket s'ouvrirait
+	* sans jamais émettre `realtime:welcome` : une panne indiscernable d'un
+	* incident réseau.
+	*
+	* @throws BootConfigurationError si la classe se déclare `@Scope("singleton")`.
+	*/
+	static assertScope() {
+		if (this.scope === "singleton") throw new BootConfigurationError(`Contrôleur temps réel « ${this.name} » déclaré @Scope("singleton") : un RealtimeController vit PAR CONNEXION — son pair JSON-RPC et notifyClient/requestClient désignent la connexion par l'instance. Retirer @Scope("singleton") : la portée d'un RealtimeController est request (une instance par connexion).`);
+	}
+	/**
+	* @param name - nom du service (celui de la classe, par convention).
+	* @param context - le contexte de la connexion.
+	* @throws BootConfigurationError si la classe se déclare singleton.
+	*/
+	constructor(name, context) {
+		new.target.assertScope();
+		super(name, context);
+	}
 	/**
 	* Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
 	* au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur
@@ -161,7 +191,10 @@ var RealtimeController = class extends Controller {
 		const ctx = this.context;
 		if (!ctx) return;
 		if (message == null) {
-			this.onHandshake(ctx);
+			this.onHandshake(ctx).catch((e) => {
+				this.log(`WS realtime handshake failed: ${e instanceof Error ? e.message : String(e)}`, "ERROR");
+				ctx.connection?.close(1011, "internal error");
+			});
 			return;
 		}
 		ctx.__nfRealtime?.transport.feed(message.toString());
@@ -224,7 +257,7 @@ var RealtimeController = class extends Controller {
 		}
 		const authenticator = hub.resolveAuthenticator(handshake);
 		let token;
-		if (authenticator !== null && authenticator.supports(handshake)) try {
+		if (authenticator?.supports(handshake)) try {
 			token = await authenticator.authenticate(handshake);
 			authenticator.onSuccess?.(handshake, token);
 		} catch (e) {
@@ -301,13 +334,17 @@ var RealtimeController = class extends Controller {
 		this._decoratedChannels = getRealtimeChannels(this);
 		const channelPolicies = getRealtimeChannelPolicies(this);
 		if (channelPolicies) {
-			for (const name in channelPolicies) hub.registerChannelPolicy(name, channelPolicies[name]);
+			for (const [name, policy] of Object.entries(channelPolicies)) hub.registerChannelPolicy(name, policy);
 			if (hub.hasUnenforcedChannelPolicies() && !warnedUnenforcedPolicies) {
 				warnedUnenforcedPolicies = true;
 				this.log("Realtime channel policies declared but NO frame authorizer is wired — these policies are NOT enforced (a protected channel is currently open). Load @nodefony/security with a realtime zone to enforce them.", "WARNING");
 			}
 		}
-		hub.onPlatformNotice((message, severity) => this.log(message, severity));
+		const noticeSyslog = this.syslog;
+		const noticeName = this.name;
+		hub.onPlatformNotice((message, severity) => {
+			noticeSyslog?.log(message, severity, noticeName);
+		});
 		hub.registerConnection(transport);
 		let revocable = null;
 		if (typeof token.isValid === "function") {
@@ -318,7 +355,7 @@ var RealtimeController = class extends Controller {
 			hub.registerRevocable(revocable);
 		}
 		const broadcast = this.realtimeBroadcastChannels();
-		for (let i = 0; i < broadcast.length; i++) hub.markBroadcastChannel(broadcast[i]);
+		for (const channel of broadcast) hub.markBroadcastChannel(channel);
 		const decoratedInbound = getRealtimeInbound(this);
 		const overrideInbound = this.realtimeInbound();
 		const inboundMap = {
@@ -326,7 +363,7 @@ var RealtimeController = class extends Controller {
 			...overrideInbound
 		};
 		const clientLogs = hub.clientLogsLimits;
-		if (clientLogs !== null && inboundMap[PLATFORM_INBOUND.syslogUplink] === void 0) {
+		if (clientLogs !== null && !Object.hasOwn(inboundMap, PLATFORM_INBOUND.syslogUplink)) {
 			const syslog = this.syslog;
 			if (syslog) inboundMap[PLATFORM_INBOUND.syslogUplink] = createSyslogUplinkHandler({
 				syslog,
@@ -342,7 +379,7 @@ var RealtimeController = class extends Controller {
 			inbound
 		};
 		holder.__nfRealtime = state;
-		ctx.once?.("onFinish", () => {
+		ctx.once("onFinish", () => {
 			const liveHub = getRealtimeHub();
 			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
 			state.channels.clear();
@@ -412,6 +449,7 @@ var RealtimeController = class extends Controller {
 			else state.peer.notify(channel, payload);
 		};
 		let servedByPattern = false;
+		const isServedByPattern = () => servedByPattern;
 		if (getRealtimeHub().subscribeClient(channel, sink, (ch, publish) => {
 			const decFactory = this._decoratedChannels?.[ch];
 			if (decFactory) return decFactory(ch, publish);
@@ -420,7 +458,7 @@ var RealtimeController = class extends Controller {
 			return dispose;
 		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
 			state.channels.set(channel, sink);
-			if (servedByPattern) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
+			if (isServedByPattern()) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
 			this.log(`WS subscribe → ${channel}`, "DEBUG");
 			return;
 		}
@@ -505,6 +543,8 @@ var RealtimeController = class extends Controller {
 				user: token.getAttribute("user"),
 				userId: token.getUserIdentifier(),
 				context: ctx,
+				resolver,
+				scope: ctx.container instanceof Scope ? ctx.container : void 0,
 				body: p?.body,
 				idempotencyKey: typeof p?.idempotencyKey === "string" ? p.idempotencyKey : void 0,
 				renderSink,
@@ -542,7 +582,8 @@ var RealtimeController = class extends Controller {
 	stopChannel(ctx, channel) {
 		if (!channel) return;
 		const state = ctx.__nfRealtime;
-		const sink = state?.channels.get(channel);
+		if (!state) return;
+		const sink = state.channels.get(channel);
 		if (sink) {
 			getRealtimeHub().unsubscribe(channel, sink);
 			state.channels.delete(channel);
@@ -564,7 +605,7 @@ var RealtimeController = class extends Controller {
 function buildHandshakeFromContext(ctx) {
 	const headers = ctx.request?.headers ?? {};
 	const cookies = /* @__PURE__ */ new Map();
-	const rawCookies = ctx.cookies ?? {};
+	const rawCookies = ctx.cookies;
 	for (const name in rawCookies) {
 		const c = rawCookies[name];
 		if (c && typeof c.value === "string") cookies.set(name, c.value);

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

@@ -273,14 +273,15 @@ var RealtimeHub = class RealtimeHub {
 	* et retire le canal (libère timers/listeners). No-op si non abonné.
 	*/
 	unsubscribe(channel, sink) {
-		const st = this.#channels?.get(channel);
-		if (!st) return;
+		const channels = this.#channels;
+		const st = channels?.get(channel);
+		if (!channels || !st) return;
 		st.sinks.delete(sink);
 		if (st.sinks.size === 0) {
 			try {
 				st.dispose?.();
 			} catch {}
-			this.#channels.delete(channel);
+			channels.delete(channel);
 		}
 	}
 	/**
@@ -356,7 +357,7 @@ var RealtimeHub = class RealtimeHub {
 	#isBroadcast(channel) {
 		const prefixes = this.#broadcastPrefixes;
 		if (prefixes === null) return false;
-		for (let i = 0; i < prefixes.length; i++) if (channel.startsWith(prefixes[i])) return true;
+		for (const prefix of prefixes) if (channel.startsWith(prefix)) return true;
 		return false;
 	}
 	/**
@@ -372,7 +373,11 @@ var RealtimeHub = class RealtimeHub {
 	setBackplane(backplane) {
 		this.#backplane = backplane;
 		backplane.onMessage((msg) => this.#admitFromBackplane(msg));
-		backplane.start();
+		const started = backplane.start();
+		if (started instanceof Promise) started.catch((err) => {
+			if (this.#notice === null) throw err instanceof Error ? err : new Error(String(err));
+			this.#notifyOnce("backplane:start", `realtime: démarrage du backplane en échec — les autres pairs ne recevront rien (${err instanceof Error ? err.message : String(err)})`);
+		});
 		return backplane;
 	}
 	/**
@@ -433,7 +438,7 @@ var RealtimeHub = class RealtimeHub {
 			this.#revalidateTimer = setInterval(() => {
 				this.revalidateRevocable();
 			}, REVOCATION_REVALIDATE_MS);
-			this.#revalidateTimer.unref?.();
+			this.#revalidateTimer.unref();
 		}
 	}
 	/**
@@ -557,7 +562,7 @@ var RealtimeHub = class RealtimeHub {
 	useAuthenticator(matcher, authenticator) {
 		const list = this.#authenticators ??= [];
 		const compiled = compileMatcher(matcher);
-		for (let i = 0; i < list.length; i++) if (list[i].authenticator === authenticator) return;
+		for (const entry of list) if (entry.authenticator === authenticator) return;
 		list.push({
 			matcher: compiled,
 			authenticator
@@ -571,10 +576,7 @@ var RealtimeHub = class RealtimeHub {
 	resolveAuthenticator(handshake) {
 		const list = this.#authenticators;
 		if (list === null) return null;
-		for (let i = 0; i < list.length; i++) {
-			const entry = list[i];
-			if (entry.matcher.match(handshake)) return entry.authenticator;
-		}
+		for (const entry of list) if (entry.matcher.match(handshake)) return entry.authenticator;
 		return null;
 	}
 	/**
@@ -781,7 +783,7 @@ var RealtimeHub = class RealtimeHub {
 		if (exact !== void 0) return exact;
 		const patterns = this.#channelPolicyPatterns;
 		if (patterns === null) return null;
-		for (let i = 0; i < patterns.length; i++) if (patterns[i].re.test(name)) return patterns[i].policy;
+		for (const pattern of patterns) if (pattern.re.test(name)) return pattern.policy;
 		return null;
 	}
 	/** Des politiques de canal sont-elles déclarées (au moins une) ? */

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

@@ -57,17 +57,19 @@ var ServerRealtimeSocket = class {
 	/** Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur. */
 	unsubscribe(channel) {
 		const c = channel;
-		const cur = this.#subs?.get(c);
-		if (!cur) return;
+		const subs = this.#subs;
+		const cur = subs?.get(c);
+		if (subs === null || cur === void 0 || cur === 0) return;
 		if (cur > 1) {
-			this.#subs.set(c, cur - 1);
+			subs.set(c, cur - 1);
 			return;
 		}
-		this.#subs.delete(c);
-		const sink = this.#sinks?.get(c);
-		if (sink) {
+		subs.delete(c);
+		const sinks = this.#sinks;
+		const sink = sinks?.get(c);
+		if (sinks && sink) {
 			this.hub.unsubscribe(c, sink);
-			this.#sinks.delete(c);
+			sinks.delete(c);
 		}
 	}
 	/** Branche un handler de réception sur un canal. Renvoie un `dispose`. */

package/dist/nodefony/src/service/RealtimeService.js

@@ -54,8 +54,9 @@ var RealtimeService = class extends Service {
 	* par la Module class). Aucun warn — c'est le cas commun.
 	*/
 	async init(_module) {
-		this.#config = this.module.config;
-		if (!this.#config) throw new Error(`${serviceName}: realtimeConfig absente (this.module.config vide) — la Module class doit la valider à onKernelRegister`);
+		const config = this.module.config;
+		if (!config) throw new Error(`${serviceName}: realtimeConfig absente (this.module.config vide) — la Module class doit la valider à onKernelRegister`);
+		this.#config = config;
 		if (!this.#config.enabled) {
 			this.log("realtime enabled:false → service inerte (hub non câblé)", "INFO");
 			return this;
@@ -227,10 +228,10 @@ var RealtimeService = class extends Service {
 *                                       `allowList` (pas de wildcard).
 */
 function buildOriginGuard(config) {
-	const c = config.csrf?.checkOrigin;
-	if (!c || c.enabled !== true) return null;
-	const allowSet = new Set(c.allowList ?? []);
-	const allowMissing = c.allowMissingOrigin === true;
+	const c = config.csrf.checkOrigin;
+	if (!c.enabled) return null;
+	const allowSet = new Set(c.allowList);
+	const allowMissing = c.allowMissingOrigin;
 	return (origin) => {
 		if (origin === void 0 || origin === "") return allowMissing;
 		return allowSet.has(origin);

package/dist/nodefony/testing/index.js

@@ -98,11 +98,13 @@ function createRealtimeHarness(create, options = {}) {
 			hub.onPlatformNotice((message) => {
 				notices.push(message);
 			});
-			if (!await waitFor(() => received.some((f) => f.method === "realtime:welcome"), 10)) {
+			await waitFor(() => received.some((f) => f.method === "realtime:welcome"), 10);
+			const welcome = received.find((f) => f.method === "realtime:welcome");
+			if (!welcome) {
 				const cause = closes.length > 0 ? `socket fermée (code ${String(closes[0]?.code)})` : "aucune frame émise";
 				throw new Error(`createRealtimeHarness: pas de realtime:welcome — ${cause}. Vérifier l'Origin (seam #4) et l'authenticator (seam #2).`);
 			}
-			return received.find((f) => f.method === "realtime:welcome");
+			return welcome;
 		},
 		async subscribe(channel) {
 			await feed(rpc({

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -44,6 +44,6 @@ export type IRealtimeConfigInput = z.input<typeof realtimeConfigSchema>;
 /** Config normalisée et gelée (sortie du builder, lue par `RealtimeService`). */
 export type IRealtimeConfig = IRealtimeSchemaConfig & {
     backplane: IRealtimeSchemaConfig["backplane"] & {
-        instance?: IBackplane;
+        instance?: IBackplane | undefined;
     };
 };

package/dist/types/nodefony/interfaces/IChannelPolicy.d.ts

@@ -19,10 +19,10 @@
  */
 export interface IChannelPolicy {
     /** Exige une connexion authentifiée (token non anonyme). */
-    readonly authenticated?: boolean;
+    readonly authenticated?: boolean | undefined;
     /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté security). */
-    readonly roles?: readonly string[];
+    readonly roles?: readonly string[] | undefined;
     /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
-    readonly scopes?: readonly string[];
+    readonly scopes?: readonly string[] | undefined;
 }
 export default IChannelPolicy;

package/dist/types/nodefony/interfaces/IRealtimeAuthenticatorMatcher.d.ts

@@ -40,7 +40,7 @@ export interface IRealtimeAuthenticatorMatcher {
  */
 export interface ICompiledRealtimeMatcher {
     readonly pattern: RegExp;
-    readonly host?: string;
+    readonly host?: string | undefined;
     /** Le matcher capture-t-il ce handshake ? */
     match(handshake: IRealtimeHandshake): boolean;
 }

package/dist/types/nodefony/interfaces/IRealtimeHandshake.d.ts

@@ -21,7 +21,7 @@ export interface IRealtimeHandshake {
     /** IP du client (déjà extraite — derrière proxy : voir `trust proxy`). */
     readonly remoteAddress: string;
     /** Origin RFC 6455 §10.2 — `undefined` si en-tête absent (clients non-browser). */
-    readonly origin?: string;
+    readonly origin?: string | undefined;
     /** Sous-protocoles annoncés (`Sec-WebSocket-Protocol`). `[]` si aucun. */
     readonly protocols: readonly string[];
 }

package/dist/types/nodefony/src/server/RealtimeController.d.ts

@@ -1,5 +1,7 @@
 import { type RpcActionHandler, type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
+import type { ContextType } from "@nodefony/http";
 import { Controller } from "@nodefony/framework";
+import type { ControllerScope } from "@nodefony/framework";
 import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } from "../../interfaces/IRealtimeController.js";
 /**
  * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
@@ -24,6 +26,31 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
  */
 export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController {
+    /**
+     * Une instance PAR CONNEXION, par construction — le défaut `singleton` des
+     * contrôleurs ne s'applique pas ici. Le pair JSON-RPC de la connexion capture
+     * l'instance du handshake, et {@link notifyClient} / {@link requestClient}
+     * désignent « CETTE connexion » par l'instance : partagée, ils liraient
+     * l'ALS de celui qui ÉMET (un écouteur du hub, un minuteur), donc une autre
+     * connexion, ou aucune. Cf {@link assertScope}.
+     */
+    static scope: ControllerScope;
+    /**
+     * Refuse qu'une sous-classe se déclare singleton — au démarrage
+     * (`Router.setController`), et au constructeur pour qui construit par `new`
+     * hors du routeur (harnais de test). Sans ce refus, la socket s'ouvrirait
+     * sans jamais émettre `realtime:welcome` : une panne indiscernable d'un
+     * incident réseau.
+     *
+     * @throws BootConfigurationError si la classe se déclare `@Scope("singleton")`.
+     */
+    static assertScope(): void;
+    /**
+     * @param name - nom du service (celui de la classe, par convention).
+     * @param context - le contexte de la connexion.
+     * @throws BootConfigurationError si la classe se déclare singleton.
+     */
+    constructor(name: string, context: ContextType);
     /**
      * Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
      * au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur

package/dist/types/nodefony/testing/index.d.ts

@@ -55,8 +55,8 @@ export interface IRealtimeFrame {
 }
 /** Fermeture demandée par le serveur (code RFC 6455 + raison). */
 export interface IHarnessClose {
-    readonly code?: number;
-    readonly reason?: string;
+    readonly code?: number | undefined;
+    readonly reason?: string | undefined;
 }
 /**
  * Refus d'abonnement notifié au client (`realtime:denied`) — le contrat de

package/docs/actions.md

@@ -136,8 +136,8 @@ l'instance du contrôleur au handshake, ce qui donne accès au noyau, aux servic
 connexion sans élargir le contrat.
 
 **L'endpoint s'annonce lui-même.** La liste des actions exposées voyage dans la frame d'accueil —
-`IRealtimeWelcome` (`RealtimeController.ts:8`) — et se lit côté client par
-`RealtimeClient.serverMethods` (`RealtimeClient.ts:591`). Une interface n'écrit donc jamais un nom d'action en dur : elle
+`IRealtimeWelcome` (`RealtimeController.ts:12`) — et se lit côté client par
+`RealtimeClient.serverMethods` (`RealtimeClient.ts:597`). Une interface n'écrit donc jamais un nom d'action en dur : elle
 n'active un bouton que si le serveur a déclaré savoir le servir.
 
 **Le compromis, dit franchement** : une action est **un aller-retour**, point. Elle ne diffuse pas,
@@ -277,7 +277,7 @@ Le trajet complet d'une requête, des étapes qu'elle traverse aux branches par
 | Voie                                                   | Quand la choisir                                            |
 | ------------------------------------------------------ | ----------------------------------------------------------- |
 | `@RealtimeAction("nom")` (`realtimeDecorators.ts:101`) | le cas courant — un nom fixe, une méthode, déclaratif       |
-| `realtimeActions()` (`RealtimeController.ts:179`)      | la table est **calculée** (noms dynamiques, boucle, config) |
+| `realtimeActions()` (`RealtimeController.ts:236`)      | la table est **calculée** (noms dynamiques, boucle, config) |
 
 Les deux sont fusionnées au handshake, et **l'override gagne** en cas de conflit de nom : une
 classe peut ainsi remplacer une action héritée sans toucher au parent
@@ -287,7 +287,7 @@ allouée au premier enregistrement seulement.
 ### Ce que ton `return` et ton `throw` deviennent sur le fil
 
 Le retour du handler est envoyé tel quel en `result`. Les erreurs, elles, suivent une règle Zero
-Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:506`) :
+Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:499`) :
 
 | Côté serveur                    | Ce que reçoit le client                  | Pourquoi                                        |
 | ------------------------------- | ---------------------------------------- | ----------------------------------------------- |
@@ -345,21 +345,22 @@ homonyme), elle est conservée : le défaut ne rétrograde jamais une règle plu
 ### Situation 2 — les namespaces réservés portent un plancher
 
 Un nom qui commence par `nodefony:` hérite d'un plancher non contournable : authentifié **et**
-`ROLE_ADMIN` (`SYSTEM_CHANNEL_POLICY`, `frameAuthorizer.ts:70`). Un seul préfixe couvre donc tout
-ce que la plateforme expose (`DEFAULT_SYSTEM_PREFIXES`, `frameAuthorizer.ts:86`). C'est ce qui
+`ROLE_NODEFONY_ADMIN` (`SYSTEM_CHANNEL_POLICY`, `frameAuthorizer.ts:89`) — un rôle de la plateforme,
+pas le `ROLE_ADMIN` d'une organisation. Un seul préfixe couvre donc tout
+ce que la plateforme expose (`DEFAULT_SYSTEM_PREFIXES`, `frameAuthorizer.ts:106`). C'est ce qui
 protège `nodefony:kernel:gc` : le nom **est** la garde, et la comparaison est insensible à la casse
 pour qu'un `NODEFONY:kernel:gc` ne passe pas à côté.
 
 Ce plancher **prime sur ta déclaration** — y compris sur `{ authenticated: false }`. Et il ne
 s'arrête pas aux préfixes : tout nom **contenant** `:health` ou `:stats` est traité comme un canal
-d'observabilité (`matchSystemPolicy`, `frameAuthorizer.ts:202`). Une action `public:health` reste
+d'observabilité (`matchSystemPolicy`, `frameAuthorizer.ts:243`). Une action `public:health` reste
 donc réservée, quoi qu'en dise son décorateur. À savoir avant de nommer une action « ouverte ».
 
 ### Situation 3 — couvrir SES actions par la configuration
 
 Pour exiger un rôle sur tes propres actions, on déclare une règle de préfixe dans la
 configuration de sécurité — la même liste que pour les canaux
-(`realtimeChannels`, `security/nodefony/config/config.ts:1124`) :
+(`realtimeChannels`, `security/nodefony/config/config.ts:1130`) :
 
 ```ts ignore
 use("@nodefony/security", {
@@ -402,7 +403,7 @@ await socket.request("orders:export", { scope }, 120_000); // action longue
 
 | Défaut    | Valeur    | Ancrage              |
 | --------- | --------- | -------------------- |
-| `request` | 30 000 ms | `JsonRpcPeer.ts:310` |
+| `request` | 30 000 ms | `JsonRpcPeer.ts:319` |
 
 À l'expiration, l'entrée en attente est **retirée** et la `Promise` rejetée avec
 `RPC timeout: <méthode>` (`JsonRpcPeer.ts:455`). Conséquence à connaître : une réponse qui
@@ -444,7 +445,7 @@ fois ? »**.
 
 Pour les mutations passant par le pont API, la clé n'est pas une convention : elle est **exigée
 par la signature** de `mutate()` (`RealtimeClient.ts:797`), et c'est la garde `@Idempotent`
-(`routerDecorators.ts:1103`) qui, côté serveur, reconnaît le rejeu et rend la réponse déjà calculée
+(`routerDecorators.ts:1171`) qui, côté serveur, reconnaît le rejeu et rend la réponse déjà calculée
 au lieu de refaire l'effet.
 
 ```ts ignore
@@ -509,8 +510,8 @@ il sera conçu avec son premier consommateur réel.
 Un cas particulier mérite d'être connu avant d'écrire une action : **elle existe peut-être déjà en
 HTTP**. Le pont API expose la méthode `api.request`, qui rejoue une route de contrôleur sur la
 socket, avec la même garde et le même résultat qu'en REST — `invokeApiRequest()`
-(`RealtimeController.ts:878`). Il est **désactivé par défaut** et s'active en surchargeant
-`realtimeApiRequest()` (`RealtimeController.ts:219`).
+(`RealtimeController.ts:949`). Il est **désactivé par défaut** et s'active en surchargeant
+`realtimeApiRequest()` (`RealtimeController.ts:276`).
 
 ```ts ignore
 const modules = await socket.request("/nodefony/kernel/api/modules");
@@ -529,7 +530,7 @@ passe par le pont pour tout ce qui est déjà une route. Le détail du pont vit
 | Le client attend indéfiniment, aucune erreur                 | le handler ne rend jamais (il publie au lieu de retourner) — pas de frame `result` | toujours `return` une valeur ; publier **en plus**, jamais **à la place**          |
 | `-32601 method not found`                                    | nom mal orthographié, ou action déclarée sur un **autre** endpoint                 | vérifier `socket.serverMethods` — c'est la liste réelle de CETTE connexion         |
 | `-32603 internal error` sans détail                          | un `throw` ordinaire est rendu opaque au client (Zero Trust)                       | lever une `RpcError` avec un code et un message publiables                         |
-| `-32001 unauthorized` sur une action légitime                | le nom commence par `nodefony:`, le namespace réservé à la plateforme              | renommer hors de `nodefony:`, ou obtenir `ROLE_ADMIN`                              |
+| `-32001 unauthorized` sur une action légitime                | le nom commence par `nodefony:`, le namespace réservé à la plateforme              | renommer hors de `nodefony:`, ou obtenir `ROLE_NODEFONY_ADMIN`                     |
 | Une action sensible est appelable par un anonyme             | une action applicative est **libre** tant qu'aucune politique ne la couvre         | ajouter une règle de préfixe (`security/nodefony/config/config.ts:906`)            |
 | Un travail relancé crée deux jobs                            | action non idempotente rejouée après une reconnexion                               | action compagnon d'annulation, ou identifiant fourni par l'appelant + mémorisation |
 | `abort()` introuvable sur la socket                          | il n'existe pas — et n'arrêterait pas le serveur de toute façon                    | exposer une action d'annulation qui prend l'identifiant du travail                 |