@nodefony/realtime 10.0.0-alpha.1

package/dist/nodefony/testing/index.js

@@ -0,0 +1,163 @@
+import { getRealtimeHub } from "../src/server/RealtimeHub.js";
+//#region nodefony/testing/index.ts
+/** `readyState` d'une connexion WebSocket ouverte (`ws` / DOM). */
+const OPEN = 1;
+/** Laisse tourner les microtâches et les timers immédiats. */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+/**
+* Attend qu'une condition devienne vraie, en bornant l'attente.
+*
+* Les chemins du controller mêlent synchrone (refus d'Origin) et asynchrone
+* (authentification, action `async`) : attendre un nombre FIXE de tours rend un
+* test fragile dans un sens et lent dans l'autre.
+*
+* @returns `true` si la condition s'est réalisée avant la borne.
+*/
+async function waitFor(predicate, ticks) {
+	for (let i = 0; i < ticks; i++) {
+		if (predicate()) return true;
+		await tick();
+	}
+	return predicate();
+}
+/**
+* Monte un controller temps réel sur une fausse connexion et rend de quoi le
+* piloter.
+*
+* La fabrique reçoit le contexte à passer au constructeur : c'est la seule
+* chose que le harnais ne peut pas deviner, puisque le nom du service et les
+* dépendances injectées appartiennent au controller.
+*
+* @param create  - construit le controller à partir du contexte fourni.
+* @param options - écarts au décor par défaut (identité, Origin, verrou…).
+* @returns le harnais, prêt pour `connect()`.
+*/
+function createRealtimeHarness(create, options = {}) {
+	const hub = getRealtimeHub();
+	if (options.resetHub !== false) hub.clear();
+	if (options.identity !== void 0) {
+		const token = options.identity;
+		hub.useAuthenticator({ pattern: /.*/u }, {
+			name: "harness",
+			supports: () => true,
+			authenticate: () => Promise.resolve(token)
+		});
+	}
+	if (options.frameAuthorizer !== void 0) hub.setFrameAuthorizer(options.frameAuthorizer);
+	const url = options.url ?? "/realtime";
+	const received = [];
+	const closes = [];
+	const notices = [];
+	let onFinish = null;
+	let closed = false;
+	const connection = {
+		readyState: OPEN,
+		send: (data, cb) => {
+			received.push(JSON.parse(data));
+			cb?.();
+		},
+		close: (code, reason) => {
+			closes.push({
+				code,
+				reason
+			});
+		}
+	};
+	const controller = create({
+		connection,
+		once: (event, fn) => {
+			if (event === "onFinish") onFinish = fn;
+		},
+		request: {
+			headers: options.headers ?? {},
+			url
+		},
+		cookies: options.cookies ?? {},
+		url,
+		remoteAddress: "127.0.0.1",
+		origin: options.origin ?? ""
+	});
+	const bridge = controller;
+	let nextId = 1;
+	const feed = async (frame) => {
+		bridge.handleRealtime(frame === null ? null : JSON.stringify(frame));
+		await tick();
+	};
+	const rpc = (payload) => ({
+		jsonrpc: "2.0",
+		...payload
+	});
+	return {
+		controller,
+		hub,
+		received,
+		closes,
+		notices,
+		async connect() {
+			await feed(null);
+			hub.onPlatformNotice((message) => {
+				notices.push(message);
+			});
+			if (!await waitFor(() => received.some((f) => f.method === "realtime:welcome"), 10)) {
+				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");
+		},
+		async subscribe(channel) {
+			await feed(rpc({
+				method: "subscribe",
+				params: { channel }
+			}));
+		},
+		async unsubscribe(channel) {
+			await feed(rpc({
+				method: "unsubscribe",
+				params: { channel }
+			}));
+		},
+		async call(method, params) {
+			const id = nextId++;
+			await feed(rpc(params === void 0 ? {
+				id,
+				method
+			} : {
+				id,
+				method,
+				params
+			}));
+			const answered = await waitFor(() => received.some((f) => f.id === id), 20);
+			const response = received.find((f) => f.id === id);
+			if (!answered || response === void 0) throw new Error(`createRealtimeHarness: aucune réponse à l'action "${method}".`);
+			if (response.error !== void 0) throw Object.assign(/* @__PURE__ */ new Error(`${method} → ${response.error.message} (${String(response.error.code)})`), { rpc: response.error });
+			return response.result;
+		},
+		async notify(method, params) {
+			await feed(rpc(params === void 0 ? { method } : {
+				method,
+				params
+			}));
+		},
+		async send(frame) {
+			await feed(frame);
+		},
+		messages(channel) {
+			return received.filter((f) => f.method === channel && f.id === void 0).map((f) => f.params);
+		},
+		denials() {
+			return received.filter((f) => f.method === "realtime:denied").map((f) => f.params);
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			connection.readyState = 3;
+			onFinish?.();
+		},
+		dispose() {
+			this.close();
+			hub.clear();
+		}
+	};
+}
+//#endregion
+export { createRealtimeHarness };

package/dist/types/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @nodefony/realtime — Couche realtime serveur Nodefony.
+ *
+ * Ce module porte le hub WebSocket (broker fan-out), le protocole JSON-RPC 2.0
+ * (peer isomorphe partagé avec le client core) et le backplane cluster. Trois
+ * drivers natifs : `loopback` (mono-process), `cluster` (IPC Node) et `redis`
+ * (multi-hôte) ; le registre `backplaneRegistry` est ouvert aux drivers écrits
+ * par l'application.
+ *
+ * Le wiring cluster (`onCluster` → branchement `ClusterBackplane` IPC +
+ * `ClusterProbeClient`) vit dans le hook du Module class ci-dessous. Le client
+ * isomorphe n'est PAS ici : il vit dans le cœur, subpath `nodefony/client`
+ * (décision figée — pas de package navigateur).
+ *
+ * Lire `docs/index.md` pour la vue d'ensemble vulgarisée.
+ *
+ * Voir aussi :
+ *  - CLAUDE.md  — décisions d'archi figées + 5 seams sécurité
+ *  - MEMORY.md  — internals IA
+ *  - README.md  — usage humain
+ *  - docs/      — doc dev vulgarisée
+ */
+import { Kernel, Module } from "nodefony";
+import { type IRealtimeConfig, type IRealtimeConfigInput } from "./nodefony/config/defineModuleConfig.js";
+import RealtimeService from "./nodefony/src/service/RealtimeService.js";
+import RealtimeController from "./nodefony/src/server/RealtimeController.js";
+import ServerRealtimeSocket, { serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
+import RealtimeHub, { getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel } from "./nodefony/src/server/RealtimeHub.js";
+import LoopbackBackplane from "./nodefony/src/backplane/LoopbackBackplane.js";
+import RedisBackplane, { createRedisServiceTransport, resolveRedisChannel, REDIS_RT_CHANNEL } from "./nodefony/src/backplane/RedisBackplane.js";
+import { resolveBackplaneOriginId } from "./nodefony/src/backplane/originId.js";
+import ClusterBackplane, { processIpcTransport } from "./nodefony/src/backplane/ClusterBackplane.js";
+import { registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers } from "./nodefony/src/backplane/backplaneRegistry.js";
+import ClusterProbeClient, { setClusterProbeClient, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, processProbeTransport } from "./nodefony/src/cluster/ClusterProbeClient.js";
+import WsConnectionTransport from "./nodefony/src/transport/WsConnectionTransport.js";
+import { createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth } from "./nodefony/src/server/RealtimeAdminApi.js";
+declare module "nodefony" {
+    interface NodefonyModuleConfig {
+        "@nodefony/realtime": IRealtimeConfigInput;
+    }
+}
+declare class Realtime extends Module<IRealtimeConfig> {
+    #private;
+    /** Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3). */
+    static critical: boolean;
+    constructor(kernel: Kernel);
+    /** JSON Schema de la config realtime → data plane admin (config riche Studio). */
+    configSchema(): unknown;
+    /**
+     * Validation Zod de la config racine merge au boot (convention figée 2026-05-28,
+     * cf [[feedback_config_validation_zod]]) — via le builder `defineRealtimeConfig`
+     * (source unique `nodefony/config/config.ts`). Plante propre avec messages clairs
+     * si la config (defaults + `module.options`) n'est pas conforme au schéma — évite
+     * tous les `undefined.x` silencieux en runtime.
+     *
+     * La config validée + gelée est exposée au container sous `realtimeConfig` pour
+     * que le `RealtimeService` (instancié à `onPreBoot` via `@services`) la consomme
+     * sans dupliquer la validation.
+     */
+    onKernelRegister(): Promise<this>;
+    /**
+     * Phase `onBoot` (avant le `mountAll` de framework dans `onReady`) — enregistre
+     * le producteur admin de la **socket Nodefony** (`/nodefony/realtime/api/*`)
+     * sur le broker `framework/AdminBroker`. Auto-observabilité du `RealtimeHub`.
+     *
+     * ⚠️ Ne PAS déplacer dans `onKernelReady` : framework fait `broker.mountAll()`
+     * dans SON `onKernelReady` ; les modules listés APRÈS framework dans `@modules()`
+     * (cas de @nodefony/realtime) verraient leur `register` rejeté avec
+     * « AdminBroker: register("realtime") après mountAll — routes figées ».
+     * `onKernelBoot` court donc avant et garantit l'ordre.
+     */
+    onKernelBoot(): Promise<this>;
+}
+export default Realtime;
+export { Realtime };
+export { RealtimeController, ServerRealtimeSocket, serverSocket, RealtimeHub, getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel, LoopbackBackplane, ClusterBackplane, RedisBackplane, createRedisServiceTransport, resolveRedisChannel, resolveBackplaneOriginId, REDIS_RT_CHANNEL, registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers, processIpcTransport, ClusterProbeClient, setClusterProbeClient, processProbeTransport, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, WsConnectionTransport, createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth, RealtimeService, };
+export type { RealtimeConfig } from "./nodefony/config/config.js";
+export { ANONYMOUS_REALTIME_TOKEN } from "./nodefony/src/server/AnonymousRealtimeToken.js";
+export { defineRealtimeConfig, realtimeConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
+export type { IRealtimeConfig, IRealtimeConfigInput, } from "./nodefony/config/defineModuleConfig.js";
+export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, getDeclaredBroadcastPrefixes, } from "./nodefony/decorators/realtimeDecorators.js";
+export type { RealtimeChannelFactory } from "./nodefony/decorators/realtimeDecorators.js";
+export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./nodefony/interfaces/IRealtimeController.js";
+export type { IChannelPolicy } from "./nodefony/interfaces/IChannelPolicy.js";
+export type { IClientLogsLimits } from "./nodefony/interfaces/IClientLogsLimits.js";
+export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from "./nodefony/src/server/syslogUplink.js";
+export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.js";
+export type { ChannelSink, ChannelFactory, } from "./nodefony/src/server/RealtimeHub.js";
+export type { IBackplane, IBackplaneMessage, BackplaneHandler, IBackplaneInfo, } from "./nodefony/interfaces/IBackplane.js";
+export type { IClusterBackplaneTransport, ClusterBackplaneEnvelope, } from "./nodefony/src/backplane/ClusterBackplane.js";
+export type { IRedisBackplaneTransport, IRedisPublisher, IRedisSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
+export type { BackplaneFactory, IBackplaneFactoryContext, } from "./nodefony/src/backplane/backplaneRegistry.js";
+export type { IClusterProbeTransport } from "./nodefony/src/cluster/ClusterProbeClient.js";
+export type { RawWsConnection } from "./nodefony/src/transport/WsConnectionTransport.js";
+export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./nodefony/interfaces/IRealtimeProbe.js";
+export type { IRealtimeToken } from "./nodefony/interfaces/IRealtimeToken.js";
+export type { IRealtimeHandshake } from "./nodefony/interfaces/IRealtimeHandshake.js";
+export type { IRealtimeAuthenticator } from "./nodefony/interfaces/IRealtimeAuthenticator.js";
+export type { IRealtimeAuthenticatorMatcher, ICompiledRealtimeMatcher, } from "./nodefony/interfaces/IRealtimeAuthenticatorMatcher.js";

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

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export declare const realtimeConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    backplane: z.ZodDefault<z.ZodObject<{
+        driver: z.ZodDefault<z.ZodString>;
+        namespace: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodString>;
+        maxQueueBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    cluster: z.ZodDefault<z.ZodObject<{
+        probe: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    slowConsumer: z.ZodDefault<z.ZodObject<{
+        bytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    limits: z.ZodDefault<z.ZodObject<{
+        maxChannelsPerConnection: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    csrf: z.ZodDefault<z.ZodObject<{
+        checkOrigin: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            allowList: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            allowMissingOrigin: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    clientLogs: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxEntriesPerBatch: z.ZodDefault<z.ZodNumber>;
+        maxEntriesPerWindow: z.ZodDefault<z.ZodNumber>;
+        windowMs: z.ZodDefault<z.ZodNumber>;
+        maxStringLength: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Type de sortie (config normalisée + défauts appliqués). */
+export type RealtimeConfig = z.infer<typeof realtimeConfigSchema>;
+/**
+ * Défauts du module, matérialisés depuis le schéma (source unique). Toujours
+ * valides par construction ; passés au `super(..., config)` du Module class.
+ */
+declare const config: RealtimeConfig;
+export default config;

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

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { realtimeConfigSchema, type RealtimeConfig } from "./config.js";
+import type { IBackplane } from "../interfaces/IBackplane.js";
+/**
+ * Builder type-safe de la configuration de `@nodefony/realtime`.
+ *
+ * ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+ * pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+ * la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+ * env + freeze) et publie le JSON Schema Studio.
+ *
+ * Principes (alignés sur `defineSecurityConfig`) :
+ * - **Source unique** : `./config.ts` (Zod). Le builder VALIDE + GÈLE, ne dévie pas.
+ * - **Auto-documenté + introspectable** : chaque champ Zod porte `.describe()` →
+ *   {@link realtimeConfigJsonSchema} produit un JSON Schema qu'un formulaire
+ *   Studio (futur) consommera pour générer son UI d'édition.
+ * - **Backplane custom** : instance `IBackplane` userland (NATS, Pulsar…) passée
+ *   via le 2ᵉ argument — **hors** schéma sérialisable (les classes n'ont rien à
+ *   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).
+ *
+ * @param config - configuration brute (sections omises = défauts sûrs).
+ * @param options.backplane - instance `IBackplane` custom (override le driver à
+ *   l'init du `RealtimeService`). Non sérialisable → exclue du JSON Schema.
+ * @returns config gelée prête pour `RealtimeService`.
+ * @throws ZodError si invalide.
+ */
+export declare function defineRealtimeConfig(config?: IRealtimeConfigInput, options?: {
+    backplane?: IBackplane;
+}): IRealtimeConfig;
+/**
+ * JSON Schema introspectable de la config realtime — destiné au formulaire
+ * d'édition Studio (futur). N'inclut PAS `backplane.instance` (non sérialisable).
+ */
+export declare function realtimeConfigJsonSchema(): unknown;
+/** Entrée du builder (champs avec défaut optionnels). */
+export type IRealtimeConfigInput = z.input<typeof realtimeConfigSchema>;
+/** Config normalisée et gelée (sortie du builder, lue par `RealtimeService`). */
+export type IRealtimeConfig = RealtimeConfig & {
+    backplane: RealtimeConfig["backplane"] & {
+        instance?: IBackplane;
+    };
+};

package/dist/types/nodefony/decorators/realtimeDecorators.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Décorateurs realtime de Nodefony — style déclaratif (NestJS-like) pour les
+ * endpoints WebSocket JSON-RPC 2.0 portés par {@link RealtimeController}.
+ *
+ * Les décorateurs **posent des métadonnées** sur le constructeur de la classe
+ * (via `reflect-metadata`, comme {@link controller}/{@link route} dans framework).
+ * La base {@link RealtimeController} les lit au handshake et fusionne avec les
+ * overrides classiques (`realtimeActions()` / `realtimeChannels()` /
+ * `realtimeInbound()` / `createRealtimeChannel()`) → coexistence sans casse.
+ *
+ * ── Pourquoi un nouveau fichier (pas dans framework/routerDecorators) ──
+ *  Les décorateurs HTTP (`route`, `controller`) appartiennent au framework, qui
+ *  ne dépend PAS de realtime (cycle interdit). Le realtime, qui PEUT dépendre du
+ *  framework via peerDep, héberge ses propres décorateurs ici.
+ *
+ * ── Coût ──
+ *  Lecture des métadonnées = 1× au handshake (cold path). Aucun coût par frame.
+ *  Une classe sans décorateur (cas legacy) → Reflect.getMetadata renvoie
+ *  `undefined` (pas d'allocation), fallback sur les overrides classiques.
+ */
+import "reflect-metadata";
+import type { RpcActionHandler } from "nodefony";
+import type { RealtimePublish, RealtimeInboundHandler } from "../interfaces/IRealtimeController.js";
+import type { IChannelPolicy } from "../interfaces/IChannelPolicy.js";
+/**
+ * Politique appliquée à une action RPC dont l'auteur n'a rien déclaré :
+ * **exiger une connexion authentifiée**. Une action est une méthode que le pair
+ * APPELLE et qui AGIT — le défaut sûr est de la fermer, pas de l'ouvrir.
+ * Pour une action délibérément publique, l'écrire : `{ authenticated: false }`.
+ */
+export declare const DEFAULT_ACTION_POLICY: IChannelPolicy;
+/**
+ * Factory d'un provider de canal — appelée par la base au 1ᵉʳ `subscribe`.
+ *
+ * Signature alignée sur {@link RealtimeController.createRealtimeChannel} (la
+ * méthode override historique) pour qu'une migration d'une override `switch` vers
+ * des méthodes décorées reste un copier-coller : même `channel` (nom EXACT du
+ * sous-canal demandé, parfois suffixé `:<ms>` côté client mais ici on matche
+ * **strict**, cf {@link RealtimeChannel}) et même `publish`.
+ *
+ * Retour : `dispose` (idempotent) appelé au dernier `unsubscribe` ET au close
+ * de la connexion qui hébergeait le sink. `null` impossible pour une méthode
+ * décorée (un match exact réussi DOIT démarrer un provider) — c'est le contrat.
+ */
+export type RealtimeChannelFactory = (channel: string, publish: RealtimePublish) => () => void;
+/**
+ * Décorateur **méthode** — expose une **action RPC** request→response du
+ * controller realtime sous le nom `method` (ex. `"nodefony:kernel:ping"`, `"chat:send"`).
+ *
+ * La méthode décorée devient le handler appelé sur une requête entrante AVEC `id` ;
+ * sa valeur de retour est sérialisée comme `result`. Sync OU async (Promise) ;
+ * un throw est mappé sur `-32603 internal error` (Zero Trust — message générique
+ * au pair, détail loggé via `onError`).
+ *
+ * Le `this` est lié à l'instance de controller (`handler.bind(instance)` au
+ * handshake). La méthode peut donc lire `this.context`, `this.kernel`, etc.
+ *
+ * **Autorisation — FERMÉE PAR DÉFAUT.** Une action sans `policy` exige une
+ * connexion **authentifiée**. C'est délibéré : une action est une méthode que le
+ * pair appelle et qui AGIT (`nodefony:kernel:gc`, `nodefony:scaffold:run`, `orders:quote`), et le
+ * verrou de frame laisse passer tout ce qu'aucune politique ne couvre — sans ce
+ * défaut, toute action applicative serait publique sans que rien ne le dise.
+ * Pour une action délibérément ouverte, l'écrire : `{ authenticated: false }`.
+ *
+ * Si une politique est **déjà déclarée sous ce nom** (canal homonyme via
+ * `@RealtimeChannel`/`@RealtimeInbound`), elle est conservée : le défaut ne
+ * rétrograde jamais une politique existante, souvent plus stricte.
+ *
+ * ⚠️ Le NOM peut primer sur ta politique : le plancher système de
+ * `@nodefony/security` réserve les préfixes plateforme (`kernel:`, `syslog:`…)
+ * **et** tout nom contenant `:health` ou `:stats`. Une action ainsi nommée reste
+ * réservée même déclarée `{ authenticated: false }`.
+ *
+ * @param method - nom RPC exposé au pair.
+ * @param policy - politique d'autorisation ; par défaut `{ authenticated: true }`.
+ *
+ * @example
+ *   class ChatController extends RealtimeController {
+ *     @RealtimeAction("chat:ping")                       // authentifié requis
+ *     ping(): { pong: true; ts: number } {
+ *       return { pong: true, ts: Date.now() };
+ *     }
+ *
+ *     @RealtimeAction("admin:purge", { roles: ["ROLE_ADMIN"] })
+ *     purge(): void {}
+ *
+ *     @RealtimeAction("catalog:browse", { authenticated: false })  // ouvert, assumé
+ *     browse(): string { return "ok"; }
+ *   }
+ */
+export declare function RealtimeAction(method: string, policy?: IChannelPolicy): MethodDecorator;
+/**
+ * Décorateur **méthode** — expose un **canal pub/sub** sous le nom `channel`
+ * (match EXACT, sans préfixe `:<ms>` ni regex). La méthode décorée DOIT renvoyer
+ * un `dispose: () => void` (la base le mémorise et l'appelle au dernier
+ * désabonné, comme avec l'override classique).
+ *
+ * v1 — match EXACT uniquement. Les canaux à pattern (`/^nodefony:orm:rich@(\d+)/`) ou à
+ * suffixe de granularité (`nodefony:dashboard:1000`) restent dans l'override
+ * `createRealtimeChannel()` (la base donne PRIORITÉ aux décorateurs, puis tombe
+ * sur l'override en fallback — coexistence sans casse). Un mode `pattern: RegExp`
+ * arrivera plus tard sans rompre cette API.
+ *
+ * Le `this` est lié à l'instance ; le factory peut donc lire `this.kernel`, etc.
+ * Mais ATTENTION : un provider est **partagé** entre toutes les connexions au
+ * même canal (cf `RealtimeHub.subscribe`) — il survit à la connexion qui l'a
+ * créé. Capturer des **valeurs long-lived** (broker, syslog) dans la closure,
+ * jamais `this.context` (lié à la connexion créatrice qui peut fermer).
+ *
+ * @example
+ *   class ChatController extends RealtimeController {
+ *     @RealtimeChannel("chat:room42")
+ *     room42(_channel: string, publish: RealtimePublish): () => void {
+ *       const timer = setInterval(() => publish("chat:room42", { ts: Date.now() }), 1000);
+ *       return () => clearInterval(timer);
+ *     }
+ *   }
+ */
+export declare function RealtimeChannel(channel: string, policy?: IChannelPolicy): MethodDecorator;
+/**
+ * Décorateur **méthode** — déclare un **canal FULL-DUPLEX entrant** (méthode WS
+ * inverse : le client pousse via une notification `method: <name>`, params libres,
+ * sans `id`). La méthode décorée reçoit `(params, reply)` :
+ *  - `params` : NON FIABLE (entrée client) — valider AVANT d'agir.
+ *  - `reply(payload)` : push serveur→client sur le MÊME canal, vers CETTE connexion.
+ *
+ * Équivalent décoratif de `realtimeInbound()` override. Sécurité : un canal n'est
+ * inbound QUE s'il est explicitement déclaré (défaut sûr — un client ne peut rien
+ * pousser tant qu'aucun handler n'est enregistré ici). Cf seam P13.8a
+ * (`beforeDispatch`) pour la gate sécurité par voter P6.
+ *
+ * @example
+ *   class ChatController extends RealtimeController {
+ *     @RealtimeInbound("chat:send")
+ *     onChatSend(params: unknown, reply: (payload: unknown) => void): void {
+ *       const text = (params as { text?: unknown })?.text;
+ *       if (typeof text !== "string") return;
+ *       reply({ ok: true, echoed: text });
+ *     }
+ *   }
+ */
+export declare function RealtimeInbound(method: string, policy?: IChannelPolicy): MethodDecorator;
+/** Lecture (lazy, au handshake) du registre des actions décorées. */
+export declare function getRealtimeActions(instance: object): Record<string, RpcActionHandler> | null;
+/** Lecture (lazy, au handshake) du registre des canaux décorés. */
+export declare function getRealtimeChannels(instance: object): Record<string, RealtimeChannelFactory> | null;
+/** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */
+export declare function getRealtimeInbound(instance: object): Record<string, RealtimeInboundHandler> | null;
+/**
+ * Lecture (lazy, au handshake) des politiques d'autorisation déclarées
+ * (`@RealtimeChannel`/`@RealtimeInbound` avec opts). `null` si aucune → le
+ * controller n'enregistre rien au hub (0 alloc). Donnée pure (pas de `bind` :
+ * une policy n'est pas une méthode), renvoyée telle quelle pour publication au
+ * hub realtime, qui l'expose à `@nodefony/security`.
+ */
+export declare function getRealtimeChannelPolicies(instance: object): Record<string, IChannelPolicy> | null;
+/**
+ * Décorateur **classe** — déclare les préfixes de canaux **broadcast**
+ * (cross-process) servis par cet endpoint : leurs publications traversent le
+ * {@link IBackplane} au lieu de rester dans le processus.
+ *
+ * POURQUOI STATIQUE (trouvé sur un banc multi-pods) : la politique de forward
+ * est une propriété du code, pas de l'instant. Déclarée seulement au handshake
+ * — via l'override `realtimeBroadcastChannels()` — elle laissait un pod qui
+ * publie **sans abonné local** (job planifié, webhook, worker) ne rien
+ * propager : `publish` évaluait « pas broadcast », en silence. Ici la
+ * déclaration existe dès l'import de la classe ; le service l'applique au hub
+ * au boot, identiquement sur tous les pods.
+ *
+ * @example
+ *   \@RealtimeBroadcast("chat:", "presence:")
+ *   \@controller("/api/chat")
+ *   class ChatController extends RealtimeController { … }
+ *
+ * @param prefixes - préfixes de canal (`"chat:"` couvre `chat:room1:1000`).
+ */
+export declare function RealtimeBroadcast(...prefixes: string[]): ClassDecorator;
+/** Préfixes broadcast déclarés par décorateur (introspection / tests). */
+export declare function getDeclaredBroadcastPrefixes(): string[];
+/**
+ * Applique au hub les préfixes broadcast déclarés statiquement. Appelé au boot
+ * par `RealtimeService` — avant tout trafic, donc la politique est en place que
+ * le pod ait ou non reçu une connexion. Idempotent
+ * ({@link RealtimeHub.markBroadcastChannel} l'est déjà).
+ *
+ * @param hub - hub à configurer (celui du processus).
+ */
+export declare function applyDeclaredBroadcastPrefixes(hub: {
+    markBroadcastChannel(prefix: string): void;
+}): void;