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

package/README.md

@@ -31,9 +31,9 @@ Le client navigateur **n'est pas dans ce module** : il vit dans le cœur, import
 du serveur (isomorphisme). Le subpath est **`nodefony/client`**.
 
 ```typescript
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
-const socket = RealtimeClient.shared({ url: "wss://app.com/realtime" });
+const socket = NodefonySocket.shared({ url: "wss://app.com/realtime" });
 
 await socket.subscribe("chat:room");
 socket.on("chat:room", (msg) => console.log(msg));

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

@@ -1,9 +1,8 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.155.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);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-//#endregion
 export { __decorate as default };

package/dist/index.js

@@ -1,5 +1,7 @@
 import config from "./nodefony/config/config.js";
-import { defineRealtimeConfig, realtimeConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
+import { buildRealtimeConfig, defineRealtimeConfig, realtimeConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
+import { isCallable, isRecord } from "./nodefony/src/guards.js";
+import { realtimeBackplaneDownNotice, realtimeLocalOnlyNotice } from "./nodefony/src/backplane/bootNotices.js";
 import resolveBackplaneOriginId from "./nodefony/src/backplane/originId.js";
 import { LoopbackBackplane } from "./nodefony/src/backplane/LoopbackBackplane.js";
 import { ANONYMOUS_REALTIME_TOKEN } from "./nodefony/src/server/AnonymousRealtimeToken.js";
@@ -10,15 +12,14 @@ import { BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, createSyslogUplinkHandler } from "
 import { WsConnectionTransport } from "./nodefony/src/transport/WsConnectionTransport.js";
 import { RealtimeController } from "./nodefony/src/server/RealtimeController.js";
 import { ServerRealtimeSocket, serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
-import { REDIS_RT_CHANNEL, RedisBackplane, createRedisServiceTransport, resolveRedisChannel } from "./nodefony/src/backplane/RedisBackplane.js";
+import { REDIS_RT_CHANNEL, RedisBackplane, createRedisServiceTransport, isRedisPublisher, isRedisSubscriber, resolveRedisChannel } from "./nodefony/src/backplane/RedisBackplane.js";
 import { ClusterBackplane, processIpcTransport } from "./nodefony/src/backplane/ClusterBackplane.js";
 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.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
-import { Kernel, Module, services, withTimeout } from "nodefony";
-//#region index.ts
+import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import { IDENTITY_CHANGED_EVENT, Module, services, withTimeout } from "nodefony";
+// index.ts
 /**
 * @nodefony/realtime — Couche realtime serveur Nodefony.
 *
@@ -51,13 +52,13 @@ registerBackplaneDriver(LoopbackBackplane.driver, () => null);
 registerBackplaneDriver(ClusterBackplane.driver, (ctx) => ctx.role === "WORKER" && process.env.NF_CLUSTER === "1" ? new ClusterBackplane(processIpcTransport, ctx.originId) : null);
 registerBackplaneDriver(RedisBackplane.driver, (ctx) => {
 	const redisService = ctx.module.kernel?.container?.get("redis");
-	if (!redisService) {
+	if (!isRecord(redisService) || !isCallable(redisService.getClient)) {
 		ctx.module.log(`driver "${RedisBackplane.driver}" : module @nodefony/redis absent (non listé dans @modules) — RealtimeHub reste local`, "WARNING");
 		return null;
 	}
 	const publisher = redisService.getClient("publish");
 	const subscriber = redisService.getClient("subscribe");
-	if (!publisher || !subscriber) {
+	if (!isRedisPublisher(publisher) || !isRedisSubscriber(subscriber)) {
 		ctx.module.log(`driver "${RedisBackplane.driver}" : connexions Redis publish/subscribe indisponibles — RealtimeHub reste local`, "WARNING");
 		return null;
 	}
@@ -96,7 +97,7 @@ let Realtime = class Realtime extends Module {
 	* sans dupliquer la validation.
 	*/
 	async onKernelRegister() {
-		const validated = defineRealtimeConfig(this.options ?? {});
+		const validated = buildRealtimeConfig(this.options);
 		this.options = validated;
 		return this;
 	}
@@ -117,7 +118,10 @@ let Realtime = class Realtime extends Module {
 			return this;
 		}
 		const broker = this.kernel?.container?.get("adminBroker");
-		if (broker && !broker.has("realtime")) broker.register(createRealtimeAdminApi());
+		if (isRecord(broker) && isCallable(broker.has) && isCallable(broker.register) && broker.has("realtime") !== true) broker.register(createRealtimeAdminApi());
+		this.kernel?.on(IDENTITY_CHANGED_EVENT, (event) => {
+			getRealtimeHub().refreshIdentity(event.identifier);
+		});
 		await this.#wireBackplane();
 		this.#wireClusterProbe(this.#clusterRole);
 		return this;
@@ -157,12 +161,14 @@ let Realtime = class Realtime extends Module {
 		});
 		if (!backplane) {
 			this.log(`realtime backplane  driver=${driverName} kind=local cross-pod=no (hub local)`, "INFO");
+			this.kernel?.reportBootNotice(realtimeLocalOnlyNotice(driverName));
 			return;
 		}
 		try {
 			await this.#startWithTimeout(backplane, BACKPLANE_START_TIMEOUT_MS);
 		} catch (e) {
-			this.log(`realtime backplane driver=${driverName} indisponible (${e.message}) — fallback hub LOCAL, boot poursuivi (pas de fan-out cross-pod)`, "WARNING");
+			this.log(`realtime backplane driver=${driverName} indisponible (${e instanceof Error ? e.message : String(e)}) — fallback hub LOCAL, boot poursuivi (pas de fan-out cross-pod)`, "WARNING");
+			this.kernel?.reportBootNotice(realtimeBackplaneDownNotice(driverName, e instanceof Error ? e.message : String(e)));
 			return;
 		}
 		hub.setBackplane(backplane);
@@ -212,7 +218,6 @@ let Realtime = class Realtime extends Module {
 		}
 	}
 };
-Realtime = __decorate([services([RealtimeService]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Realtime);
+Realtime = __decorate([services([RealtimeService])], Realtime);
 var realtime_default = Realtime;
-//#endregion
 export { ANONYMOUS_REALTIME_TOKEN, BROWSER_ORIGIN, ClusterBackplane, ClusterProbeClient, LoopbackBackplane, MAX_CLIENT_SEVERITY, REDIS_RT_CHANNEL, RESERVED_SYSTEM_PREFIXES, Realtime, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeController, RealtimeHub, RealtimeInbound, RealtimeService, RedisBackplane, SLOW_CONSUMER_BYTES, ServerRealtimeSocket, WsConnectionTransport, buildOwnHealth, buildRealtimeHealth, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, createRealtimeAdminApi, createRedisServiceTransport, createSyslogUplinkHandler, realtime_default as default, defineRealtimeConfig, getBackplaneDriver, getDeclaredBroadcastPrefixes, getRealtimeHub, isReservedSystemChannel, listBackplaneDrivers, mergeClusterHealth, processIpcTransport, processProbeTransport, realtimeConfigJsonSchema, registerBackplaneDriver, resolveBackplaneOriginId, resolveRedisChannel, serverSocket, setClusterProbeClient };

package/dist/nodefony/config/config.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-//#region nodefony/config/config.ts
+// nodefony/config/config.ts
 /**
 * @nodefony/realtime — CONFIGURATION DU MODULE (schéma Zod = source unique).
 *
@@ -24,9 +24,12 @@ import { z } from "zod";
 */
 const probeSchema = z.strictObject({ enabled: z.boolean().default(true).describe("Branche le ClusterProbeClient (sonde agrégée pod, Phase 4c) en worker `nodefony cluster`. true = sonde active (timer + IPC). false = bypass total (0 timer / 0 listener / 0 IPC, l'endpoint santé sert la vue per-instance). Override env : NF_CLUSTER_PROBE=0 force la désactivation.") }).describe("Sonde agrégée pod (Phase 4c).");
 const backplaneSchema = z.strictObject({
-	driver: z.string().default("loopback").describe("Nom du driver IBackplane, résolu dans le registre de drivers (`listBackplaneDrivers()`) — PAS d'enum en dur ici : la liste réelle est la source de vérité du registre, ouverte aux drivers custom utilisateur (`registerBackplaneDriver(name, factory)`). Natifs : `loopback` (mono, hub local sans IPC), `cluster` (IPC workers `nodefony cluster`, actif si NF_CLUSTER=1), `redis` (multi-host pub/sub). Driver inconnu au boot → warn fail-soft, le hub reste local."),
-	namespace: z.string().min(1).regex(/^[\w.-]+$/).optional().describe("Cloison logique du transport partagé (drivers cross-pod : redis, futur kafka) — suffixe le canal pub/sub (`nodefony:realtime:<ns>`). Le `database` Redis ne cloisonnant PAS le pub/sub, deux apps sur un Redis mutualisé SANS namespace se parleraient (cross-talk). Défaut : dérivé du nom d'app (`kernel.projectName`). À poser EXPLICITEMENT quand deux déploiements de la même app (staging/prod) partagent un Redis. Caractères : alphanumériques, `_`, `.`, `-`. Env : `NF_REALTIME_BACKPLANE_NAMESPACE` (prioritaire — le namespace distingue des DÉPLOIEMENTS, il n'a pas à être figé dans le code)."),
-	secret: z.string().min(32).optional().describe("Secret de SCELLEMENT des messages du backplane, partagé par tous les pods de l'app (drivers à transport PARTAGÉ : redis, futurs drivers cross-host). Un bus pub/sub n'authentifie PAS l'émetteur : sans ce secret, quiconque écrit dans le Redis (autre app d'un Redis mutualisé, credential fuité, SSRF) publie sur les canaux de TOUS les pods. Posé, chaque message porte un HMAC-SHA256 et l'ingress devient fail-closed strict (non scellé ou mal scellé = ignoré, aucun downgrade). Sans lui, le boot ALERTE et le bus reste ouvert. Inutile pour `cluster` (IPC master↔workers : aucun tiers ne peut y écrire). Env : `NF_REALTIME_BACKPLANE_SECRET`. Minimum 32 caractères.").meta({ secret: true }),
+	driver: z.string().default("loopback").describe("Nom du driver IBackplane, résolu dans le registre de drivers (`listBackplaneDrivers()`) — PAS d'enum en dur ici : la liste réelle est la source de vérité du registre, ouverte aux drivers custom utilisateur (`registerBackplaneDriver(name, factory)`). Natifs : `loopback` (mono, hub local sans IPC), `cluster` (IPC workers `nodefony cluster`, actif si NF_CLUSTER=1), `redis` (multi-host pub/sub). Driver inconnu au boot → warn fail-soft, le hub reste local.").meta({ env: "NF_REALTIME_DRIVER" }),
+	namespace: z.string().min(1).regex(/^[\w.-]+$/).optional().describe("Cloison logique du transport partagé (drivers cross-pod : redis, futur kafka) — suffixe le canal pub/sub (`nodefony:realtime:<ns>`). Le `database` Redis ne cloisonnant PAS le pub/sub, deux apps sur un Redis mutualisé SANS namespace se parleraient (cross-talk). Défaut : dérivé du nom d'app (`kernel.projectName`). À poser EXPLICITEMENT quand deux déploiements de la même app (staging/prod) partagent un Redis. Caractères : alphanumériques, `_`, `.`, `-`. Env : `NF_REALTIME_BACKPLANE_NAMESPACE` (prioritaire — le namespace distingue des DÉPLOIEMENTS, il n'a pas à être figé dans le code).").meta({ env: "NF_REALTIME_BACKPLANE_NAMESPACE" }),
+	secret: z.string().min(32).optional().describe("Secret de SCELLEMENT des messages du backplane, partagé par tous les pods de l'app (drivers à transport PARTAGÉ : redis, futurs drivers cross-host). Un bus pub/sub n'authentifie PAS l'émetteur : sans ce secret, quiconque écrit dans le Redis (autre app d'un Redis mutualisé, credential fuité, SSRF) publie sur les canaux de TOUS les pods. Posé, chaque message porte un HMAC-SHA256 et l'ingress devient fail-closed strict (non scellé ou mal scellé = ignoré, aucun downgrade). Sans lui, le boot ALERTE et le bus reste ouvert. Inutile pour `cluster` (IPC master↔workers : aucun tiers ne peut y écrire). Env : `NF_REALTIME_BACKPLANE_SECRET`. Minimum 32 caractères.").meta({
+		env: "NF_REALTIME_BACKPLANE_SECRET",
+		secret: true
+	}),
 	maxQueueBytes: z.number().int().nonnegative().default(1 << 23).describe("Seuil d'octets PUBLIÉS mais pas encore acquittés par le bus, au-delà duquel les publications suivantes sont JETÉES (drivers à transport réseau : redis, drivers cross-host userland). Un `publish` de backplane est fire-and-forget : quand le bus ne draine plus, la file interne du client réseau grossit sans limite (583 MB observés sous rafale sur le banc multi-pods). Même doctrine que le back-pressure WS : on sacrifie du fan-out cross-pod pour tenir la mémoire du pod, jamais en silence (compteurs `backplane.queue` dans la sonde + Studio, alerte au franchissement). Défaut 8 MiB, soit trois ordres de grandeur au-dessus d'un régime sain (bus acquitté en quelques ms). `0` = illimité (opt-out explicite : la mémoire n'est alors bornée par rien).")
 }).describe("Driver IBackplane (fan-out cluster realtime cross-process).");
 const clusterSchema = z.strictObject({ probe: probeSchema.default(() => probeSchema.parse({})) }).describe("Comportement spécifique au mode cluster (worker IPC).");
@@ -59,5 +62,4 @@ const realtimeConfigSchema = z.strictObject({
 * valides par construction ; passés au `super(..., config)` du Module class.
 */
 const config = realtimeConfigSchema.parse({});
-//#endregion
 export { config as default, realtimeConfigSchema };

package/dist/nodefony/config/configSchema.js

@@ -0,0 +1,18 @@
+import { realtimeConfigSchema } from "./config.js";
+import { z } from "zod";
+// nodefony/config/configSchema.ts
+/**
+* JSON Schema de la configuration de `@nodefony/realtime` — lu SANS démarrer
+* l'application, par `nodefony env` et la notice `.env.example`, qui y
+* trouvent les noms courts (`.meta({ env })`).
+*
+* Déclaré dans `package.json` → `nodefony.configSchema` ; le nom de l'export
+* est FIXE. Fichier FEUILLE : il n'importe que zod et le schéma, et n'ouvre
+* rien à l'import — une commande qui ne démarre pas l'application l'exécute.
+*
+* @returns le JSON Schema, métadonnées Nodefony comprises.
+*/
+function configJsonSchema() {
+	return z.toJSONSchema(realtimeConfigSchema);
+}
+export { configJsonSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -1,7 +1,7 @@
 import { realtimeConfigSchema } from "./config.js";
+import { configJsonSchema } from "./configSchema.js";
 import { parseModuleConfig } from "nodefony";
-import { z } from "zod";
-//#region nodefony/config/defineModuleConfig.ts
+// nodefony/config/defineModuleConfig.ts
 /**
 * Builder type-safe de la configuration de `@nodefony/realtime`.
 *
@@ -20,11 +20,13 @@ import { z } from "zod";
 *   faire dans un JSON Schema Studio). L'instance, si fournie, prend précédence
 *   sur `driver` côté service ; ce dernier reste source d'introspection/UI.
 *
-* **Layering d'environnement** (convention-frère avec `REDIS_*` de
-* `@nodefony/redis`) : `NF_REALTIME_DRIVER` surcharge le driver backplane
-* APRÈS le parse (schéma pur, déterministe). Indispensable en déploiement
-* (k8s/Docker : `NF_REALTIME_DRIVER=redis`) et fiable quel que soit le
-* timing du merge `module-realtime` côté app (cf chantier ordering config).
+* **Variables d'environnement** : `NF_REALTIME_DRIVER`,
+* `NF_REALTIME_BACKPLANE_SECRET` et `NF_REALTIME_BACKPLANE_NAMESPACE` ne se
+* lisent PAS ici. Chacune est déclarée sur son champ dans `config.ts`
+* (`.meta({ env })`) et posée par le Kernel AVANT la validation : le schéma
+* les valide comme une valeur de l'application (un secret de moins de 32
+* caractères arrête le démarrage). Un appel direct de ce builder, hors Kernel,
+* ne les voit donc pas.
 *
 * @param config - configuration brute (sections omises = défauts sûrs).
 * @param options.backplane - instance `IBackplane` custom (override le driver à
@@ -33,28 +35,52 @@ import { z } from "zod";
 * @throws ZodError si invalide.
 */
 function defineRealtimeConfig(config = {}, options = {}) {
+	return buildRealtimeConfig(config, options);
+}
+/**
+* Le builder pour une entrée NON typée — la config reçue par le module au
+* démarrage, dont le schéma décide seul de la forme. Interne au paquet : une
+* application passe par {@link defineRealtimeConfig}, qui type ce qu'elle écrit.
+*
+* @param config - configuration brute, validée par le schéma
+* @param options.backplane - instance `IBackplane` custom
+* @returns config gelée prête pour `RealtimeService`.
+* @throws BootConfigurationError si invalide.
+*/
+function buildRealtimeConfig(config = {}, options = {}) {
 	const parsed = parseModuleConfig(realtimeConfigSchema, config, "@nodefony/realtime");
-	const driver = process.env.NF_REALTIME_DRIVER || parsed.backplane.driver;
-	const secret = process.env.NF_REALTIME_BACKPLANE_SECRET || parsed.backplane.secret;
-	const namespace = process.env.NF_REALTIME_BACKPLANE_NAMESPACE || parsed.backplane.namespace;
 	const out = {
 		...parsed,
 		backplane: {
 			...parsed.backplane,
-			driver,
-			secret,
-			namespace,
 			instance: options.backplane
 		}
 	};
-	return Object.freeze(out);
+	const frozen = Object.freeze(out);
+	built.add(frozen);
+	return frozen;
+}
+/**
+* Configs produites par ce builder. Marquer la sortie plutôt que d'en vérifier
+* la forme : une seule appartenance (`has`) prouve que l'objet a traversé le
+* schéma, ce qu'aucune inspection de champs ne dit.
+*/
+const built = /* @__PURE__ */ new WeakSet();
+/**
+* Vrai si la valeur est une config produite par {@link buildRealtimeConfig}
+* (donc validée par le schéma). Lu une fois, à l'init du service.
+*
+* @param value - la config lue sur le module
+* @returns `true` si elle sort du builder
+*/
+function isRealtimeConfig(value) {
+	return typeof value === "object" && value !== null && built.has(value);
 }
 /**
 * JSON Schema introspectable de la config realtime — destiné au formulaire
 * d'édition Studio (futur). N'inclut PAS `backplane.instance` (non sérialisable).
 */
 function realtimeConfigJsonSchema() {
-	return z.toJSONSchema(realtimeConfigSchema);
+	return configJsonSchema();
 }
-//#endregion
-export { defineRealtimeConfig, realtimeConfigJsonSchema };
+export { buildRealtimeConfig, defineRealtimeConfig, isRealtimeConfig, realtimeConfigJsonSchema };

package/dist/nodefony/decorators/realtimeDecorators.js

@@ -1,14 +1,46 @@
+import { isCallable, isRecord } from "../src/guards.js";
 import "reflect-metadata";
-//#region nodefony/decorators/realtimeDecorators.ts
+// nodefony/decorators/realtimeDecorators.ts
 /** Clés de métadonnées posées sur le constructor de la classe controller. */
 const ACTIONS_KEY = "realtime:actions";
 const CHANNELS_KEY = "realtime:channels";
 const INBOUND_KEY = "realtime:inbound";
 const POLICIES_KEY = "realtime:policies";
+/**
+* Lit une métadonnée de classe posée par ces décorateurs : un objet nom → valeur,
+* ou `undefined` quand la classe n'en porte pas. Les valeurs restent `unknown` :
+* `Reflect.defineMetadata` est public, n'importe qui peut écrire sous ces clés.
+* Lu au démarrage et à la poignée de main, jamais par frame.
+*/
+function readMetadataMap(key, ctor) {
+	const raw = Reflect.getMetadata(key, ctor);
+	return isRecord(raw) ? raw : void 0;
+}
+/** Vrai si la valeur est un tableau de chaînes. */
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/** Vrai si la valeur a la forme d'une {@link IChannelPolicy}. */
+function isChannelPolicy(value) {
+	if (!isRecord(value)) return false;
+	const { authenticated, roles, scopes } = value;
+	return (authenticated === void 0 || typeof authenticated === "boolean") && (roles === void 0 || isStringArray(roles)) && (scopes === void 0 || isStringArray(scopes));
+}
+/** Vrai si chaque entrée du registre est une {@link IChannelPolicy}. */
+function isPolicyMap(map) {
+	for (const name in map) if (!isChannelPolicy(map[name])) return false;
+	return true;
+}
+/** Méthode de l'instance que désigne une entrée de registre, ou `undefined`. */
+function methodOf(instance, prop) {
+	return typeof prop === "string" || typeof prop === "symbol" ? Reflect.get(instance, prop) : void 0;
+}
+/** Libération d'un canal dont la fabrique décorée n'en a rendu aucune. */
+const NO_DISPOSE = () => {};
 /** Enregistre (idempotent) une politique non vide sous son nom de canal/méthode. */
 function definePolicy(ctor, name, policy) {
 	if (!policy || policy.authenticated === void 0 && policy.roles === void 0 && policy.scopes === void 0) return;
-	const map = Reflect.getMetadata(POLICIES_KEY, ctor) ?? {};
+	const map = { ...readMetadataMap(POLICIES_KEY, ctor) };
 	map[name] = policy;
 	Reflect.defineMetadata(POLICIES_KEY, map, ctor);
 }
@@ -21,7 +53,7 @@ function definePolicy(ctor, name, policy) {
 const DEFAULT_ACTION_POLICY = Object.freeze({ authenticated: true });
 /** Une politique est-elle DÉJÀ déclarée sous ce nom ? */
 function hasPolicy(ctor, name) {
-	const map = Reflect.getMetadata(POLICIES_KEY, ctor);
+	const map = readMetadataMap(POLICIES_KEY, ctor);
 	return map ? Object.prototype.hasOwnProperty.call(map, name) : false;
 }
 /**
@@ -72,7 +104,7 @@ function hasPolicy(ctor, name) {
 function RealtimeAction(method, policy) {
 	return function(target, propertyKey) {
 		const ctor = target.constructor;
-		const map = Reflect.getMetadata(ACTIONS_KEY, ctor) ?? {};
+		const map = { ...readMetadataMap(ACTIONS_KEY, ctor) };
 		map[method] = propertyKey;
 		Reflect.defineMetadata(ACTIONS_KEY, map, ctor);
 		if (policy) definePolicy(ctor, method, policy);
@@ -109,7 +141,7 @@ function RealtimeAction(method, policy) {
 function RealtimeChannel(channel, policy) {
 	return function(target, propertyKey) {
 		const ctor = target.constructor;
-		const map = Reflect.getMetadata(CHANNELS_KEY, ctor) ?? {};
+		const map = { ...readMetadataMap(CHANNELS_KEY, ctor) };
 		map[channel] = propertyKey;
 		Reflect.defineMetadata(CHANNELS_KEY, map, ctor);
 		definePolicy(ctor, channel, policy);
@@ -140,42 +172,58 @@ function RealtimeChannel(channel, policy) {
 function RealtimeInbound(method, policy) {
 	return function(target, propertyKey) {
 		const ctor = target.constructor;
-		const map = Reflect.getMetadata(INBOUND_KEY, ctor) ?? {};
+		const map = { ...readMetadataMap(INBOUND_KEY, ctor) };
 		map[method] = propertyKey;
 		Reflect.defineMetadata(INBOUND_KEY, map, ctor);
 		definePolicy(ctor, method, policy);
 	};
 }
-/** Lecture (lazy, au handshake) du registre des actions décorées. */
-function getRealtimeActions(instance) {
-	const map = Reflect.getMetadata(ACTIONS_KEY, instance.constructor);
+/**
+* Lecture (lazy, au handshake) du registre des actions décorées.
+*
+* @param instance - le contrôleur de la connexion
+* @param wrap - enveloppe optionnelle de chaque action (résolution des
+*   paramètres décorés) ; sans elle, l'action reçoit la charge JSON-RPC brute
+* @returns les handlers par nom d'action, ou `null` si aucune n'est décorée
+*/
+function getRealtimeActions(instance, wrap) {
+	const map = readMetadataMap(ACTIONS_KEY, instance.constructor);
 	if (!map) return null;
 	const out = {};
 	for (const [name, prop] of Object.entries(map)) {
-		const fn = instance[prop];
-		if (typeof fn === "function") out[name] = fn.bind(instance);
+		if (typeof prop !== "string" && typeof prop !== "symbol") continue;
+		const fn = methodOf(instance, prop);
+		if (isCallable(fn)) {
+			const bound = fn.bind(instance);
+			out[name] = wrap !== void 0 ? wrap(bound, prop) : bound;
+		}
 	}
 	return out;
 }
 /** Lecture (lazy, au handshake) du registre des canaux décorés. */
 function getRealtimeChannels(instance) {
-	const map = Reflect.getMetadata(CHANNELS_KEY, instance.constructor);
+	const map = readMetadataMap(CHANNELS_KEY, instance.constructor);
 	if (!map) return null;
 	const out = {};
 	for (const [name, prop] of Object.entries(map)) {
-		const fn = instance[prop];
-		if (typeof fn === "function") out[name] = fn.bind(instance);
+		const fn = methodOf(instance, prop);
+		if (!isCallable(fn)) continue;
+		const factory = fn.bind(instance);
+		out[name] = (channel, publish) => {
+			const dispose = factory(channel, publish);
+			return isCallable(dispose) ? () => void dispose() : NO_DISPOSE;
+		};
 	}
 	return out;
 }
 /** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */
 function getRealtimeInbound(instance) {
-	const map = Reflect.getMetadata(INBOUND_KEY, instance.constructor);
+	const map = readMetadataMap(INBOUND_KEY, instance.constructor);
 	if (!map) return null;
 	const out = {};
 	for (const [name, prop] of Object.entries(map)) {
-		const fn = instance[prop];
-		if (typeof fn === "function") out[name] = fn.bind(instance);
+		const fn = methodOf(instance, prop);
+		if (isCallable(fn)) out[name] = fn.bind(instance);
 	}
 	return out;
 }
@@ -187,7 +235,10 @@ function getRealtimeInbound(instance) {
 * hub realtime, qui l'expose à `@nodefony/security`.
 */
 function getRealtimeChannelPolicies(instance) {
-	return Reflect.getMetadata(POLICIES_KEY, instance.constructor) ?? null;
+	const map = readMetadataMap(POLICIES_KEY, instance.constructor);
+	if (map === void 0) return null;
+	if (!isPolicyMap(map)) throw new TypeError(`${instance.constructor.name} : politique de canal temps réel illisible`);
+	return map;
 }
 /**
 * Préfixes de canaux **broadcast** déclarés statiquement, tous controllers
@@ -236,5 +287,4 @@ function getDeclaredBroadcastPrefixes() {
 function applyDeclaredBroadcastPrefixes(hub) {
 	for (const prefix of declaredBroadcastPrefixes) hub.markBroadcastChannel(prefix);
 }
-//#endregion
 export { DEFAULT_ACTION_POLICY, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, applyDeclaredBroadcastPrefixes, getDeclaredBroadcastPrefixes, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound };

package/dist/nodefony/interfaces/IRealtimeConnectionState.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,6 +1,6 @@
 import resolveBackplaneOriginId from "./originId.js";
 import { CLUSTER_RT_KIND } from "nodefony";
-//#region nodefony/src/backplane/ClusterBackplane.ts
+// nodefony/src/backplane/ClusterBackplane.ts
 /**
 * Transport de production : `process.send` (émission) + `process.on("message")`
 * (réception). Standalone — utilisable tel quel. En vrai câblage cluster (Phase 3c),
@@ -101,5 +101,4 @@ var ClusterBackplane = class ClusterBackplane {
 		};
 	}
 };
-//#endregion
 export { ClusterBackplane, ClusterBackplane as default, processIpcTransport };

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

@@ -1,5 +1,5 @@
 import resolveBackplaneOriginId from "./originId.js";
-//#region nodefony/src/backplane/LoopbackBackplane.ts
+// nodefony/src/backplane/LoopbackBackplane.ts
 /**
 * Backplane **mono-process no-op** — implémentation de RÉFÉRENCE du port
 * {@link IBackplane} quand il n'existe **aucun pair** (1 process = 1 pod).
@@ -36,5 +36,4 @@ var LoopbackBackplane = class LoopbackBackplane {
 		};
 	}
 };
-//#endregion
 export { LoopbackBackplane, LoopbackBackplane as default };

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

@@ -1,7 +1,8 @@
+import { isCallable, isRecord, isThenable } from "../guards.js";
 import resolveBackplaneOriginId from "./originId.js";
 import { openBackplaneEnvelope, sealBackplaneEnvelope } from "./envelope.js";
 import { BackplanePublishQueue } from "./publishQueue.js";
-//#region nodefony/src/backplane/RedisBackplane.ts
+// nodefony/src/backplane/RedisBackplane.ts
 /**
 * BASE du canal Redis **dédié** transportant les enveloppes realtime entre pods.
 * Un seul canal pub/sub par app (les canaux logiques voyagent DANS l'enveloppe,
@@ -43,20 +44,36 @@ function resolveRedisChannel(namespace) {
 * Le listener Redis est conservé pour un `unsubscribe(channel, listener)` ciblé
 * (n'arrache pas d'éventuels autres abonnés du même client).
 */
+/**
+* Vrai si la valeur expose la surface d'un client Redis publisher — vérifié au
+* démarrage, sur le client que rend le service `redis`.
+*/
+function isRedisPublisher(value) {
+	return isRecord(value) && isCallable(value.publish);
+}
+/** Vrai si la valeur expose la surface d'un client Redis subscriber dédié. */
+function isRedisSubscriber(value) {
+	return isRecord(value) && isCallable(value.subscribe) && isCallable(value.unsubscribe);
+}
+/** Ramène l'acquittement d'une commande Redis au contrat du transport. */
+function settled(ack) {
+	return isThenable(ack) ? ack.then(() => void 0) : void 0;
+}
 function createRedisServiceTransport(publisher, subscriber) {
 	let listener = null;
 	return {
 		publish(channel, message) {
-			return publisher.publish(channel, message);
+			const ack = publisher.publish(channel, message);
+			return isThenable(ack) ? ack : void 0;
 		},
 		subscribe(channel, onMessage) {
 			listener = (message) => onMessage(message);
-			return subscriber.subscribe(channel, listener);
+			return settled(subscriber.subscribe(channel, listener));
 		},
 		unsubscribe(channel) {
 			const current = listener;
 			listener = null;
-			return current ? subscriber.unsubscribe(channel, current) : subscriber.unsubscribe(channel);
+			return settled(current ? subscriber.unsubscribe(channel, current) : subscriber.unsubscribe(channel));
 		}
 	};
 }
@@ -172,5 +189,4 @@ var RedisBackplane = class RedisBackplane {
 		};
 	}
 };
-//#endregion
-export { REDIS_RT_CHANNEL, RedisBackplane, RedisBackplane as default, createRedisServiceTransport, resolveRedisChannel };
+export { REDIS_RT_CHANNEL, RedisBackplane, RedisBackplane as default, createRedisServiceTransport, isRedisPublisher, isRedisSubscriber, resolveRedisChannel };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/backplane/backplaneRegistry.ts
+// nodefony/src/backplane/backplaneRegistry.ts
 const drivers = /* @__PURE__ */ new Map();
 /**
 * Enregistre (ou remplace) la fabrique d'un driver backplane. Appelé par les
@@ -16,5 +16,4 @@ function getBackplaneDriver(name) {
 function listBackplaneDrivers() {
 	return [...drivers.keys()];
 }
-//#endregion
 export { getBackplaneDriver, listBackplaneDrivers, registerBackplaneDriver };

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

@@ -0,0 +1,42 @@
+// nodefony/src/backplane/bootNotices.ts
+/** Le geste qui rend le temps réel partagé entre processus et pods. */
+const REDIS_BACKPLANE_FIX = "use(\"@nodefony/realtime\", { backplane: { driver: \"redis\" } }) + NF_REDIS_URL=redis://…";
+/**
+* Le temps réel ne dépasse pas ce processus : aucun backplane actif (driver
+* `loopback`, `cluster` hors d'un worker, ou fabrique inactive ici).
+*
+* Simple information en développement mono-processus — c'est le cas normal —
+* mais à savoir avant de déployer plusieurs exemplaires : un message publié
+* sur l'un n'atteindrait pas les clients connectés aux autres.
+*
+* @param driver - le driver déclaré.
+* @returns le point à déclarer.
+*/
+function realtimeLocalOnlyNotice(driver) {
+	return {
+		code: "REALTIME_LOCAL_ONLY",
+		level: "info",
+		message: `Temps réel limité à ce processus (backplane « ${driver} » inactif ici)`,
+		fix: REDIS_BACKPLANE_FIX
+	};
+}
+/**
+* Le backplane déclaré n'a pas pu démarrer — le hub est retombé en local.
+*
+* Distinct de {@link realtimeLocalOnlyNotice} : ici, l'application a DEMANDÉ
+* un fan-out entre exemplaires et ne l'a pas. Deux pods servent alors deux
+* mondes temps réel disjoints, sans erreur visible.
+*
+* @param driver - le driver déclaré.
+* @param reason - la cause (message de l'échec).
+* @returns le point à déclarer.
+*/
+function realtimeBackplaneDownNotice(driver, reason) {
+	return {
+		code: "REALTIME_BACKPLANE_DOWN",
+		level: "warning",
+		message: `Backplane temps réel « ${driver} » indisponible (${reason}) — retombé sur ce seul processus`,
+		fix: driver === "redis" ? "vérifier NF_REDIS_URL et que Redis répond" : void 0
+	};
+}
+export { realtimeBackplaneDownNotice, realtimeLocalOnlyNotice };

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

@@ -1,5 +1,5 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
-//#region nodefony/src/backplane/envelope.ts
+// nodefony/src/backplane/envelope.ts
 /**
 * **Sceau d'enveloppe backplane** — authenticité des messages transportés sur un
 * bus **PARTAGÉ** (Redis pub/sub, et tout driver userland cross-host : NATS,
@@ -106,5 +106,4 @@ function openBackplaneEnvelope(raw, secret) {
 	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
 	return msg;
 }
-//#endregion
 export { openBackplaneEnvelope, sealBackplaneEnvelope };

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

@@ -1,6 +1,6 @@
 import { hostname } from "node:os";
 import { randomUUID } from "node:crypto";
-//#region nodefony/src/backplane/originId.ts
+// nodefony/src/backplane/originId.ts
 /**
 * Résout l'identifiant d'origine d'un backplane — l'étiquette que l'anti-écho
 * compare pour jeter les messages qui reviennent à leur émetteur.
@@ -31,5 +31,4 @@ function resolveBackplaneOriginId() {
 	if (!host) return randomUUID();
 	return `${host}:${process.pid}`;
 }
-//#endregion
 export { resolveBackplaneOriginId as default, resolveBackplaneOriginId };

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

@@ -1,3 +1,4 @@
+import { isThenable } from "../guards.js";
 /**
 * Seuil par défaut d'octets en vol vers le bus : **8 MiB**, aligné sur le seuil de
 * coupure d'un slow-consumer WS. Un bus sain acquitte en quelques millisecondes
@@ -5,10 +6,6 @@
 * au-dessus du régime nominal — le pod a un problème bien avant d'y arriver.
 */
 const DEFAULT_MAX_QUEUE_BYTES = 1 << 23;
-/** Vrai si la valeur se comporte comme une promesse (transport asynchrone). */
-function isThenable(v) {
-	return typeof v === "object" && v !== null && typeof v.then === "function";
-}
 /**
 * File d'envoi bornée : décide d'admettre ou de jeter une publication, puis suit
 * son acquittement pour rendre la place.
@@ -92,5 +89,4 @@ var BackplanePublishQueue = class {
 		};
 	}
 };
-//#endregion
 export { BackplanePublishQueue, BackplanePublishQueue as default, DEFAULT_MAX_QUEUE_BYTES };