@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,128 @@
+/**
+ * Port du **backplane** de la socket Nodefony — l'abstraction de fan-out
+ * **CROSS-PROCESS** du {@link RealtimeHub}.
+ *
+ * Le hub fait le fan-out **local** (aux connexions du process courant). Le backplane
+ * propage une publication aux **autres pairs** (autres workers d'un même pod via IPC,
+ * autres pods via Redis…) et réinjecte localement ce que les pairs publient. C'est
+ * **le même contrat** quel que soit le backing — c'est tout l'intérêt : on définit le
+ * port UNE fois et on prouve l'archi avec plusieurs implémentations interchangeables :
+ *
+ *  - {@link LoopbackBackplane} — mono-process, **no-op** (aucun pair) ;
+ *  - `ClusterBackplane` (IPC, master-gateway) — pairs = workers du même pod, SANS infra
+ *    → « comme si Redis était là » : le banc d'essai qui stabilise l'archi multi-process ;
+ *  - `RedisBackplane` (P13) — pairs = pods du cluster, **drop-in** (le hub ne change pas).
+ *
+ * Anti-boucle (règle absolue) : une publication locale part vers le backplane, mais un
+ * message **reçu** du backplane est réinjecté en **fan-out LOCAL UNIQUEMENT** (jamais
+ * re-publié vers le backplane, sinon tempête). Le hub applique cette barrière en
+ * appelant `RealtimeHub.publishLocal` dans son handler. Le backplane applique la 2ᵉ
+ * barrière : il **filtre son propre {@link originId}** (echo) avant d'appeler le handler.
+ *
+ * Sémantique de livraison : **best-effort / at-most-once** (comme un pub/sub) — aucune
+ * garantie de delivery ni d'ordre cross-pair ; le client realtime re-synchronise. Ne pas
+ * sur-concevoir une fiabilité que les backings (Redis pub/sub) n'offrent pas.
+ *
+ * Cf vision « la socket Nodefony » + mémoire `project_cluster_backplane_vision`.
+ */
+/**
+ * Compteurs de la **file d'envoi** d'un backplane à transport réseau : ce qui est
+ * publié mais pas encore acquitté par le bus. Sans borne, cette file (interne au
+ * client réseau) grossit sans limite sous rafale — d'où le seuil et ses compteurs,
+ * exposés jusqu'à la sonde et Studio. Cf `BackplanePublishQueue`.
+ */
+export interface IBackplaneQueueInfo {
+    /** Octets publiés en attente d'acquittement par le transport (instantané). */
+    bytes: number;
+    /** Seuil au-dessus duquel une publication est jetée ; `0` = illimité. */
+    maxBytes: number;
+    /** Publications JETÉES faute de place (monotone). `0` en régime sain. */
+    droppedTotal: number;
+    /** Publications REFUSÉES par le transport (bus coupé…) (monotone). */
+    failedTotal: number;
+}
+/**
+ * Message transporté entre pairs par le backplane. Sérialisé une fois à l'émission
+ * (IPC `structuredClone` / Redis JSON) ; le `payload` doit donc être structurellement
+ * clonable / sérialisable (pas de fonction, pas de cycle).
+ */
+export interface IBackplaneMessage {
+    /** Canal logique (mêmes noms que côté hub, suffixe de cadence `:<ms>` inclus). */
+    channel: string;
+    /** Charge applicative diffusée sur le canal. */
+    payload: unknown;
+    /** Identité du pair **émetteur** — sert l'anti-echo (cf {@link IBackplane.originId}). */
+    originId: string;
+}
+/**
+ * Handler d'ingress : reçoit un message publié par un **autre** pair. L'echo du pair
+ * courant a déjà été filtré par l'implémentation → le handler peut réinjecter sans
+ * condition (mais en fan-out **local only**).
+ */
+export type BackplaneHandler = (msg: IBackplaneMessage) => void;
+/**
+ * **Carte d'identité** d'un backplane — descripteur de DONNÉE (pas un log) décrivant
+ * l'état du fond de panier. Source unique alimentant trois sorties cohérentes : la
+ * ligne stdout au boot, le champ `backplane` de la sonde (`/api/health`) et la vue
+ * Studio. Réutilisable par les tests / un agent IA sans dupliquer la connaissance
+ * « c'est quoi ce backplane ».
+ */
+export interface IBackplaneInfo {
+    /** Nom du driver (clé du registre). Ex. `redis`, `cluster`, `loopback`. */
+    driver: string;
+    /** Nature du transport. Ex. `redis-pubsub`, `ipc`, `local`. */
+    kind: string;
+    /** Identité de CE pair (process/pod). Ex. `String(process.pid)`. */
+    originId: string;
+    /** `true` si le fan-out franchit les frontières de pod (multi-host). */
+    crossPod: boolean;
+    /** Canal/topic de transport, si applicable (canal Redis, topic Kafka). */
+    channel?: string;
+    /**
+     * Les messages sont-ils **scellés** (authenticité de l'émetteur vérifiée) ?
+     * Renseigné par les drivers à transport PARTAGÉ, où un tiers peut écrire :
+     * `false` y signale un bus ouvert. Absent quand la question n'a pas de sens
+     * (mono-process, IPC master↔workers — authentifié par construction).
+     */
+    sealed?: boolean;
+    /**
+     * État de la **file d'envoi** vers le bus (octets en vol, seuil, jetés). Renseigné
+     * par les drivers à transport RÉSEAU, dont les publications sont acquittées de
+     * façon asynchrone : c'est là qu'un bus lent fait grossir la mémoire du pod.
+     * `droppedTotal > 0` = du fan-out cross-pod a été sacrifié pour tenir la mémoire.
+     * Absent quand le transport n'a pas de file (mono-process, IPC synchrone).
+     */
+    queue?: IBackplaneQueueInfo;
+}
+/**
+ * Contrat d'un backplane realtime. Implémentation **stateless du point de vue métier**
+ * (l'état des canaux vit dans le hub) ; le backplane ne porte que le transport vers les
+ * pairs + son identité.
+ */
+export interface IBackplane {
+    /** Identité stable de CE pair (process/pod). Discrimine l'echo. Ex. `String(process.pid)`. */
+    readonly originId: string;
+    /**
+     * Démarre le transport vers les pairs (connexion IPC/Redis, abonnements). Idempotent.
+     * Peut être synchrone (IPC) ou asynchrone (Redis) → retour `void | Promise<void>`.
+     */
+    start(): void | Promise<void>;
+    /**
+     * Propage une publication locale aux **autres** pairs. NE refait PAS le fan-out local
+     * (déjà fait par le hub). No-op s'il n'y a aucun pair (mono-process).
+     */
+    publish(channel: string, payload: unknown): void;
+    /**
+     * Enregistre le handler d'ingress (messages venus des autres pairs, echo déjà filtré).
+     * Un seul handler à la fois — un appel ultérieur remplace le précédent.
+     */
+    onMessage(handler: BackplaneHandler): void;
+    /** Arrête le transport et libère les ressources (connexions, listeners). Idempotent. */
+    stop(): void | Promise<void>;
+    /**
+     * Carte d'identité du backplane (driver, transport, origine, cross-pod, canal).
+     * Donnée pure — consommée par le log de boot, la sonde santé et Studio.
+     */
+    describe(): IBackplaneInfo;
+}
+export default IBackplane;

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

