@nodefony/realtime 10.0.0-beta.5 → 10.0.0-beta.7

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

@@ -1,6 +1,8 @@
-import type { JsonRpcPeer } from "nodefony";
+import type { IFrameCodec, JsonRpcPeer } from "nodefony";
 import type { WsConnectionTransport } from "../src/transport/WsConnectionTransport.js";
 import type { ChannelSink } from "../src/server/RealtimeHub.js";
+import type { RealtimeConnection } from "../src/server/RealtimeConnection.js";
+import type { ConnectionAdmission } from "../src/server/connectionAdmission.js";
 import type { RealtimeInboundHandler } from "./IRealtimeController.js";
 /**
  * État du protocole temps réel d'UNE connexion WebSocket — posé au welcome, et
@@ -22,10 +24,47 @@ export interface IRealtimeConnectionState {
     peer: JsonRpcPeer;
     /** Le transport qui relie le pair à la socket (contre-pression, sonde). */
     transport: WsConnectionTransport;
+    /**
+     * Le codec BINAIRE accordé à cette connexion au handshake (ADR-0022 §2), `null`
+     * pour une connexion restée en texte. Non nul, toute trame binaire reçue est une
+     * frame du codec, et le flux brut (`onRealtimeBinary`, `sendBinaryToClient`) est
+     * refusé : les octets passent par les canaux, et leurs portes.
+     */
+    binaryCodec: IFrameCodec | null;
     /** Canal → sink de CETTE connexion auprès du hub partagé, pour s'en désabonner. */
     channels: Map<string, ChannelSink>;
-    /** Canaux full-duplex qui acceptent une entrée client ; `null` s'il n'y en a aucun. */
+    /**
+     * Canaux full-duplex qui acceptent une entrée client ; `null` s'il n'y en a aucun.
+     * Objet ordinaire, de même forme pour toutes les connexions d'un contrôleur :
+     * un nom hérité de son prototype (`__proto__`, `toString`) est refusé par le
+     * verrou des trames avant d'atteindre la distribution.
+     */
     inbound: Record<string, RealtimeInboundHandler> | null;
