@nodefony/realtime 10.0.0-alpha.1

package/dist/types/nodefony/src/backplane/ClusterBackplane.d.ts

@@ -0,0 +1,76 @@
+import type { IBackplane, BackplaneHandler, IBackplaneMessage, IBackplaneInfo } from "../../interfaces/IBackplane.js";
+import { CLUSTER_RT_KIND } from "nodefony";
+/**
+ * Enveloppe IPC d'une publication realtime = {@link IBackplaneMessage} + discriminant.
+ * Sérialisée une fois par `process.send`/`worker.send` (`structuredClone` IPC) → le
+ * `payload` doit rester structurellement clonable (cf contrat IBackplane).
+ */
+export interface ClusterBackplaneEnvelope extends IBackplaneMessage {
+    readonly kind: typeof CLUSTER_RT_KIND;
+}
+/**
+ * Transport IPC du backplane cluster — abstrait `process.send` / la réception des
+ * messages relayés par le master, derrière un seam **injectable** (même pattern que
+ * `IClusterRuntime` côté ClusterManager). Permet de prouver le routage + l'anti-echo
+ * **sans forker** de process réel.
+ */
+export interface IClusterBackplaneTransport {
+    /**
+     * Émet une enveloppe vers le master (worker → master). No-op silencieux si le
+     * canal IPC est absent (process hors cluster) — le backplane reste sûr.
+     */
+    send(env: ClusterBackplaneEnvelope): void;
+    /**
+     * Enregistre le récepteur des messages IPC venus du master (master → worker).
+     * Reçoit `unknown` (canal partagé) : le tri du `kind` est fait par le backplane.
+     * Appelé une seule fois, au `start()`.
+     */
+    onReceive(cb: (msg: unknown) => void): void;
+}
+/**
+ * Transport de production : `process.send` (émission) + `process.on("message")`
+ * (réception). Standalone — utilisable tel quel. En vrai câblage cluster (Phase 3c),
+ * un transport branché sur l'event kernel `onMessage` (déjà alimenté par
+ * `Kernel.initCluster`) est préféré pour éviter un 2ᵉ listener + le log par message.
+ */
+export declare const processIpcTransport: IClusterBackplaneTransport;
+/**
+ * Backplane **IPC cross-process** (Phase 3) — implémentation worker-side du port
+ * {@link IBackplane} dans un cluster Node natif, où les workers ne se parlent qu'à
+ * travers le **master-gateway** (un worker ne peut envoyer qu'au master via IPC).
+ *
+ * Flux d'une publication cross-process :
+ *  - {@link publish} → emballe `{kind,channel,payload,originId}` → `transport.send`
+ *    (worker → master) ; le master rebroadcast aux **autres** workers (cf `ClusterRelay`,
+ *    Phase 3b) ; le fan-out **local** a déjà été fait par le hub avant cet appel ;
+ *  - réception (master → worker) → {@link onMessage} handler → le hub réinjecte en
+ *    fan-out **local uniquement** (`publishLocal`), jamais re-publié (anti-boucle).
+ *
+ * Anti-echo (2ᵉ barrière du contrat) : à la réception, on **filtre son propre
+ * `originId`** — même si le master renvoyait à la source, le worker l'ignore.
+ *
+ * Perf : hors mono-process (où le hub garde `#backplane === null` → ce code ne tourne
+ * jamais). En cluster, `publish` alloue 1 enveloppe + 1 sérialisation IPC (coût dominé
+ * par l'IPC, pas par l'alloc) — sur le chemin realtime broadcast (tickers/fan-out),
+ * PAS sur le hot path du request HTTP. SERVEUR uniquement (`process`).
+ */
+export declare class ClusterBackplane implements IBackplane {
+    #private;
+    /** Nom du driver — source unique du littéral (registre + config). */
+    static readonly driver = "cluster";
+    readonly originId: string;
+    constructor(transport?: IClusterBackplaneTransport, originId?: string);
+    /** Branche la réception IPC. Idempotent. */
+    start(): void;
+    /**
+     * Propage une publication locale aux autres pairs via le master. NE refait PAS le
+     * fan-out local (déjà fait par le hub). Sérialisé par le transport IPC.
+     */
+    publish(channel: string, payload: unknown): void;
+    /** Un seul handler d'ingress ; un appel ultérieur remplace le précédent. */
+    onMessage(handler: BackplaneHandler): void;
+    /** Détache le handler. Le listener du transport prod (`process`) survit au process. */
+    stop(): void;
+    describe(): IBackplaneInfo;
+}
+export default ClusterBackplane;