@@ -0,0 +1,28 @@
+/**
+ * Politique d'autorisation d'un **canal** WebSocket — exigences à satisfaire
+ * pour s'y abonner (`subscribe`) ou y pousser (canal inbound full-duplex).
+ *
+ * Déclarée côté métier via {@link RealtimeChannel}/{@link RealtimeInbound}
+ * (`@RealtimeChannel("admin:x", { roles: ["ROLE_ADMIN"] })`), agrégée par le
+ * {@link RealtimeHub} et **lue par `@nodefony/security`** (P6) au moment de la
+ * frame via le seam `resolveChannelPolicy`. Le module realtime NE décide PAS de
+ * l'autorisation (il ne connaît ni la hiérarchie de rôles ni l'identité réelle) :
+ * il ne fait que **transporter la déclaration** jusqu'au décideur (le firewall).
+ *
+ * ⚠️ Cette interface est un **miroir structurel** de `IChannelPolicy` côté
+ * `@nodefony/security` (`realtimeContracts.ts`) — les deux modules ne s'importent
+ * pas (`package.json` disjoints). Le typage structurel de TS fait le pont à
+ * l'exécution. Toute dérive de forme casserait le seam silencieusement.
+ *
+ * Champs cumulatifs (ET) ; un champ absent = pas de contrainte sur cet axe ;
+ * objet entièrement vide = canal libre (équivaut à « pas de politique »).
+ */
+export interface IChannelPolicy {
+    /** Exige une connexion authentifiée (token non anonyme). */
+    readonly authenticated?: boolean;
+    /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté security). */
+    readonly roles?: readonly string[];
+    /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
+    readonly scopes?: readonly string[];
+}
+export default IChannelPolicy;

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