+    /**
+     * File d'admission aux canaux à `allow` — `null` tant que la connexion n'a
+     * demandé aucun de ces canaux (la plupart ne le font jamais).
+     */
+    admission: ConnectionAdmission | null;
+    /**
+     * Canaux entrants dont les trames passent sans le verrou : ouverts par `allow`,
+     * ou dont le verrou a déjà dit oui (ADR-0022 §6, décision 1 ter). Le coût d'une
+     * trame chaude tient dans cette lecture (`admitted[method] === true`). Mêmes
+     * clés que {@link inbound}, à `false` tant que non admises : une seule forme
+     * d'objet pour toutes les connexions d'un contrôleur. `null` jusqu'à la
+     * première admission.
+     */
+    admitted: Record<string, boolean> | null;
+    /**
+     * Ceux de {@link admitted} que le VERROU a admis — au plus 64, vidés quand une
+     * politique arrive après coup. `null` s'il n'y en a aucun.
+     */
+    retained: string[] | null;
+    /**
+     * Poignée publique de la connexion (membre d'un canal, argument des
+     * gestionnaires `@RealtimeInbound`) — `null` jusqu'au premier abonnement ou à
+     * la première trame entrante qui la demande.
+     */
+    connection: RealtimeConnection | null;
 }
 declare module "@nodefony/http" {
     interface IWebsocketConnectionState {

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

@@ -1,5 +1,33 @@
-/** Publie une charge sur un canal (notification serveur→client). */
-export type RealtimePublish = (channel: string, payload: unknown) => void;
+import type { ContractServerEmit, EventNames, EventPayload, EventsMap, IRealtimeContract } from "nodefony";
+import type { IRealtimeConnection } from "./IRealtimeConnection.js";
+/**
+ * Publie une charge sur un canal (notification serveur→client) — forme LIBRE :
+ * tout nom, toute charge objet. Sous un contrat, préférer {@link ContractRealtimePublish}.
+ */
+export type RealtimePublish = (channel: string, payload?: object) => void;
+/**
+ * Publie sur un canal DÉCLARÉ par le contrat `C` : le nom est l'un des canaux de
+ * `serverToClient`, la charge est celle qu'il déclare. Une faute de frappe dans
+ * le nom ou dans la charge ne compile pas.
+ *
+ * C'est le `publish` qu'une fabrique de canal déclare sous un contrat — méthode
+ * `@RealtimeChannel` ou surcharge `createRealtimeChannel`. La fonction reçue à
+ * l'exécution est la même qu'en forme libre ({@link RealtimePublish}) : seul le
+ * compilateur voit la différence. La charge est un objet : le hub refuse un
+ * scalaire à l'exécution (`isRealtimePayload`), le type le dit avant.
+ *
+ * @typeParam C - le contrat de l'application.
+ *
+ * @example
+ * ```ts
+ * @RealtimeChannel("chat:presence", { authenticated: true })
+ * presence(_channel: string, publish: ContractRealtimePublish<ChatContract>) {
+ *   publish("chat:presence", { online: 3 });
+ *   return () => undefined;
+ * }
+ * ```
+ */
+export type ContractRealtimePublish<C extends IRealtimeContract> = <K extends EventNames<ContractServerEmit<C>>>(channel: K, payload: EventPayload<ContractServerEmit<C>, K> & object) => 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
@@ -9,10 +37,43 @@ export type RealtimePublish = (channel: string, payload: unknown) => void;
  *   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).
+ * - `connection` = la connexion émettrice, locale à ce processus : de quoi l'abonner
+ *   d'office à un canal (`RealtimeHub.subscribeConnection`) ou l'en éjecter. Un
+ *   gestionnaire qui n'en a pas l'usage l'omet.
  *
  * 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;
+export type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown) => void, connection: IRealtimeConnection) => void;
+/**
+ * Handler d'entrée TYPÉ par le contrat : `params` est ce que le client a émis sur
+ * ce canal, lu par `Jsonify` ; `reply` pousse la charge que le serveur émet sur le
+ * même canal. Les paramètres restent NON FIABLES : le type n'est pas une validation.
+ *
+ * Écrit en signature de MÉTHODE pour que ses paramètres se comparent de façon
+ * bivariante : c'est ce qui permet à une table typée de remplacer la table
+ * permissive de la base, que le contrôleur lit en `unknown` à l'exécution.
+ */
+export type TypedRealtimeInboundHandler<P, R> = {
+    handle(params: P, reply: (payload: R) => void, connection: IRealtimeConnection): void;
+}["handle"];
+/**
+ * Table des entrées client d'un contrôleur : un handler par canal de `Listen`,
+ * chacun facultatif — accepter une entrée reste un choix explicite, canal par
+ * canal (par défaut, un client ne peut rien pousser). `Listen` non déclaré :
+ * n'importe quel nom, `params: unknown`.
+ */
+export type RealtimeInboundHandlers<Listen extends EventsMap, Emit extends EventsMap> = {
+    [K in EventNames<Listen>]?: TypedRealtimeInboundHandler<EventPayload<Listen, K>, K extends keyof Emit ? Emit[K] : unknown>;
+};
+/**
+ * Handler d'action RPC tel que la table de `realtimeActions()` le range. Signature
+ * de MÉTHODE (paramètre comparé de façon bivariante) : une table typée par le
+ * contrat, dont chaque handler attend sa forme, remplace ainsi la table
+ * permissive de la base.
+ */
+export type RealtimeActionHandler = {
+    handle(params: unknown): unknown;
+}["handle"];
 /**
  * IRealtimeController — contrat d'un contrôleur temps réel SERVEUR (endpoint WS
  * JSON-RPC 2.0). Le protocole (discrimination, dispatch, actions, pending, pub/sub,

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

@@ -13,8 +13,7 @@
  *    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";
+export type { IRealtimeChannelStat, IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, RealtimeHealthReport, } from "nodefony";
 /** Vue d'UNE connexion realtime pour la sonde (backpressure = risque #1). */
 export interface IRealtimeConnProbe {
     /** État du transport (0..3, aligné `WebSocket.readyState`). */
@@ -35,172 +34,14 @@ export interface IRealtimeConnProbe {
      * 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.
+     * Cumul de trames BINAIRES reçues et écartées faute de lecteur (monotone) :
+     * connexion texte sans `onRealtimeBinary`. Absent = la connexion ne compte pas.
      */
-    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;
-    };
+    readonly binaryDiscarded?: 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.
+     * Cumul de trames reçues et écartées parce qu'illisibles par le codec de la
+     * connexion (monotone). Absent = la connexion ne compte pas.
      */
-    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;
-    };
+    readonly malformedDiscarded?: number;
 }

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

