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

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

@@ -25,22 +25,9 @@
  *
  * 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;
-}
+import type { IFrameCodec } from "nodefony";
+import type { IBackplaneInfo, IBackplaneQueueInfo } from "nodefony";
+export type { IBackplaneInfo, IBackplaneQueueInfo };
 /**
  * Message transporté entre pairs par le backplane. Sérialisé une fois à l'émission
  * (IPC `structuredClone` / Redis JSON) ; le `payload` doit donc être structurellement
@@ -60,44 +47,28 @@ export interface IBackplaneMessage {
  * 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é.
+ *
+ * Exigences d'un driver (ADR-0022 §6, décision 4) — aucune ne se voit à la
+ * compilation, toutes se perdent en silence :
+ *
+ *  - **chaque pair reçoit TOUT** : sur un journal partitionné, un groupe de lecteurs
+ *    PAR pair — un groupe partagé répartirait les messages entre serveurs ;
+ *  - **l'ordre par émetteur** est tenu : clé de partition = `originId`, jamais le
+ *    canal (ADR-0021 S5) ;
+ *  - **aucun rejeu au démarrage** : lire à partir du dernier message, jamais depuis le
+ *    début — un ordre de fin rejoué couperait une partie rouverte ;
+ *  - **aucune attente de regroupement** à l'émission : `publish` part tout de suite ;
+ *  - **le sceau appliqué** dès que le bus quitte la machine (`crossPod`) :
+ *    `sealBackplaneEnvelope` à l'émission, `openBackplaneEnvelope` à la réception ;
+ *  - `start` après `stop` remet la réception en route sans doubler les messages ;
+ *  - la dépendance npm du transport vit dans le driver, jamais au cœur.
+ *
+ * Un driver s'y prouve par la suite de conformité, la même que jouent les drivers
+ * livrés : `runBackplaneConformance` de `@nodefony/realtime/testing`.
  */
 export interface IBackplane {
     /** Identité stable de CE pair (process/pod). Discrimine l'echo. Ex. `String(process.pid)`. */
@@ -117,6 +88,19 @@ export interface IBackplane {
      * Un seul handler à la fois — un appel ultérieur remplace le précédent.
      */
     onMessage(handler: BackplaneHandler): void;
+    /**
+     * Arme le transport des **octets** (ADR-0021 S6) : après un `true`, une charge qui
+     * est ou contient un `Uint8Array` traverse {@link publish} intacte jusqu'aux autres
+     * pairs. Appelé par le hub, une fois, quand le serveur a un codec binaire.
+     *
+     * Optionnel : un driver qui ne l'implémente pas — ou qui rend `false` — garde ses
+     * messages texte inchangés, et le hub retient les octets sur ce serveur en
+     * prévenant l'exploitant une fois, plutôt que de les laisser se déformer.
+     *
+     * @param codec - le codec binaire du serveur (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+     * @returns `true` si les octets traverseront le bus intacts.
+     */
+    enableBytes?(codec: IFrameCodec): boolean;
     /** Arrête le transport et libère les ressources (connexions, listeners). Idempotent. */
     stop(): void | Promise<void>;
     /**

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

@@ -1,28 +1,8 @@
 /**
- * Politique d'autorisation d'un **canal** WebSocket — exigences à satisfaire
- * pour s'y abonner (`subscribe`) ou y pousser (canal inbound full-duplex).
+ * Politique d'autorisation d'un canal — déclaration UNIQUE, au cœur (`nodefony`).
  *
- * 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 »).
+ * Réexportée ici pour que `import type { IChannelPolicy } from "@nodefony/realtime"`
+ * continue de compiler. Elle n'est plus recopiée : `@nodefony/security`, qui la
+ * juge, lit la même déclaration — deux copies dérivaient en silence.
  */
-export interface IChannelPolicy {
-    /** Exige une connexion authentifiée (token non anonyme). */
-    readonly authenticated?: boolean | undefined;
-    /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté security). */
-    readonly roles?: readonly string[] | undefined;
-    /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
-    readonly scopes?: readonly string[] | undefined;
-}
-export default IChannelPolicy;
+export type { IChannelPolicy, IChannelPolicy as default } from "nodefony";

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

@@ -0,0 +1,22 @@
+/**
+ * Une connexion temps réel servie par CE processus — la poignée qu'un
+ * gestionnaire `@RealtimeInbound` reçoit, et que les gestes du hub sur les
+ * membres d'un canal désignent (`RealtimeHub.subscribeConnection`,
+ * `RealtimeHub.evictConnection`, `RealtimeHub.channelMembers`).
+ *
+ * Elle n'existe que dans la mémoire du processus qui a accepté la socket : elle
+ * ne traverse pas le backplane, et un autre exemplaire (pod, `nodefony cluster
+ * -w N`) ne la connaît pas. Une poignée fermée, ou venue d'ailleurs, fait rendre
+ * `false` aux gestes du hub — jamais un geste muet.
+ */
+export interface IRealtimeConnection {
+    /**
+     * Identifiant du compte connecté (`RealtimeIdentity.id`) — la clé des canaux
+     * personnels et de `RealtimeHub.evictUser`, qui l'atteint sur tous les
+     * exemplaires ; `null` pour l'anonyme (qu'aucun ordre par compte n'atteint),
+     * et pour un authentificateur qui ne produit pas d'identité d'admission.
+     */
+    readonly userId: string | null;
+    /** `false` une fois la socket fermée : la poignée ne désigne plus rien. */
+    readonly open: boolean;
+}

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;
 }