@@ -0,0 +1,22 @@
+/**
+ * Bornes de la réception des journaux remontés par un navigateur.
+ *
+ * Elles vivent dans une interface à part parce qu'elles voyagent : la configuration du
+ * module les produit, le hub les porte, et le contrôleur les consomme au handshake pour
+ * fabriquer le handler d'une connexion. Le hub n'en DÉCIDE rien — il les transporte,
+ * comme il transporte la garde d'origine et le plafond de canaux.
+ *
+ * Leur présence vaut ouverture du canal : `null` sur le hub = aucun handler entrant
+ * déclaré pour `nodefony:syslog:uplink`, donc une frame qui l'invoque est droppée comme
+ * n'importe quelle méthode inconnue.
+ */
+export interface IClientLogsLimits {
+    /** Entrées retenues par lot reçu ; le surplus est ignoré. */
+    readonly maxEntriesPerBatch: number;
+    /** Entrées retenues par fenêtre et par connexion. */
+    readonly maxEntriesPerWindow: number;
+    /** Durée de la fenêtre de débit, en ms. */
+    readonly windowMs: number;
+    /** Longueur maximale d'une chaîne acceptée (message, pile). */
+    readonly maxStringLength: number;
+}

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

@@ -0,0 +1,53 @@
+import type { IRealtimeHandshake } from "./IRealtimeHandshake.js";
+import type { IRealtimeToken } from "./IRealtimeToken.js";
+/**
+ * Stratégie d'authentification au handshake WebSocket — équivalent realtime du
+ * pattern `IAuthenticator` côté HTTP de `@nodefony/security`.
+ *
+ * Plusieurs authenticators sont enregistrés sur le hub via
+ * `RealtimeService.useAuthenticator(matcher, authenticator)`. Au handshake, le
+ * hub itère les matchers ordonnés ; le **1ʳᵉ** qui matche capture la connexion,
+ * son authenticator est exécuté (`supports` puis `authenticate`).
+ *
+ * Implémentations futures (P6) : `AnonymousRealtimeAuthenticator`,
+ * `JwtRealtimeAuthenticator` (cookie HTTP-only), `ApiKeyRealtimeAuthenticator`.
+ *
+ * **SYNC vs ASYNC** — l'authentification PEUT être asynchrone (handshake = 1×
+ * par connexion, cold path). Le RÉSULTAT (`IRealtimeToken`) est ensuite caché
+ * par le hub sur le peer ; les hooks hot-path (`beforeDispatch`, `onFrameAudit`)
+ * le lisent en O(1) sans recalculer l'auth par frame (cf
+ * `JsonRpcPeerOptions.beforeDispatch` — doctrine sync stricte du dispatch).
+ *
+ * @see IRealtimeAuthenticatorMatcher
+ */
+export interface IRealtimeAuthenticator {
+    /** Nom logique (référencé dans les matchers, ex. `"realtime_jwt"`). */
+    readonly name: string;
+    /**
+     * Peut-on extraire un credential de cette requête upgrade ? (sinon le hub
+     * pose un token anonyme par défaut).
+     */
+    supports(handshake: IRealtimeHandshake): boolean;
+    /**
+     * Valide le credential et renvoie un token AUTHENTIFIÉ.
+     *
+     * `throw` une erreur (typiquement `AuthenticationError`) → le hub ferme la
+     * connexion WebSocket avec un code 4001 (`unauthorized`, plage applicative
+     * RFC 6455 §7.4.2) et n'instancie pas de peer.
+     *
+     * En cas de succès, le token est POSÉ par le hub sur la map `peer → token`.
+     */
+    authenticate(handshake: IRealtimeHandshake): Promise<IRealtimeToken>;
+    /**
+     * Hook succès — appelé APRÈS pose du token sur le peer, AVANT le welcome
+     * JSON-RPC. Sert à journaliser (audit S1), poser un cookie de session si
+     * besoin (rare en WS), etc. `void` (pas de back-pressure handshake).
+     */
+    onSuccess?(handshake: IRealtimeHandshake, token: IRealtimeToken): void;
+    /**
+     * Hook échec — appelé APRÈS qu'`authenticate` a throw, AVANT la fermeture
+     * de la socket (code 4001). Permet de tracer l'échec sans interrompre la
+     * fermeture. Throw d'ici est ignoré (catch défensif côté hub).
+     */
+    onFailure?(handshake: IRealtimeHandshake, error: Error): void;
+}

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