package/dist/types/nodefony/src/backplane/LoopbackBackplane.d.ts

@@ -0,0 +1,29 @@
+import type { IBackplane, BackplaneHandler, IBackplaneInfo } from "../../interfaces/IBackplane.js";
+/**
+ * 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).
+ *
+ * `publish` ne sort rien (pas de pair à qui propager), `onMessage` ne fire jamais
+ * (rien n'arrive de l'extérieur) → 0 fan-out cross-process, le hub se comporte
+ * exactement comme en local pur.
+ *
+ * Rôle : (1) matérialiser le contrat pour les tests (cible de vérification du câblage
+ * du hub) ; (2) câblage explicite « backplane présent mais inactif ». NB perf : en
+ * mono-process le {@link RealtimeHub} garde `#backplane === null` (0 overhead réel,
+ * style lazy du fichier) — ce Loopback n'est donc PAS sur le hot path par défaut, il
+ * sert à prouver que brancher un backplane ne change rien tant qu'il n'y a pas de pair.
+ *
+ * SERVEUR uniquement (`process.pid`) — pas isomorphe.
+ */
+export declare class LoopbackBackplane implements IBackplane {
+    /** Nom du driver — source unique du littéral (registre + config). */
+    static readonly driver = "loopback";
+    readonly originId: string;
+    constructor(originId?: string);
+    start(): void;
+    publish(_channel: string, _payload: unknown): void;
+    onMessage(_handler: BackplaneHandler): void;
+    stop(): void;
+    describe(): IBackplaneInfo;
+}
+export default LoopbackBackplane;

package/dist/types/nodefony/src/backplane/RedisBackplane.d.ts