@@ -1,3 +1,4 @@
+import type { ISubscriberIdentity, TokenStatus } from "nodefony";
 /**
  * Jeton realtime — surface MINIMALE de l'identité d'une connexion WebSocket.
  *
@@ -45,6 +46,15 @@ export interface IRealtimeToken {
      * (publish/subscribe), payé seulement sur `api.request`.
      */
     isValid?(nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * La CAUSE de l'état de l'identité, quand elle est connaissable : `active`,
+     * `expired` (jeton porteur arrivé à `exp`) ou `revoked` (révoqué l'emporte sur
+     * expiré). Le hub en tire le code de fermeture d'une socket ouverte : `expired` →
+     * `TOKEN_EXPIRED_CLOSE_CODE` (4006), sinon `IDENTITY_DEAD_CLOSE_CODE` (4001) —
+     * ADR-0021 §S11. Optionnel : absent, `isValid` décide et son `false` vaut 4001
+     * (une session ne sait pas dire si elle a expiré ou été détruite).
+     */
+    status?(nowMs?: number): TokenStatus | Promise<TokenStatus>;
     /**
      * Le COMPTE qui a ouvert la socket existe-t-il toujours, actif, et est-ce
      * bien le même ? `false` si le compte a disparu, a été désactivé ou
@@ -58,4 +68,15 @@ export interface IRealtimeToken {
      * qui le paierait pour chaque socket ouverte, à chaque tour.
      */
     confirmAccount?(): Promise<boolean>;
+    /**
+     * Identité d'ADMISSION de la connexion — la donnée plate que reçoit la règle `allow` d'un canal, construite UNE fois et gelée.
+     *
+     * Rend toujours la MÊME référence : elle est lue au `welcome` puis à chaque
+     * admission, jamais recalculée. Optionnelle pour un authentificateur tiers ;
+     * absente, la connexion n'entre sur AUCUN canal qui déclare `allow` (refus
+     * `forbidden` et une ligne de journal) — jamais un `id` déduit de
+     * {@link getUserIdentifier}, qui est un login et se réattribue
+     * (ADR-0021 §S10).
+     */
+    getIdentity?(): ISubscriberIdentity;
 }

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

@@ -9,9 +9,10 @@
  * `@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 { IRealtimeController, RealtimePublish, ContractRealtimePublish, RealtimeInboundHandler, } from "./IRealtimeController.js";
 export type { IChannelPolicy } from "./IChannelPolicy.js";
 export type { IRealtimeConnectionState } from "./IRealtimeConnectionState.js";
+export type { IRealtimeConnection } from "./IRealtimeConnection.js";
 export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./IRealtimeProbe.js";
 export type { IRealtimeToken } from "./IRealtimeToken.js";
 export type { IRealtimeHandshake } from "./IRealtimeHandshake.js";

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

@@ -2,8 +2,11 @@ import type { IBackplane, BackplaneHandler, IBackplaneMessage, IBackplaneInfo }
 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).
+ * Sérialisée une fois par `process.send`/`worker.send`. Le master de Nodefony forke
+ * ses workers en sérialisation `advanced` (clonage structuré,
+ * `src/nodefony/src/service/cluster/clusterMaster.ts#startClusterMaster`) : un
+ * `Uint8Array` y traverse intact, sans codec — l'IPC ne quitte pas la machine, il
+ * n'a ni sceau ni second sujet à porter.
  */
 export interface ClusterBackplaneEnvelope extends IBackplaneMessage {
     readonly kind: typeof CLUSTER_RT_KIND;
@@ -26,6 +29,11 @@ export interface IClusterBackplaneTransport {
      * Appelé une seule fois, au `start()`.
      */
     onReceive(cb: (msg: unknown) => void): void;
+    /**
+     * Le canal porte-t-il un `Uint8Array` intact (sérialisation `advanced`) ?
+     * Optionnel : absent, les octets restent sur ce process.
+     */
+    carriesBytes?(): boolean;
 }
 /**
  * Transport de production : `process.send` (émission) + `process.on("message")`
@@ -60,7 +68,7 @@ export declare class ClusterBackplane implements IBackplane {
     static readonly driver = "cluster";
     readonly originId: string;
     constructor(transport?: IClusterBackplaneTransport, originId?: string);
-    /** Branche la réception IPC. Idempotent. */
+    /** Branche la réception IPC. Idempotent, et redémarrable après {@link stop}. */
     start(): void;
     /**
      * Propage une publication locale aux autres pairs via le master. NE refait PAS le
@@ -69,7 +77,17 @@ export declare class ClusterBackplane implements IBackplane {
     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. */
+    /**
+     * Les octets traversent l'IPC tels quels quand le canal est en clonage
+     * structuré : aucun codec n'est appliqué, l'argument est ignoré.
+     *
+     * @returns `true` si le transport constate un canal `advanced`.
+     */
+    enableBytes(): boolean;
+    /**
+     * Coupe la réception et détache le handler. Le récepteur du transport survit
+     * (`process` ne le retire pas) mais ne livre plus rien jusqu'au prochain {@link start}.
+     */
     stop(): void;
     describe(): IBackplaneInfo;
 }

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