@@ -0,0 +1,46 @@
+import type { IRealtimeHandshake } from "./IRealtimeHandshake.js";
+/**
+ * Sélecteur d'une zone WS protégée — équivalent realtime de `ISecuredArea`
+ * côté HTTP de `@nodefony/security` (pattern URL + vhost optionnel).
+ *
+ * Le hub stocke les matchers dans l'ordre d'enregistrement ; le **1ʳᵉ** dont
+ * `match()` renvoie `true` capture le handshake. Convention : enregistrer les
+ * patterns les plus spécifiques EN PREMIER.
+ *
+ * @example
+ * ```ts
+ * // Zone admin (préfixe + vhost) — JWT obligatoire
+ * realtimeService.useAuthenticator(
+ *   { pattern: /^\/admin\//, host: "admin.example.com" },
+ *   jwtAuthenticator,
+ * );
+ * // Zone publique chat — anonyme accepté
+ * realtimeService.useAuthenticator(
+ *   { pattern: /^\/chat\// },
+ *   anonymousAuthenticator,
+ * );
+ * ```
+ */
+export interface IRealtimeAuthenticatorMatcher {
+    /**
+     * Pattern d'URL (path) — string compilé en RegExp (escape complet) OU RegExp
+     * fournie telle quelle. La RegExp est testée contre `handshake.url` (le path
+     * sans query string).
+     */
+    readonly pattern: string | RegExp;
+    /**
+     * Vhost (Host header) optionnel — match exact (insensible à la casse). Omis
+     * = tous domaines. Parité avec `ISecuredArea.host` HTTP.
+     */
+    readonly host?: string;
+}
+/**
+ * Forme compilée d'un matcher — utilisé en interne par le hub (cache de la
+ * RegExp compilée + host lowercase). Pas destiné à l'API publique.
+ */
+export interface ICompiledRealtimeMatcher {
+    readonly pattern: RegExp;
+    readonly host?: string;
+    /** Le matcher capture-t-il ce handshake ? */
+    match(handshake: IRealtimeHandshake): boolean;
+}

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

@@ -0,0 +1,36 @@
+/** Publie une charge sur un canal (notification serveur→client). */
+export type RealtimePublish = (channel: string, payload: unknown) => void;
+/**
+ * Handler d'un message ENTRANT sur un canal full-duplex (client → serveur). C'est le
+ * seam des backings entrants (SIP, bridge) : le client `publish(channel, payload)` ; si
+ * le contrôleur a déclaré ce canal dans `realtimeInbound()`, le handler est appelé.
+ *
+ * - `params` = la charge du client. **NON FIABLE** (Zero Trust) : le handler DOIT la
+ *   valider (origine non authentifiée au niveau transport).
+ * - `reply` = pousse une charge serveur→client sur le MÊME canal, vers CETTE connexion
+ *   uniquement (ex. réponse SIP). Per-connexion (≠ fan-out).
+ *
+ * Par défaut aucun canal n'accepte d'entrée (sûr) : un contrôleur opte explicitement.
+ */
+export type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown) => void) => void;
+/**
+ * IRealtimeController — contrat d'un contrôleur temps réel SERVEUR (endpoint WS
+ * JSON-RPC 2.0). Le protocole (discrimination, dispatch, actions, pending, pub/sub,
+ * cleanup) est porté par {@link RealtimeController} via un `JsonRpcPeer` PAR
+ * connexion ; le contrôleur concret ne fournit QUE ses providers de canaux.
+ *
+ * (Les hooks `realtimeActions()` / `realtimeChannels()` sont `protected` sur la base
+ * — détail d'implémentation surchargeable, hors contrat public.)
+ *
+ * Côté client, le pendant n'est PAS un controller mais `RealtimeClient` — tous deux
+ * composent le même peer ; cf vision « la socket Nodefony ».
+ */
+export interface IRealtimeController {
+    /**
+     * Crée le provider d'un canal au `subscribe` (démarre listener/ticker, pousse via
+     * `publish`) et renvoie son `dispose` (appelé au `unsubscribe` ET à la fermeture).
+     * `null` si le canal est inconnu.
+     */
+    createRealtimeChannel(channel: string, publish: RealtimePublish): (() => void) | null;
+}
+export default IRealtimeController;

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