@@ -0,0 +1,164 @@
+import type { IBackplane, BackplaneHandler, IBackplaneInfo } from "../../interfaces/IBackplane.js";
+import { type BackplaneNotice } from "./publishQueue.js";
+/**
+ * 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,
+ * comme le `channel` IPC du {@link ClusterBackplane}) → 1 `SUBSCRIBE` au boot, pas
+ * de (dés)abonnement Redis dynamique par canal applicatif.
+ *
+ * ⚠️ Le `database` Redis ne cloisonne PAS le pub/sub (global au serveur) → sur un
+ * Redis mutualisé, deux apps sur le même canal se parlent (cross-talk). Le canal
+ * effectif est donc suffixé par un namespace via {@link resolveRedisChannel}
+ * (config `backplane.namespace`, sinon dérivé de `kernel.projectName` au wiring).
+ */
+export declare const REDIS_RT_CHANNEL = "nodefony:realtime";
+/**
+ * Construit le canal pub/sub effectif : `nodefony:realtime:<namespace>`, ou la
+ * base seule si aucun namespace n'est résolu (compat mono-app). Deux déploiements
+ * de la MÊME app sur un Redis partagé (staging + prod) ont le même nom dérivé →
+ * y poser un `backplane.namespace` EXPLICITE distinct.
+ *
+ * @param namespace - cloison logique (config `backplane.namespace` ou nom d'app).
+ * @returns le nom du canal Redis à `SUBSCRIBE`/`PUBLISH`.
+ */
+export declare function resolveRedisChannel(namespace?: string): string;
+/**
+ * Transport pub/sub du backplane Redis — abstrait `PUBLISH` / `SUBSCRIBE` derrière
+ * un seam **injectable** (même pattern que `IClusterBackplaneTransport`). Permet de
+ * prouver le routage + l'anti-echo **sans Redis** (bus en mémoire dans les tests),
+ * et de ne PAS coupler `@nodefony/realtime` à la lib `redis` ni au module
+ * `@nodefony/redis` (cf {@link createRedisServiceTransport}, le seul point couplé).
+ */
+export interface IRedisBackplaneTransport {
+    /**
+     * Publie un message sérialisé sur le canal Redis.
+     *
+     * Rendre la promesse du client (plutôt que `void`) permet au backplane de savoir
+     * QUAND la publication est acquittée, donc de **borner** ce qui est en vol : sans
+     * ce signal, la file interne du client réseau grossit sans limite sous rafale (cf
+     * {@link BackplanePublishQueue}). Un transport synchrone (bus mémoire de test) rend
+     * `void` — il n'a pas de file, la borne reste alors inerte.
+     */
+    publish(channel: string, message: string): void | Promise<unknown>;
+    /**
+     * Abonne au canal Redis. Le listener reçoit le message brut (string) ; le tri
+     * (parse + anti-echo) est fait par le backplane. Async (Redis) ou sync (fake).
+     */
+    subscribe(channel: string, onMessage: (message: string) => void): void | Promise<void>;
+    /** Désabonne du canal Redis et libère le listener associé. Idempotent. */
+    unsubscribe(channel: string): void | Promise<void>;
+}
+/**
+ * Client Redis **publisher** — surface structurelle minimale (compatible
+ * `RedisClientType` v5). Typage structurel volontaire : évite d'ajouter `redis`
+ * en dépendance de `@nodefony/realtime`.
+ */
+export interface IRedisPublisher {
+    publish(channel: string, message: string): unknown;
+}
+/**
+ * Client Redis **subscriber** dédié — surface structurelle minimale (compatible
+ * `RedisClientType` v5). Un client abonné ne peut plus émettre de commandes
+ * normales (protocole Redis) → publisher et subscriber sont 2 connexions distinctes
+ * (cf `@nodefony/redis` : connexions `publish` / `subscribe`).
+ */
+export interface IRedisSubscriber {
+    subscribe(channel: string, listener: (message: string, channel: string) => unknown): unknown;
+    unsubscribe(channel: string, listener?: (message: string, channel: string) => unknown): unknown;
+}
+/**
+ * Adapte deux clients Redis (publisher + subscriber dédié) au seam
+ * {@link IRedisBackplaneTransport}. SEUL point de contact avec la lib `redis` —
+ * et même ici le couplage est **structurel** (aucun import). Le consommateur
+ * branche typiquement les connexions du module `@nodefony/redis` :
+ *
+ * ```ts
+ * const redis = kernel.get("redis"); // RedisService
+ * const bp = new RedisBackplane(
+ *   createRedisServiceTransport(redis.getClient("publish")!, redis.getClient("subscribe")!),
+ * );
+ * defineRealtimeConfig({ backplane: { driver: "redis" } }, { backplane: bp });
+ * ```
+ *
+ * Le listener Redis est conservé pour un `unsubscribe(channel, listener)` ciblé
+ * (n'arrache pas d'éventuels autres abonnés du même client).
+ */
+export declare function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber): IRedisBackplaneTransport;
+/**
+ * Réglages optionnels du driver — regroupés en objet pour ne pas allonger une
+ * liste de paramètres positionnels déjà à quatre entrées.
+ */
+export interface IRedisBackplaneOptions {
+    /**
+     * Seuil d'octets publiés en attente d'acquittement au-delà duquel les
+     * publications sont jetées ; `0` = illimité (opt-out explicite). Défaut :
+     * {@link DEFAULT_MAX_QUEUE_BYTES}.
+     */
+    maxQueueBytes?: number;
+    /**
+     * Annonce des transitions de la file (saturation / retour à la normale) — le
+     * wiring y branche le syslog du module. Omis = silencieux : acceptable en test,
+     * jamais en production (une dégradation doit être annoncée).
+     */
+    onNotice?: BackplaneNotice;
+}
+/**
+ * Backplane **Redis pub/sub** (P13.5) — implémentation du port {@link IBackplane}
+ * pour le fan-out realtime **cross-pod** (multi-host), là où le {@link ClusterBackplane}
+ * ne couvrait que les workers d'un même pod (IPC). **Drop-in** : le hub ne change pas,
+ * seul le driver branché change.
+ *
+ * Flux d'une publication cross-pod :
+ *  - {@link publish} → emballe `{channel,payload,originId}` → `PUBLISH nodefony:realtime`
+ *    (le fan-out **local** a déjà été fait par le hub avant cet appel) ;
+ *  - réception (`SUBSCRIBE`) → {@link onMessage} handler → le hub réinjecte en
+ *    fan-out **local uniquement** (`publishLocal`), jamais re-publié (anti-boucle).
+ *
+ * Anti-echo (2ᵉ barrière du contrat) : Redis renvoie au pod émetteur ce qu'il
+ * publie (publisher + subscriber sont 2 connexions du même pod) → on **filtre son
+ * propre `originId`** à la réception, sinon double fan-out local.
+ *
+ * Authenticité (F83) : Redis pub/sub n'authentifie PAS l'émetteur d'un message —
+ * quiconque écrit dans ce Redis (autre app d'un Redis mutualisé, credential fuité,
+ * SSRF vers le port) publierait sur les canaux de tous les pods. Avec un `secret`
+ * partagé, l'enveloppe est **scellée** (HMAC, cf `envelope.ts`) et l'ingress devient
+ * fail-closed strict : non scellé ou mal scellé = ignoré, sans downgrade possible.
+ * Sans secret le transport reste ouvert (compat) — le wiring alerte alors au boot.
+ *
+ * Livraison : **best-effort / at-most-once** — pub/sub Redis ne persiste ni ne
+ * rejoue ; un pod déconnecté rate les messages émis pendant sa coupure (le client
+ * realtime re-synchronise). Ne pas sur-concevoir une fiabilité que le backing
+ * n'offre pas (cf contrat {@link IBackplane}).
+ *
+ * Perf : hors mono-process (où le hub garde `#backplane === null`). `publish`
+ * alloue 1 enveloppe + 1 `JSON.stringify` — sur le chemin broadcast realtime
+ * (tickers/fan-out), PAS sur le hot path HTTP. SERVEUR uniquement (`process.pid`).
+ */
+export declare class RedisBackplane implements IBackplane {
+    #private;
+    /** Nom du driver — source unique du littéral (registre + config). */
+    static readonly driver = "redis";
+    readonly originId: string;
+    constructor(transport: IRedisBackplaneTransport, originId?: string, redisChannel?: string, secret?: string | null, options?: IRedisBackplaneOptions);
+    /**
+     * Abonne au canal Redis dédié. Idempotent (le flag est posé avant l'`await` →
+     * un 2ᵉ appel concurrent ne ré-abonne pas).
+     */
+    start(): Promise<void>;
+    /**
+     * Propage une publication locale aux autres pods via Redis. NE refait PAS le
+     * fan-out local (déjà fait par le hub). Sérialisé une fois ici.
+     *
+     * L'envoi passe par la **file bornée** : si le bus n'acquitte plus, les
+     * publications suivantes sont jetées et comptées plutôt que d'empiler des
+     * mégaoctets dans le client Redis (sémantique at-most-once déjà assumée par le
+     * port ; le client realtime re-synchronise).
+     */
+    publish(channel: string, payload: unknown): void;
+    /** Un seul handler d'ingress ; un appel ultérieur remplace le précédent. */
+    onMessage(handler: BackplaneHandler): void;
+    /** Désabonne du canal Redis et détache le handler. Idempotent. */
+    stop(): Promise<void>;
+    describe(): IBackplaneInfo;
+}
+export default RedisBackplane;