@@ -1,4 +1,5 @@
 import type { IBackplane, BackplaneHandler, IBackplaneInfo } from "../../interfaces/IBackplane.js";
+import { type IFrameCodec } from "nodefony";
 import { type BackplaneNotice } from "./publishQueue.js";
 /**
  * BASE du canal Redis **dédié** transportant les enveloppes realtime entre pods.
@@ -22,6 +23,17 @@ export declare const REDIS_RT_CHANNEL = "nodefony:realtime";
  * @returns le nom du canal Redis à `SUBSCRIBE`/`PUBLISH`.
  */
 export declare function resolveRedisChannel(namespace?: string): string;
+/**
+ * Construit le **sujet binaire** du bus (ADR-0021 S6) : le canal texte suffixé du
+ * protocole du codec. Un second sujet, versionné par son nom, que les exemplaires
+ * plus anciens n'écoutent pas — le message texte n'est pas touché, et un codec
+ * binaire d'un autre format aurait son propre sujet.
+ *
+ * @param redisChannel - le canal texte effectif ({@link resolveRedisChannel}).
+ * @param codec - le codec binaire du serveur.
+ * @returns le nom du canal Redis qui porte les enveloppes binaires.
+ */
+export declare function resolveRedisBytesChannel(redisChannel: string, codec: IFrameCodec): string;
 /**
  * Transport pub/sub du backplane Redis — abstrait `PUBLISH` / `SUBSCRIBE` derrière
  * un seam **injectable** (même pattern que `IClusterBackplaneTransport`). Permet de
@@ -39,12 +51,18 @@ export interface IRedisBackplaneTransport {
      * {@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>;
+    publish(channel: string, message: string | Uint8Array): 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>;
+    /**
+     * Abonne au canal Redis en mode **octets** : le listener reçoit le message tel
+     * que publié, sans décodage UTF-8 (sujet binaire, ADR-0021 S6). Optionnel : un
+     * transport qui ne l'offre pas laisse les octets sur le serveur qui les publie.
+     */
+    subscribeBytes?(channel: string, onMessage: (message: Uint8Array) => void): void | Promise<void>;
     /** Désabonne du canal Redis et libère le listener associé. Idempotent. */
     unsubscribe(channel: string): void | Promise<void>;
 }
@@ -54,18 +72,53 @@ export interface IRedisBackplaneTransport {
  * en dépendance de `@nodefony/realtime`.
  */
 export interface IRedisPublisher {
-    publish(channel: string, message: string): unknown;
+    publish(channel: string, message: string | Buffer): unknown;
 }
+/** Écouteur texte d'un client Redis abonné. */
+type RedisTextListener = (message: string, channel: string) => unknown;
+/** Écouteur octets d'un client Redis abonné (`bufferMode`). */
+type RedisBytesListener = (message: Buffer, channel: Buffer) => 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;
+    subscribe(channel: string, listener: RedisTextListener): unknown;
+    unsubscribe(channel: string, listener?: RedisTextListener): unknown;
 }