@@ -0,0 +1,27 @@
+/**
+ * Données de handshake WebSocket — DTO minimal passé à un
+ * {@link IRealtimeAuthenticator} pour qu'il extraie un credential et valide
+ * l'identité, SANS coupler ce module à `@nodefony/http` runtime.
+ *
+ * Construit par `RealtimeController.onHandshake()` depuis le `WebsocketContext`
+ * (request upgrade HTTP) puis consommé une seule fois par connexion (cold path).
+ *
+ * Cookies : déjà PARSÉS en `Map<string, string>` (et non l'en-tête `Cookie` brut)
+ * — la plupart des authenticators stateless WS lisent un cookie JWT.
+ *
+ * @see IRealtimeAuthenticator
+ */
+export interface IRealtimeHandshake {
+    /** En-têtes de la requête upgrade (clés en lowercase RFC 7230 §3.2). */
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    /** Cookies parsés depuis `Cookie:` (vide si en-tête absent ou mal formé). */
+    readonly cookies: ReadonlyMap<string, string>;
+    /** URL de l'upgrade (pathname + query string), ex. `/realtime?token=...`. */
+    readonly url: string;
+    /** 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;
+    /** Sous-protocoles annoncés (`Sec-WebSocket-Protocol`). `[]` si aucun. */
+    readonly protocols: readonly string[];
+}

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