package/dist/types/nodefony/src/backplane/backplaneRegistry.d.ts

@@ -0,0 +1,51 @@
+import type { Module } from "nodefony";
+import type { IBackplane } from "../../interfaces/IBackplane.js";
+import type { IRealtimeConfig } from "../../config/defineModuleConfig.js";
+/**
+ * Registre de **drivers backplane** — résout `config.backplane.driver` (une
+ * chaîne) vers une fabrique d'`IBackplane`, SANS que le code de wiring connaisse
+ * le moindre nom de driver en dur.
+ *
+ * Pourquoi : `IBackplane` est pluggable par contrat. Sélectionner le driver avec
+ * une chaîne de `if (driver === "redis") … else if (driver === "kafka") …` dans
+ * le Module trahit cette promesse (couplage aux noms, fermé à l'extension). Le
+ * registre rend la sélection **ouverte** : les drivers natifs s'enregistrent au
+ * chargement du module, et un utilisateur peut enregistrer le sien
+ * (`registerBackplaneDriver("nats", …)`) puis poser `driver: "nats"` en config —
+ * aucun changement dans le cœur. Single source of truth de la résolution driver.
+ */
+/**
+ * Contexte passé à une fabrique de backplane : tout ce dont un driver peut avoir
+ * besoin pour se construire (accès kernel/container/log via le Module, identité
+ * du pair, rôle dans la topologie, config validée). Une fabrique ne démarre PAS
+ * le backplane (`start()` est appelé par le wiring) — elle le **construit** ou
+ * renvoie `null` (driver inactif dans ce contexte, ex. loopback / cluster hors
+ * worker → le hub reste local).
+ */
+export interface IBackplaneFactoryContext {
+    /** Module realtime — accès `container`/`kernel`/`log`. */
+    readonly module: Module;
+    /** Identité stable de ce pair (process/pod). Ex. `String(process.pid)`. */
+    readonly originId: string;
+    /** Rôle du process dans la topologie de lancement. */
+    readonly role: "MASTER" | "WORKER" | "MONO";
+    /** Config realtime validée + gelée. */
+    readonly config: IRealtimeConfig;
+}
+/**
+ * Fabrique d'un backplane pour un driver donné. Retourne l'instance à brancher,
+ * ou `null` si le driver est inactif dans ce contexte (mono-process, mauvais
+ * rôle, infra absente — le wiring laisse alors le hub local). Peut être async
+ * (ex. lecture d'un service dont l'init est asynchrone).
+ */
+export type BackplaneFactory = (ctx: IBackplaneFactoryContext) => IBackplane | null | Promise<IBackplane | null>;
+/**
+ * Enregistre (ou remplace) la fabrique d'un driver backplane. Appelé par les
+ * drivers natifs au chargement du module, et par l'utilisateur pour ses drivers
+ * custom (NATS, Pulsar, RabbitMQ…).
+ */
+export declare function registerBackplaneDriver(name: string, factory: BackplaneFactory): void;
+/** Fabrique d'un driver par nom, ou `undefined` si inconnu. */
+export declare function getBackplaneDriver(name: string): BackplaneFactory | undefined;
+/** Noms des drivers enregistrés (introspection / Studio / tests). */
+export declare function listBackplaneDrivers(): string[];