+/**
+ * Client Redis abonné en mode **octets** — le troisième argument `true`
+ * (`bufferMode` de node-redis) rend les messages en `Buffer`, sans décodage
+ * UTF-8 : c'est lui qui porte le sujet binaire intact (ADR-0021 S6).
+ *
+ * Interface SÉPARÉE de {@link IRedisSubscriber}, et non une surcharge de
+ * celle-ci : les deux formes réunies dans une même interface ne sont plus
+ * satisfaites ni par le type de node-redis (générique sur le mode), ni par une
+ * doublure de test qui ne connaît que le texte. Séparées, chacune l'est.
+ */
+export interface IRedisBytesSubscriber {
+    subscribe(channel: string, listener: RedisBytesListener, bufferMode: true): unknown;
+    unsubscribe(channel: string, listener: RedisBytesListener, bufferMode: true): unknown;
+}
+/**
+ * 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`.
+ */
+export declare function isRedisPublisher(value: unknown): value is IRedisPublisher;
+/** Vrai si la valeur expose la surface d'un client Redis subscriber dédié. */
+export declare function isRedisSubscriber(value: unknown): value is IRedisSubscriber;
+/**
+ * Vrai si la valeur expose la surface d'un client abonné capable du mode octets.
+ *
+ * La forme ne dit pas si le troisième argument est compris : ce garde vaut pour
+ * le client que rend le service `redis` (node-redis, qui l'accepte). Un client qui
+ * l'ignorerait livrerait du texte au sujet binaire — illisible pour le codec,
+ * donc jeté, compté sous un secret (`sealRejectedTotal`), jamais réinjecté.
+ */
+export declare function isRedisBytesSubscriber(value: unknown): value is IRedisBytesSubscriber;
 /**
  * Adapte deux clients Redis (publisher + subscriber dédié) au seam
  * {@link IRedisBackplaneTransport}. SEUL point de contact avec la lib `redis` —
@@ -80,17 +133,17 @@ export interface IRedisSubscriber {
  * 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).
+ * Chaque listener Redis est conservé, par canal, pour un `unsubscribe(channel,
+ * listener)` ciblé (n'arrache pas d'éventuels autres abonnés du même client).
+ *
+ * @param publisher - connexion de publication.
+ * @param subscriber - connexion d'abonnement dédiée.
+ * @param bytesSubscriber - la MÊME connexion d'abonnement, vue en mode octets
+ *   ({@link IRedisBytesSubscriber}) ; absente, le transport n'offre pas de sujet
+ *   binaire et les octets restent sur le serveur qui les publie.
+ * @returns le transport du {@link RedisBackplane}.
  */
-/**
- * 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`.
- */
-export declare function isRedisPublisher(value: unknown): value is IRedisPublisher;
-/** Vrai si la valeur expose la surface d'un client Redis subscriber dédié. */
-export declare function isRedisSubscriber(value: unknown): value is IRedisSubscriber;
-export declare function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber): IRedisBackplaneTransport;
+export declare function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber, bytesSubscriber?: IRedisBytesSubscriber): 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.
@@ -103,8 +156,8 @@ export interface IRedisBackplaneOptions {
      */
     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,
+     * Annonce des transitions de la file (saturation / retour à la normale) et des
+     * sceaux refusés à l'entrée — 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;
@@ -152,6 +205,16 @@ export declare class RedisBackplane implements IBackplane {
      * un 2ᵉ appel concurrent ne ré-abonne pas).
      */
     start(): Promise<void>;
+    /**
+     * Arme le sujet binaire (ADR-0021 S6) : les charges qui contiennent des octets
+     * partent en enveloppe encodée par `codec` sur un second canal Redis, et ce
+     * canal est écouté. Les charges sans octets gardent le sujet texte, intact pour
+     * les exemplaires plus anciens. Idempotent.
+     *
+     * @param codec - le codec binaire du serveur.
+     * @returns `false` si le transport ne sait pas s'abonner en octets.
+     */
+    enableBytes(codec: IFrameCodec): boolean;
     /**
      * 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.
@@ -159,12 +222,20 @@ export declare class RedisBackplane implements IBackplane {
      * 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).
+     * port ; le client realtime re-synchronise). Un ordre de contrôle, lui, part
+     * toujours (cf {@link BackplanePublishQueue.send}).
      */
     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. */
+    /**
+     * Laisse partir les publications déjà émises (acquittées ou refusées par Redis), puis désabonne du canal et détache le handler. Idempotent.
+     *
+     * Sans l'attente, un arrêt suivi de la sortie du processus perdait ce qui
+     * était encore dans la file — la preuve de vie FINALE de la présence comprise,
+     * et les pairs gardaient alors ce pod jusqu'au délai d'oubli. Un Redis qui ne
+     * répond plus fait attendre : l'appelant borne (l'arrêt du module le fait).
+     */
     stop(): Promise<void>;
     describe(): IBackplaneInfo;
 }