@@ -0,0 +1,206 @@
+/**
+ * Contrats d'**auto-observabilité de la socket Nodefony** — la sonde SERVEUR du
+ * {@link RealtimeHub}. Applique le patron sondes+hub (comme les sondes ORM) à la
+ * couche realtime elle-même : « la socket s'observe à travers elle-même ».
+ *
+ * Trois familles de signaux, dérivées de l'analyse du multiplexing N canaux / 1 WS
+ * (le design est bon mais déplace 3 responsabilités sur le hub) :
+ *  - **fan-out** : combien de canaux, d'abonnés, de livraisons (chatter du broker) ;
+ *  - **backpressure** (risque #1, SEUL vrai blocker mémoire) : `bufferedAmount` par
+ *    connexion — une connexion lente fait grossir la file `ws` → OOM, et le
+ *    multiplexing CONCENTRE (1 WS lente bloque TOUS ses canaux) ;
+ *  - **débit octets/frames** : matière à mesurer AVANT d'optimiser (stringify unique,
+ *    seuil de drop). Tous les cumuls sont **monotones** → le débit/s se dérive côté
+ *    lecteur (delta `total`/`ts`, comme le CPU% ou le flux ORM) : 0 état de lecture.
+ */
+import type { IProcessHealth, IProcessRich, IOrmLeanHealth, IInstanceErrorHealth } from "nodefony";
+import type { IBackplaneInfo } from "./IBackplane.js";
+/** Vue d'UNE connexion realtime pour la sonde (backpressure = risque #1). */
+export interface IRealtimeConnProbe {
+    /** État du transport (0..3, aligné `WebSocket.readyState`). */
+    readonly readyState: number;
+    /**
+     * Octets en file d'envoi NON encore drainés vers le réseau (`ws.bufferedAmount`).
+     * > 0 durablement = slow-consumer → la file interne grossit (borne = timeout TCP)
+     * → pression mémoire. C'est LE signal du blocker #1.
+     */
+    readonly bufferedAmount: number;
+    /** Cumul d'octets envoyés à cette connexion (monotone). */
+    readonly bytesSent: number;
+    /** Cumul de frames envoyées à cette connexion (monotone). */
+    readonly messagesSent: number;
+    /**
+     * Cumul de frames JETÉES par back-pressure sur cette connexion (monotone) :
+     * drop latest-wins (`bufferedAmount ≥` seuil DROP) + la frame en cours quand on
+     * coupe un slow-consumer (`close 1013`). `> 0` = ce client n'absorbe pas le flux.
+     */
+    readonly dropped: number;
+}
+/** Stat per-canal du hub (fan-out). */
+export interface IRealtimeChannelStat {
+    /** Nom du canal (suffixe `:<ms>` de granularité inclus). */
+    channel: string;
+    /** Abonnés locaux vivants (sinks) — instantané. */
+    subscribers: number;
+    /** Publications cumulées sur ce canal (monotone) → débit dérivé côté lecteur. */
+    messages: number;
+}
+/**
+ * Snapshot PUR du hub (sans identité process) — ce que renvoie
+ * {@link RealtimeHub.probe}. Per-instance/pod (cloud-native) ; l'agrégat multi-pod
+ * = backplane Redis / Prometheus (P13).
+ */
+export interface IRealtimeProbe {
+    /** Horodatage du snapshot (ms epoch) — base du calcul de débit côté lecteur. */
+    ts: number;
+    /** Canaux actifs (≥ 1 abonné) avec abonnés + publications cumulées. */
+    channels: IRealtimeChannelStat[];
+    /** Nombre de canaux actifs (= 1 provider/canal/pod). */
+    channelCount: number;
+    /** Appels `publish` cumulés (monotone). */
+    publishTotal: number;
+    /** Livraisons cumulées (`publish` × abonnés) — vrai coût de fan-out (monotone). */
+    fanoutTotal: number;
+    /** Frames entrantes full-duplex cumulées (canaux gated SIP/bridge) (monotone). */
+    inboundTotal: number;
+    /**
+     * Messages d'ingress backplane REFUSÉS (canal non déclaré broadcast) — monotone.
+     * Reste à 0 en fonctionnement normal : un pair légitime n'émet que des canaux
+     * broadcast. Un compteur qui décolle = pair mal configuré, ou écriture tierce
+     * dans un bus partagé (Redis mutualisé). Cf `RealtimeHub` (contrôle d'admission).
+     */
+    ingressRejectedTotal: number;
+    /**
+     * Abonnements clients REFUSÉS par le plancher des canaux de plateforme —
+     * monotone. Un canal réservé (`syslog:`, `orm:`…) a été demandé alors qu'aucun
+     * module de sécurité n'est chargé : sans identité vérifiable, le hub ferme.
+     * `> 0` signale une configuration incomplète (sécurité absente) autant qu'une
+     * tentative d'accès — dans les deux cas, quelque chose est à regarder.
+     */
+    systemFloorDeniedTotal: number;
+    /** Connexions realtime vivantes. */
+    connectionCount: number;
+    /** Somme cumulée des octets envoyés, toutes connexions (monotone). */
+    bytesSentTotal: number;
+    /** Somme cumulée des frames envoyées, toutes connexions (monotone). */
+    messagesSentTotal: number;
+    /** Backpressure agrégée (instantanée) — risque #1. */
+    backpressure: {
+        /** Pire `bufferedAmount` parmi les connexions (octets). */
+        maxBufferedAmount: number;
+        /** Somme des `bufferedAmount` (octets en attente process-wide). */
+        totalBufferedAmount: number;
+        /** Connexions au-dessus du seuil d'alerte slow-consumer. */
+        slowConsumers: number;
+        /**
+         * Cumul de frames jetées par back-pressure (drop latest-wins + close
+         * slow-consumer), toutes connexions (monotone) → taux de perte dérivé côté
+         * lecteur. `0` en régime sain ; croît = des clients lents sont contenus pour
+         * protéger la mémoire process (sinon file `ws` non bornée → OOM).
+         */
+        drops: number;
+    };
+    /**
+     * Carte d'identité du backplane effectif (driver, transport, cross-pod, canal).
+     * Reflète l'état RÉEL : `local` si le hub n'a aucun backplane (mono-process ou
+     * fallback fail-soft), sinon le descripteur du driver branché. Optionnel pour
+     * rétrocompat des consommateurs qui construisent un probe partiel.
+     */
+    backplane?: IBackplaneInfo;
+}
+/** Snapshot enrichi de l'identité d'instance — santé per-instance d'un worker/pod. */
+export interface IRealtimeHealth extends IRealtimeProbe {
+    /** Identifiant de CE process/pod (per-instance). */
+    instanceId: string;
+    /**
+     * Santé PROCESS du worker (CPU/mém/event-loop) — additif : la grille « salle des
+     * machines » de la vue pod lit `instances[].process` par worker. Optionnel (absent si
+     * sonde process coupée) → les consommateurs realtime existants l'ignorent (non-breaking).
+     */
+    process?: IProcessHealth;
+    /**
+     * Sonde process **riche** (GC/heap-spaces/handles/ELU active-idle/ctx-switches) —
+     * présente UNIQUEMENT pendant un drill-down de CE worker (Phase 2 : le master a envoyé
+     * `nf:probe:enrich` à ce pid). Absente sinon → « on paie ce qu'on regarde » (0 surcoût
+     * hors drill). Fusionnée côté front avec `process` pour la vue Supervision complète.
+     */
+    rich?: IProcessRich;
+    /**
+     * Santé ORM **lean** du worker (connecteurs/requêtes/erreurs/latence EWMA) — additif,
+     * comme `process`. Présent si un driver ORM a branché sa sonde (`setOrmHealthProvider`),
+     * absent sinon → les consommateurs realtime l'ignorent (non-breaking). Agrégée pod dans
+     * {@link IRealtimeClusterHealth.totals}.`orm`.
+     */
+    orm?: IOrmLeanHealth;
+    /**
+     * Compteurs d'erreurs Syslog du worker (ERROR/CRITIC cumulés) — additif. Permet une
+     * carte « erreurs par worker » + un taux d'erreur pod (delta côté lecteur). Absent si la
+     * sonde n'a pu lire le syslog du kernel.
+     */
+    errors?: IInstanceErrorHealth;
+    /**
+     * Drivers de backplane **enregistrés dans ce process** (clés du registre ouvert :
+     * natifs + ceux qu'une application a ajoutés par `registerBackplaneDriver`). Sert la
+     * même question que la liste des backends côté stores : « qu'est-ce que je POURRAIS
+     * brancher ? », à laquelle `backplane.driver` (l'actif) ne répond pas. Absent si le
+     * registre n'est pas joignable.
+     */
+    backplaneDrivers?: string[];
+    /**
+     * Diagnostic ORM **riche** du worker (par connecteur : ping/latence/stockage/pool +
+     * flux requêtes) — blob OPAQUE `{ health, flow }` produit par le driver, présent
+     * UNIQUEMENT pendant un drill ORM de CE worker (facette `"orm"` : le master a envoyé
+     * `nf:probe:enrich {facet:"orm"}` à ce pid). Absent sinon → « on paie ce qu'on regarde »
+     * (0 ping ORM hors drill). Consommé par la page drill `/nodefony/orm/<pid>` (canal
+     * `nodefony:orm:rich@<pid>`) → diagnostic riche du pid EXACT (≠ round-robin).
+     */
+    ormRich?: unknown;
+}
+/**
+ * Vue **POD agrégée** de la socket (Phase 4c, mode cluster) — la santé de TOUS les workers
+ * du pod consolidée. Servie par n'importe quel worker via l'endpoint santé quand le master
+ * pousse le snapshot agrégé (sinon on retombe sur {@link IRealtimeHealth} per-instance).
+ *
+ * `cluster: true` est le discriminant : un consommateur (Studio) distingue la vue pod de la
+ * vue per-instance. `instances` garde le détail par worker (drill-down) ; `totals` somme les
+ * scalaires (la backpressure `maxBufferedAmount` est un MAX, pas une somme — c'est le pire pod).
+ */
+export interface IRealtimeClusterHealth {
+    /** Discriminant : vue agrégée multi-worker (≠ {@link IRealtimeHealth} per-instance). */
+    cluster: true;
+    /** Horodatage du snapshot agrégé (ms epoch). */
+    ts: number;
+    /** Nombre de workers présents dans l'agrégat. */
+    instanceCount: number;
+    /** Santé par worker (détail per-instance pour le drill-down). */
+    instances: IRealtimeHealth[];
+    /** Totaux pod (sommes des scalaires ; backpressure max = pire worker). */
+    totals: {
+        channelCount: number;
+        publishTotal: number;
+        fanoutTotal: number;
+        inboundTotal: number;
+        /** Ingress backplane refusés, tous workers (signal de sécurité pod-wide). */
+        ingressRejectedTotal: number;
+        connectionCount: number;
+        bytesSentTotal: number;
+        messagesSentTotal: number;
+        backpressure: {
+            /** Pire `maxBufferedAmount` parmi les workers (octets) — pas une somme. */
+            maxBufferedAmount: number;
+            /** Somme des octets en attente, tous workers. */
+            totalBufferedAmount: number;
+            /** Total des slow-consumers du pod. */
+            slowConsumers: number;
+            /** Total des frames jetées par back-pressure (drop + close), tous workers. */
+            drops: number;
+        };
+        /**
+         * Santé ORM agrégée du pod (sommes ; `maxEwmaMs` = pire worker). Présent si ≥ 1 worker
+         * a remonté sa sonde ORM, absent sinon.
+         */
+        orm?: IOrmLeanHealth;
+        /** Erreurs Syslog agrégées du pod (sommes). Présent si ≥ 1 worker a remonté ses compteurs. */
+        errors?: IInstanceErrorHealth;
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Jeton realtime — surface MINIMALE de l'identité d'une connexion WebSocket.
+ *
+ * Sous-ensemble STRICT de `@nodefony/security`'s `IToken` (TypeScript structural
+ * typing → toute classe `Token` security l'implémente gratuitement). Le module
+ * `@nodefony/realtime` reste ainsi **pur** (zéro dépendance security runtime
+ * ni type-only), tout en exposant un contrat partageable.
+ *
+ * Posé par un {@link IRealtimeAuthenticator} au handshake WS et cacheable côté
+ * `RealtimeHub` via la map `peer → token` — les hot-paths (`beforeDispatch`,
+ * `onFrameAudit`) le lisent en O(1) sans recalculer l'auth par frame.
+ *
+ * Zero Trust : un visiteur non authentifié reçoit toujours un token (Anonymous,
+ * `isAuthenticated() === false`), jamais `null`.
+ *
+ * @see IRealtimeAuthenticator
+ */
+export interface IRealtimeToken {
+    /** Type du token (`"anonymous"`, `"jwt"`, `"apikey"`, …) — discriminator stable. */
+    readonly type: string;
+    /** Identifiant logique de l'utilisateur (`"anonymous"`, `"user-42"`, …). */
+    getUserIdentifier(): string;
+    /** `true` si l'authentification a réussi (≠ anonyme). */
+    isAuthenticated(): boolean;
+    /** Rôles **plats** (sans hiérarchie résolue) — utilisés par les voters P6. */
+    getRoles(): string[];
+    /**
+     * Scopes accordés (clés API / OAuth) — axe **distinct** des rôles RBAC.
+     * Ex. `["chat:write", "presence:read"]`. `[]` si aucun.
+     */
+    getScopes(): string[];
+    /** Lecture d'un attribut arbitraire (claims JWT, `tenantId`, providerId…). */
+    getAttribute<T = unknown>(key: string): T | undefined;
+    /**
+     * Re-valide l'identité À L'USAGE (Zero Trust) : `true` si le token est encore
+     * légitime, `false` s'il est PÉRIMÉ (session détruite, ou un AUTRE compte s'est
+     * connecté depuis sur la même socket partagée). Optionnel — un token qui porte
+     * sa propre validité (Anonyme, JWT à `exp`) n'en a pas besoin (**absent =
+     * considéré valide**).
+     *
+     * Appelé par le pont `api.request` AVANT toute action data plane : une
+     * WebSocket survit à sa session (le token est figé au handshake), donc une
+     * identité périmée ne doit JAMAIS servir une requête data plane sensible.
+     * Async (peut relire un store de session) ; gardé HORS du hot-path temps réel
+     * (publish/subscribe), payé seulement sur `api.request`.
+     */
+    isValid?(nowMs?: number): boolean | Promise<boolean>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Interfaces publiques de @nodefony/realtime.
+ *
+ * Contrats partagés du module realtime — toutes ces interfaces sont aussi
+ * exportées depuis le barrel racine `@nodefony/realtime` pour DX.
+ *
+ * Sécurité : `IRealtimeToken` / `IRealtimeHandshake` / `IRealtimeAuthenticator`
+ * (+ matcher) sont les 3 contrats du **seam sécurité #2** (P13 Bloc A étape 6) —
+ * `@nodefony/security` (P6) les implémente sans coupler ce module au security.
+ */
+export type { IBackplane, IBackplaneMessage, BackplaneHandler, } from "./IBackplane.js";
+export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./IRealtimeController.js";
+export type { IChannelPolicy } from "./IChannelPolicy.js";
+export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./IRealtimeProbe.js";
+export type { IRealtimeToken } from "./IRealtimeToken.js";
+export type { IRealtimeHandshake } from "./IRealtimeHandshake.js";
+export type { IRealtimeAuthenticator } from "./IRealtimeAuthenticator.js";
+export type { IRealtimeAuthenticatorMatcher, ICompiledRealtimeMatcher, } from "./IRealtimeAuthenticatorMatcher.js";