package/dist/types/nodefony/src/backplane/envelope.d.ts

@@ -0,0 +1,27 @@
+import type { IBackplaneMessage } from "../../interfaces/IBackplane.js";
+/**
+ * Sérialise un message backplane, scellé si un secret est fourni.
+ *
+ * L'enveloppe scellée est assemblée par concaténation des fragments déjà
+ * sérialisés — un `JSON.stringify` d'objet complet re-sérialiserait la charge
+ * une seconde fois.
+ *
+ * @param msg - message à transporter (canal, charge, origine).
+ * @param secret - secret partagé entre pods ; `null`/`undefined` → enveloppe nue.
+ * @returns la chaîne à publier sur le bus.
+ */
+export declare function sealBackplaneEnvelope(msg: IBackplaneMessage, secret?: string | null): string;
+/**
+ * Parse et **vérifie** une enveloppe reçue du bus partagé.
+ *
+ * Fail-closed strict quand un secret est posé : une enveloppe sans sceau ou au
+ * sceau invalide est rejetée — **aucun downgrade** possible en retirant le champ
+ * `sig`. Sans secret, l'enveloppe nue est acceptée (compat ; l'alerte de boot qui
+ * signale ce mode non authentifié est portée par le wiring du driver).
+ *
+ * @param raw - message brut lu sur le bus.
+ * @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
+ * @returns le message vérifié, ou `null` s'il doit être ignoré (malformé, non
+ *   scellé alors qu'un secret est exigé, sceau invalide).
+ */
+export declare function openBackplaneEnvelope(raw: string, secret?: string | null): IBackplaneMessage | null;

package/dist/types/nodefony/src/backplane/originId.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Résout l'identifiant d'origine d'un backplane — l'étiquette que l'anti-écho
+ * compare pour jeter les messages qui reviennent à leur émetteur.
+ *
+ * POURQUOI pas `String(process.pid)` (ex-défaut) : en conteneur, le namespace
+ * PID est PAR conteneur → deux pods k8s peuvent tous deux être PID 1. Avec un
+ * backplane cross-pod (Redis/Kafka), l'anti-écho confond alors les pods et
+ * jette SILENCIEUSEMENT le fan-out légitime (dette 🔴 #2 du module).
+ *
+ * Résolution (du plus explicite au filet) :
+ *  1. `NF_POD_NAME` (downward API k8s, opt-in opérateur) ;
+ *  2. `os.hostname()` — en k8s = nom du pod (unique), en docker = id court du
+ *     conteneur (unique), en bare-metal = nom de machine ;
+ *  3. suffixe `:pid` TOUJOURS ajouté : distingue les workers d'un même host
+ *     (cluster bare-metal `-w N` + driver redis = même hostname, pids ≠) ;
+ *  4. hostname indisponible/vide (exotique) → `randomUUID()` (l'anti-écho n'a
+ *     pas besoin de stabilité entre restarts, seulement d'unicité à l'instant t).
+ *
+ * Évalué à la CONSTRUCTION du backplane (boot) — 0 coût par message.
+ */
+export declare function resolveBackplaneOriginId(): string;
+export default resolveBackplaneOriginId;

package/dist/types/nodefony/src/backplane/publishQueue.d.ts

@@ -0,0 +1,71 @@
+/**
+ * **File d'envoi bornée d'un backplane** — protège la mémoire du pod quand le bus
+ * n'absorbe pas le débit publié. Mutualisée ici (comme le sceau d'enveloppe) pour
+ * qu'un driver à transport réseau — Redis, et tout driver userland : NATS, Kafka,
+ * RabbitMQ — hérite de la garantie sans la réécrire.
+ *
+ * Pourquoi : `IBackplane.publish` est **fire-and-forget** par contrat (il rend
+ * `void`). Un client réseau met alors la commande dans SA file tant que la socket
+ * n'est pas drainée — file interne, invisible, sans limite. Une rafale y accumule
+ * des mégaoctets : 583 MB observés sur le banc multi-pods, pour 152 MB au repos.
+ * Aucune fuite (tout redescend), mais rien ne borne le pic → OOM sous rafale plus
+ * longue.
+ *
+ * Doctrine — la MÊME que le transport WS (seuil, compteur de jetés, avertissement),
+ * parce que le problème est le même : un pair qui ne draine pas. Deux règles en
+ * découlent :
+ *  - **on protège la mémoire** : au-delà du seuil, les publications suivantes sont
+ *    jetées (sémantique at-most-once déjà assumée par le port — le client realtime
+ *    re-synchronise) ;
+ *  - **on ne jette jamais en silence** : compteurs exposés dans la carte d'identité
+ *    du backplane (donc sonde + Studio) et transitions annoncées.
+ *    Cf `project_resilience_no_silent_degradation`.
+ *
+ * Ce qui est jeté est le message **nouveau**, pas le plus ancien : contrairement au
+ * WS (drop latest-wins sur une file qu'on possède), ce qui est déjà remis au client
+ * réseau ne peut plus être repris.
+ */
+import type { IBackplaneQueueInfo } from "../../interfaces/IBackplane.js";
+/** Sévérité d'une transition de la file — mappée telle quelle sur le syslog. */
+export type BackplaneNoticeSeverity = "WARNING" | "INFO";
+/** Annonce d'une transition (saturation / retour à la normale). */
+export type BackplaneNotice = (message: string, severity: BackplaneNoticeSeverity) => void;
+/**
+ * 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
+ * (3 ms mesurés cross-pod) : 8 MiB d'arriéré, c'est déjà trois ordres de grandeur
+ * au-dessus du régime nominal — le pod a un problème bien avant d'y arriver.
+ */
+export declare const DEFAULT_MAX_QUEUE_BYTES: number;
+/**
+ * File d'envoi bornée : décide d'admettre ou de jeter une publication, puis suit
+ * son acquittement pour rendre la place.
+ *
+ * Un transport **synchrone** (bus mémoire des tests, IPC) ne rend pas de promesse :
+ * il n'a donc pas de file, la garde reste alors inerte et ne jette jamais rien.
+ */
+export declare class BackplanePublishQueue {
+    #private;
+    /**
+     * @param maxBytes - seuil d'octets en vol ; `0` (ou négatif) = illimité.
+     * @param notice - annonce des transitions ; omis = silencieux (tests unitaires).
+     */
+    constructor(maxBytes?: number, notice?: BackplaneNotice | null);
+    /**
+     * Admet ou jette une publication, et suit son acquittement.
+     *
+     * L'admission regarde l'état de la file **avant** l'envoi, pas la taille du
+     * message : une charge plus grosse que le seuil part quand la file est vide
+     * (sinon elle ne partirait jamais — famine silencieuse), quitte à dépasser
+     * transitoirement. Même règle que le drop WS, qui teste `bufferedAmount` seul.
+     *
+     * @param bytes - taille de la charge sérialisée.
+     * @param emit - envoi réel ; appelé UNIQUEMENT si la publication est admise.
+     *   Son retour est suivi s'il s'agit d'une promesse (transport asynchrone).
+     * @returns `true` si la publication est partie, `false` si elle a été jetée.
+     */
+    send(bytes: number, emit: () => unknown): boolean;
+    /** Compteurs pour la carte d'identité du backplane (sonde + Studio). */
+    describe(): IBackplaneQueueInfo;
+}
+export default BackplanePublishQueue;

package/dist/types/nodefony/src/cluster/ClusterProbeClient.d.ts

@@ -0,0 +1,90 @@
+import type { ClusterProbeFacet } from "nodefony";
+import type { IRealtimeHealth, IRealtimeClusterHealth } from "../../interfaces/IRealtimeProbe.js";
+/**
+ * Transport IPC de la sonde cluster côté worker — abstrait `process.send` / la réception
+ * des snapshots du master, derrière un seam **injectable** (même pattern que
+ * `IClusterBackplaneTransport`). Permet de tester le report + le cache **sans forker**.
+ */
+export interface IClusterProbeTransport {
+    /** Émet une remontée de sonde vers le master (worker → master). No-op hors cluster. */
+    send(report: unknown): void;
+    /** Enregistre le récepteur des snapshots agrégés du master (master → worker). */
+    onReceive(cb: (msg: unknown) => void): void;
+}
+/** Transport de production : `process.send` + `process.on("message")`. */
+export declare const processProbeTransport: IClusterProbeTransport;
+/**
+ * Consolide N santés per-instance en une vue **POD** ({@link IRealtimeClusterHealth}).
+ * Pur (aucune I/O) : somme les scalaires ; la backpressure `maxBufferedAmount` est un MAX
+ * (le pire worker), `totalBufferedAmount`/`slowConsumers` des sommes.
+ *
+ * @param instances - santés per-instance (chaque worker, snapshot master).
+ * @param ts - horodatage du snapshot (défaut maintenant).
+ */
+export declare function mergeClusterHealth(instances: IRealtimeHealth[], ts?: number): IRealtimeClusterHealth;
+/**
+ * Client de sonde cluster **côté worker** (Phase 4c) — le pendant de
+ * {@link ClusterProbeAggregator} (master). Deux rôles :
+ *  - **report** : envoie périodiquement sa santé per-instance au master (`CLUSTER_PROBE_KIND`) ;
+ *  - **cache** : reçoit le snapshot agrégé du master (`CLUSTER_PROBE_SNAPSHOT_KIND`) et le garde
+ *    → n'importe quel worker sert la vue POD en O(1) (modèle push : 0 latence de requête).
+ *
+ * **Bypass total quand désactivé** : ce client n'est instancié/`start()` QUE par le module
+ * Framework en worker de cluster AVEC la sonde activée. Sinon (mono-process, ou sonde coupée)
+ * il n'existe pas → aucun timer, aucun listener, aucun IPC, et {@link clusterProbeHealth}
+ * renvoie `null` → l'endpoint santé retombe sur la vue per-instance. Aucun coût « au cas où ».
+ *
+ * Perf : 1 timer `unref` (report) + 1 listener IPC. Le report sérialise 1 santé / intervalle
+ * (≥ 1 s, jamais hot path). SERVEUR uniquement.
+ */
+export declare class ClusterProbeClient {
+    #private;
+    constructor(transport?: IClusterProbeTransport, intervalMs?: number);
+    /**
+     * Démarre le report périodique + l'écoute des snapshots. Idempotent. 1ᵉʳ report immédiat.
+     *
+     * @param buildOwn - fournit la santé per-instance courante (capturée à chaque tick).
+     */
+    start(buildOwn: () => IRealtimeHealth): void;
+    /**
+     * Demande au master d'(arrêter d')enrichir le worker `pid` sur une **facette** (drill-down).
+     * Émis par le worker qui tient la connexion navigateur quand un client subscribe/unsubscribe
+     * le canal `nodefony:supervision@<pid>` (facette `"process"`) ou `nodefony:orm:rich@<pid>` (facette
+     * `"orm"`). No-op hors cluster (`send` no-op).
+     *
+     * @param pid - worker ciblé (identité de la vue pod).
+     * @param enable - `true` = activer la sonde riche sur ce worker, `false` = la couper.
+     * @param facet - quelle sonde riche cibler (défaut `"process"`).
+     */
+    requestEnrich(pid: number, enable: boolean, facet?: ClusterProbeFacet): void;
+    /** Vue POD agrégée, ou `null` tant qu'aucun snapshot n'est reçu (cold start). */
+    getClusterHealth(): IRealtimeClusterHealth | null;
+    /** Arrête le report et purge le cache. Idempotent. Libère la sonde riche (drill). */
+    stop(): void;
+}
+/** Branche le client de sonde cluster du process (worker). Remplace un éventuel précédent. */
+export declare function setClusterProbeClient(client: ClusterProbeClient): ClusterProbeClient;
+/**
+ * Vue POD agrégée si la sonde cluster est branchée ET a reçu un snapshot, sinon `null`.
+ * `null` ⇒ l'endpoint santé sert la vue per-instance (mono-process / sonde désactivée /
+ * cold start). Lecture pure, jamais throw.
+ */
+export declare function clusterProbeHealth(): IRealtimeClusterHealth | null;
+/**
+ * Demande au master d'(arrêter d')enrichir le worker `pid` sur une **facette** (drill-down
+ * Phase 2). Facettes indépendantes : `"process"` (supervision) et `"orm"` (drill ORM).
+ *
+ * @param pid - worker ciblé.
+ * @param enable - activer/couper la sonde riche.
+ * @param facet - quelle sonde riche cibler (défaut `"process"`).
+ * @returns `true` si la sonde cluster est branchée (worker de cluster) → l'ordre est émis ;
+ *   `false` en mono-process / sonde désactivée (pas de drill cross-worker possible → le
+ *   consommateur retombe sur la sonde riche locale du process courant).
+ */
+export declare function clusterProbeRequestEnrich(pid: number, enable: boolean, facet?: ClusterProbeFacet): boolean;
+/**
+ * Santé d'UN worker `pid` extraite du dernier snapshot pod (avec sa sonde riche si le
+ * drill est actif), ou `null` (mono-process, pid inconnu, ou cold start). Lecture pure.
+ */
+export declare function clusterProbeInstance(pid: number): IRealtimeHealth | null;
+export default ClusterProbeClient;

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

@@ -0,0 +1,3 @@
+import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+export declare const ANONYMOUS_REALTIME_TOKEN: IRealtimeToken;
+export default ANONYMOUS_REALTIME_TOKEN;

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

@@ -0,0 +1,18 @@
+import type { IAdminApi } from "nodefony";
+import type { IRealtimeHealth, IRealtimeClusterHealth } from "../../interfaces/IRealtimeProbe.js";
+export declare function buildOwnHealth(): IRealtimeHealth;
+/**
+ * Construit la **santé de la socket** servie par l'endpoint/le canal `nodefony:socket` :
+ * la **vue POD agrégée** si la sonde cluster est branchée et a reçu un snapshot du master
+ * (Phase 4c, push), sinon la **vue per-instance** (mono-process, sonde désactivée, ou cold
+ * start). Lecture pure, jamais throw. Async pour matcher la signature des tickers broker.
+ *
+ * @returns {@link IRealtimeClusterHealth} (cluster) ou {@link IRealtimeHealth} (per-instance).
+ */
+export declare function buildRealtimeHealth(): Promise<IRealtimeHealth | IRealtimeClusterHealth>;
+/**
+ * Construit le producteur `IAdminApi` de la socket (namespace `"realtime"`).
+ *
+ * @returns le contrat admin, prêt à `broker.register()`.
+ */
+export declare function createRealtimeAdminApi(): IAdminApi;