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

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).
- */
-/**
- * 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`.
+ * 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}.
  */
-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.

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

@@ -0,0 +1,52 @@
+/**
+ * Ordres de contrôle entre serveurs — la LISTE FERMÉE de ce qui circule sur le
+ * canal `PLATFORM_BUS_CHANNELS.control` (ADR-0022 §6 décision 4).
+ *
+ * Un ordre ne fait qu'ENLEVER : terminer un canal, éjecter un compte d'un
+ * canal. Aucun n'admet — seul `allow` fait entrer. Il voyage dans la charge
+ * d'un message ordinaire du bus, donc sous le sceau de l'enveloppe
+ * (`envelope.ts#sealBackplaneEnvelope`), sans champ neuf dans l'enveloppe ni
+ * méthode neuve dans `IBackplane` : un driver tiers le transporte sans le savoir.
+ */
+/** Longueur maximale d'un champ texte d'un ordre (nom de canal, identifiant de compte). */
+export declare const MAX_CONTROL_FIELD_LENGTH = 1024;
+/** Terminer un canal sur chaque serveur : ses membres reçoivent `realtime:closed { reason: "ended" }`. */
+export interface ICloseChannelOrder {
+    /** Discriminant de l'ordre. */
+    readonly op: "close";
+    /** Nom exact du canal. */
+    readonly channel: string;
+}
+/** Éjecter d'un canal, sur chaque serveur, toutes les connexions d'un compte. */
+export interface IEvictUserOrder {
+    /** Discriminant de l'ordre. */
+    readonly op: "evictUser";
+    /** Nom exact du canal. */
+    readonly channel: string;
+    /** Identifiant du compte (`IRealtimeConnection.userId`). */
+    readonly user: string;
+    /**
+     * Génération d'appartenance visée — RÉSERVÉE : aucun exemplaire 10.0 ne
+     * l'émet, et un exemplaire qui ne sait pas s'en servir l'ignore et éjecte
+     * toutes les générations (plus large, jamais moins). Elle portera en 10.x la
+     * parade au rejeu d'une éjection sur un canal durable (ADR-0022 §6 d4, S-rt-48).
+     */
+    readonly generation?: number;
+}
+/** Un ordre de contrôle reconnu. */
+export type ControlOrder = ICloseChannelOrder | IEvictUserOrder;
+/**
+ * Lit un ordre de contrôle dans une charge venue du bus — `null` si la forme n'est pas celle d'un ordre connu.
+ *
+ * Une seule garde pour les deux bords : l'émetteur la passe avant de publier
+ * (il n'émet jamais ce que ses pairs refuseraient), le récepteur avant
+ * d'appliquer. Lecture par champs PROPRES (`ownField`) : une charge dont le
+ * prototype porterait `op` ne passe pas. Un champ inconnu est toléré — c'est
+ * ce qui laisse une version suivante ajouter un champ sans faire refuser ses
+ * ordres pendant un déploiement progressif ; un champ CONNU de forme fausse
+ * fait refuser l'ordre entier.
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ * @returns l'ordre, ou `null`.
+ */
+export declare function readControlOrder(payload: unknown): ControlOrder | null;

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

@@ -1,3 +1,4 @@
+import { type IFrameCodec } from "nodefony";
 import type { IBackplaneMessage } from "../../interfaces/IBackplane.js";
 /**
  * Sérialise un message backplane, scellé si un secret est fourni.
@@ -25,3 +26,36 @@ export declare function sealBackplaneEnvelope(msg: IBackplaneMessage, secret?: s
  *   scellé alors qu'un secret est exigé, sceau invalide).
  */
 export declare function openBackplaneEnvelope(raw: string, secret?: string | null): IBackplaneMessage | null;
+/**
+ * Encode un message backplane pour le **sujet binaire** du bus (ADR-0021 S6) :
+ * la MÊME enveloppe `{ channel, payload, originId }`, encodée par le codec
+ * binaire du serveur, octets natifs dans `payload`, scellée si un secret est
+ * fourni.
+ *
+ * Scellée, la charge est encodée deux fois — une pour le sceau, une dans
+ * l'enveloppe : le codec générique ne permet pas d'assembler l'enveloppe à
+ * partir de fragments déjà encodés, comme le fait la voie texte.
+ *
+ * @param msg - message à transporter (canal, charge, origine).
+ * @param codec - le codec binaire du serveur (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+ * @param secret - secret partagé entre pods ; `null`/`undefined` → enveloppe nue.
+ * @returns les octets à publier sur le sujet binaire.
+ * @throws TypeError si le codec rend du texte.
+ */
+export declare function sealBackplaneEnvelopeBytes(msg: IBackplaneMessage, codec: IFrameCodec, secret?: string | null): Uint8Array;
+/**
+ * Décode et **vérifie** une enveloppe reçue sur le sujet binaire du bus — même
+ * règle que {@link openBackplaneEnvelope} : fail-closed strict sous un secret,
+ * aucun downgrade en retirant `sig`.
+ *
+ * Le sceau se recalcule sur le RÉ-ENCODAGE de la charge décodée, comme la voie
+ * texte le fait sur sa re-sérialisation : le codec CBOR du cœur rend la forme la
+ * plus courte de chaque valeur, donc émetteur et récepteur signent les mêmes
+ * octets.
+ *
+ * @param raw - octets lus sur le sujet binaire.
+ * @param codec - le codec binaire du serveur.
+ * @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
+ * @returns le message vérifié, ou `null` s'il doit être ignoré.
+ */
+export declare function openBackplaneEnvelopeBytes(raw: Uint8Array, codec: IFrameCodec, secret?: string | null): IBackplaneMessage | null;

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

@@ -1,4 +1,14 @@
+import type { ISubscriberIdentity } from "nodefony";
 import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Identité d'admission de l'ANONYME — gelée et partagée par toutes les connexions non authentifiées (0 allocation par connexion).
+ *
+ * Porte l'invariant de l'ADR-0021 §S10 : anonyme ⇔ `authenticated === false`,
+ * `id === null` et `issuer === null`. Un canal qui déclare `allow` refuse
+ * cette identité d'office, sauf option explicite `anonymous: true` — ce qui
+ * garantit que `user:${who.id}` ne vaut jamais `"user:null"`.
+ */
+export declare const ANONYMOUS_SUBSCRIBER_IDENTITY: ISubscriberIdentity;
 /**
  * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
  * `IRealtimeAuthenticatorMatcher` ne capture le handshake.

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

@@ -0,0 +1,138 @@
+import type { ContractActionNames, ContractClientEmit, ContractServerActions, ContractServerEmit, ContractServerListen, ContractServerMethods, EventNames, IRealtimeContract, TypedRpcActionHandler } from "nodefony";
+import { RealtimeController } from "./RealtimeController.js";
+/**
+ * Clé de l'étiquette de type qui relie une classe à son contrat. Déclaration
+ * ambiante : aucun symbole n'existe à l'exécution, seul le compilateur la voit.
+ */
+declare const contractType: unique symbol;
+/**
+ * Table COMPLÈTE des méthodes que le serveur doit au contrat : une entrée par nom
+ * de `serverMethods`, chacune recevant ses paramètres lus par `Jsonify` et rendant
+ * le résultat déclaré. Une méthode oubliée, un nom hors contrat ou une forme
+ * fausse ne compilent pas.
+ */
+export type ContractRealtimeMethodHandlers<C extends IRealtimeContract> = {
+    [K in ContractActionNames<ContractServerMethods<C>>]: TypedRpcActionHandler<ContractServerMethods<C>, K>;
+};
+/**
+ * Noms qu'un contrat déclare et qu'une politique peut garder : ses méthodes
+ * serveur et les canaux de ses deux directions. Un canal déclaré par gabarit
+ * (`user:${string}`) admet aussi son motif (`user:*`). Direction non déclarée :
+ * tout nom.
+ */
+export type ContractPolicyNames<C extends IRealtimeContract> = ContractActionNames<ContractServerMethods<C>> | EventNames<ContractServerEmit<C>> | EventNames<ContractClientEmit<C>>;
+/**
+ * Le contrat qu'une classe de contrôleur implémente, lu sur son étiquette de
+ * type ; `never` pour un contrôleur sans contrat.
+ */
+export type RealtimeContractOf<T> = T extends abstract new (...args: never[]) => {
+    readonly [contractType]?: infer C;
+} ? unknown extends C ? never : C extends IRealtimeContract ? C : never : never;
+/**
+ * Socle commun des deux formes de {@link ContractRealtimeController} : l'étiquette
+ * de contrat et les canaux annoncés. Les actions y gardent le défaut de la base
+ * (`{}`) — un contrat SANS `serverMethods` n'a rien à écrire.
+ *
+ * Ne s'étend pas directement : on étend {@link ContractRealtimeController}, qui
+ * choisit cette forme ou la forme stricte selon le contrat.
+ *
+ * @typeParam C - le contrat de l'application.
+ */
+export declare abstract class ContractRealtimeControllerBase<C extends IRealtimeContract> extends RealtimeController<ContractServerEmit<C>, ContractServerActions<C>, ContractServerListen<C>> {
+    /**
+     * Étiquette de TYPE : relie la classe à son contrat pour que `@RealtimePolicy`
+     * le retrouve. `declare` — aucun champ n'existe à l'exécution.
+     */
+    readonly [contractType]?: C;
+    /** Canaux annoncés au handshake, contraints aux noms de `serverToClient`. */
+    protected realtimeChannels(): EventNames<ContractServerEmit<C>>[];
+}
+/**
+ * Forme stricte de {@link ContractRealtimeController}, retenue quand le contrat
+ * déclare des `serverMethods` : `realtimeActions()` y devient ABSTRAITE et typée
+ * par le contrat — la seule construction qui fait d'une méthode OUBLIÉE une
+ * erreur de compilation (un décorateur ne voit jamais la classe entière).
+ *
+ * Ne s'étend pas directement : on étend {@link ContractRealtimeController}.
+ *
+ * @typeParam C - le contrat de l'application.
+ */
+export declare abstract class ContractRealtimeControllerStrict<C extends IRealtimeContract> extends ContractRealtimeControllerBase<C> {
+    /**
+     * Les méthodes du contrat servies par ce contrôleur — toutes, et par cette
+     * table SEULE : une action servie ici ne se décore pas en plus de
+     * `@RealtimeAction` (handler fabriqué puis écrasé à chaque connexion). Sa
+     * politique se pose sur la classe, par `@RealtimePolicy`.
+     *
+     * Appelée à chaque connexion. Des handlers qui n'ont pas besoin de `this` se
+     * rangent dans une table CONSTANTE du module, rendue telle quelle : aucune
+     * allocation par connexion.
+     */
+    protected abstract realtimeActions(): ContractRealtimeMethodHandlers<C>;
+}
+/**
+ * Vrai quand le contrat `C` ne déclare aucune méthode serveur. Le tuple empêche
+ * la distribution du conditionnel sur `never`.
+ */
+type HasNoServerMethods<C extends IRealtimeContract> = [
+    ContractActionNames<ContractServerMethods<C>>
+] extends [never] ? true : false;
+/**
+ * L'instance d'un contrôleur de contrat : forme stricte si `C` déclare des
+ * `serverMethods`, socle sinon.
+ *
+ * @typeParam C - le contrat de l'application.
+ */
+export type ContractRealtimeController<C extends IRealtimeContract> = HasNoServerMethods<C> extends true ? ContractRealtimeControllerBase<C> : ContractRealtimeControllerStrict<C>;
+/**
+ * Le constructeur de {@link ContractRealtimeController} : celui de la forme
+ * stricte, dont l'instance se lit par le contrat. Les statiques (`scope`,
+ * `assertScope`) restent ceux de la classe.
+ */
+type ContractRealtimeControllerConstructor = Omit<typeof ContractRealtimeControllerStrict, "prototype"> & (abstract new <C extends IRealtimeContract>(...args: ConstructorParameters<typeof RealtimeController>) => ContractRealtimeController<C>);
+/**
+ * Base d'un contrôleur qui IMPLÉMENTE un contrat temps réel — la porte du
+ * serveur. Le contrat s'écrit UNE fois, sur `extends` ; la direction du serveur
+ * en est dérivée (il émet `serverToClient`, écoute `clientToServer`, appelle
+ * `clientMethods`) et il DOIT servir chaque méthode de `serverMethods`.
+ *
+ * Quand le contrat déclare des `serverMethods`, `realtimeActions()` est
+ * abstraite et typée par lui : une méthode OUBLIÉE ne compile pas. Un contrat
+ * SANS `serverMethods` (tableau de bord, chat qui ne fait que diffuser) n'a rien
+ * à écrire. Les entrées client (`realtimeInbound()`) restent facultatives canal
+ * par canal : accepter une entrée est une permission, pas une promesse. Les
+ * politiques d'accès se posent sur la classe par `@RealtimePolicy`, qui lit le
+ * contrat sur cette classe.
+ *
+ * Le fichier du contrat, fait de types seuls, est partagé avec le navigateur, qui
+ * entre par `NodefonySocket.fromContract<C>()`.
+ *
+ * Un contrat qui déclare des `serverRoutes` (routes du pont, typées côté client
+ * par le schéma que la route valide) se double d'une table statique de VALEURS,
+ * `static readonly serverRoutes = { … } satisfies ContractRouteSchemas<C>` : le
+ * compilateur y exige chaque route du contrat avec son schéma, et le démarrage
+ * vérifie que chacune est montée, servie par la socket et valide LE MÊME schéma
+ * (`BootConfigurationError` sinon). Sans cette table, aucun contrôle.
+ *
+ * @typeParam C - le contrat de l'application.
+ *
+ * @example
+ * ```ts
+ * @RealtimePolicy({ "chat:send": { roles: ["ROLE_USER"] } })
+ * class ChatRt extends ContractRealtimeController<ChatContract> {
+ *   protected realtimeActions() {
+ *     return { "chat:send": (p: { text: string }) => ({ id: this.store(p.text) }) };
+ *   }
+ * }
+ *
+ * class DashRt extends ContractRealtimeController<DashContract> {} // sans serverMethods
+ *
+ * class ChatRoutesRt extends ContractRealtimeController<ChatContract> {
+ *   static readonly serverRoutes = {
+ *     "POST /chat/send": { body: SendBody }, // le schéma de la route, pas une copie
+ *   } satisfies ContractRouteSchemas<ChatContract>;
+ * }
+ * ```
+ */
+export declare const ContractRealtimeController: ContractRealtimeControllerConstructor;
+export {};

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

@@ -0,0 +1,17 @@
+import type { RealtimeClosedReason } from "nodefony";
+/**
+ * Ce que la poignée d'une connexion demande au contrôleur qui la sert — imposer
+ * un abonnement, y mettre fin. Implémenté par `RealtimeController`, une fois par
+ * connexion.
+ */
+export interface IRealtimeConnectionHost {
+    /** Lance l'abonnement imposé à `channel` ; le verdict passe par {@link RealtimeConnection.settleImposed}. */
+    impose(channel: string): void;
+    /**
+     * Met fin à l'abonnement de cette connexion à `channel` (hub ET état de la
+     * connexion) et le lui notifie (`realtime:closed`).
+     *
+     * @returns `false` si la connexion n'est pas abonnée à ce canal.
+     */
+    end(channel: string, reason: RealtimeClosedReason): boolean;
+}

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

@@ -1,8 +1,8 @@
-import { type RpcActionHandler, type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
+import { type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ActionNames, type ActionParams, type ActionResult } from "nodefony";
 import type { ContextType } from "@nodefony/http";
 import { Controller } from "@nodefony/framework";
 import type { ControllerScope } from "@nodefony/framework";
-import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } from "../../interfaces/IRealtimeController.js";
+import type { IRealtimeController, RealtimePublish, RealtimeInboundHandlers, RealtimeActionHandler } from "../../interfaces/IRealtimeController.js";
 /**
  * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
  *
@@ -25,7 +25,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * créé au 1ᵉʳ abonné, `dispose()` au dernier (`unsubscribe` ou `onFinish`). Le dispatch
  * d'action n'est payé que sur une requête `id`. C'est aussi le seam du backplane Redis.
  */
-export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> extends Controller implements IRealtimeController {
+export declare abstract class RealtimeController<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap, Listen extends EventsMap = DefaultEventsMap> extends Controller implements IRealtimeController {
     #private;
     /**
      * Une instance PAR CONNEXION, par construction — le défaut `singleton` des
@@ -72,7 +72,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     createRealtimeChannel(_channel: string, _publish: RealtimePublish): (() => void) | null;
     /** Actions RPC exposées (requête→réponse). À surcharger ; défaut : aucune. */
-    protected realtimeActions(): Record<string, RpcActionHandler>;
+    protected realtimeActions(): Record<string, RealtimeActionHandler>;
     /** Canaux annoncés au handshake. À surcharger ; défaut : aucun. */
     protected realtimeChannels(): string[];
     /**
@@ -88,13 +88,16 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * surcharger ; défaut : **aucun** (sûr — un client ne peut rien pousser au serveur
      * tant qu'un canal n'est pas explicitement déclaré ici). Seam des backings entrants
      * (SIP, bridge). Cf {@link RealtimeInboundHandler} (params NON FIABLES).
+     *
+     * Typée par `Listen` (ce que le client émet, 3ᵉ générique) : un canal hors de
+     * la carte ne compile pas, et chaque handler reçoit la forme de SON canal.
      */
-    protected realtimeInbound(): Record<string, RealtimeInboundHandler>;
+    protected realtimeInbound(): RealtimeInboundHandlers<Listen, Emit>;
     /**
-     * Opt-in du **pont API** (« API souveraine », POC Ph.3) : `true` → la
+     * Opt-in du **pont API** (une action, deux transports) : `true` → la
      * connexion expose la méthode RPC `api.request {path}` qui re-route le path
      * porté par le message vers l'action controller correspondante — la MÊME
-     * action que le GET REST (`socket.request("/nodefony/kernel/api/modules")`
+     * action que le GET REST (`socket.get("/nodefony/kernel/api/modules")`
      * côté client). Le pont n'atteint QUE les routes déclarant le transport
      * `WEBSOCKET` dans leurs `methods` (zéro bypass : une action dit à quels
      * transports elle répond). À surcharger ; défaut : `false` — aucune surface
@@ -120,7 +123,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
      * écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
      */
-    protected handleRealtime(message: string | Buffer | null): void;
+    protected handleRealtime(message: string | Uint8Array | null): void;
     /**
      * Lit les trames BINAIRES de cette connexion — le point d'extension d'un
      * protocole binaire écrit par l'application, à côté du JSON-RPC ; pendant
@@ -128,7 +131,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      *
      * Le protocole temps réel est du JSON-RPC texte : il ne sait pas à quel canal
      * une trame binaire appartient. Sans cette méthode, une trame binaire est
-     * écartée, comptée (`binaryDiscarded` de la sonde de connexion) et journalisée
+     * écartée, comptée (`binaryDiscardedTotal` de la sonde du hub) et journalisée
      * une fois par connexion. La surcharger la reçoit telle quelle, octets exacts,
      * en `Uint8Array` — le type que livre aussi `NodefonySocket.onBinary` dans le
      * navigateur : un décodeur s'écrit une fois pour les deux côtés. À l'exécution
@@ -140,6 +143,10 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * et le pare-feu. L'identité se lit par `RequestContext.getAuthenticatedUser()`,
      * et toute décision d'accès sur une trame binaire appartient à l'application.
      *
+     * ⚠️ Connexions TEXTE seulement : une connexion qui a négocié un codec binaire
+     * (configuration `codec: "cbor"`) lit toute trame binaire comme une frame du
+     * codec, et cette méthode n'y est jamais appelée (ADR-0022 §2).
+     *
      * ⚠️ Un `DataView` se construit sur `data.buffer` AVEC `data.byteOffset` et
      * `data.byteLength` : un `Buffer` issu du pool de Node ne commence pas à 0.
      *
@@ -183,10 +190,20 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * client. Même contre-pression que les frames JSON-RPC.
      *
      * @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
-     * @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
-     *   la trame jetée par la contre-pression.
+     * Sur une connexion qui a négocié un codec BINAIRE, refusé (ADR-0022 §2) : le
+     * client y lirait ces octets comme une frame du codec. Des octets passent
+     * alors par un canal, avec ses portes.
+     *
+     * @returns `false` si le handshake n'est pas terminé, la connexion fermée, la
+     *   trame jetée par la contre-pression, ou la connexion en codec binaire.
      */
     protected sendBinaryToClient(data: Uint8Array): boolean;
+    /**
+     * Journalise, une fois par connexion, le flux brut refusé sous codec binaire.
+     *
+     * @param state - l'état de la connexion.
+     */
+    private noticeRawBinaryUnderCodec;
     /**
      * État realtime de CETTE connexion, `undefined` avant le welcome — pour les
      * chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
@@ -207,6 +224,8 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * Échecs (close WebSocket, codes plage applicative RFC 6455 §7.4.2) :
      *  - Origin refusée    → code 4003 (`forbidden`).
      *  - `authenticate` throw → code 4001 (`unauthorized`).
+     *  - `authenticate` sans réponse dans `authenticateTimeoutMs` → code 1013
+     *    (`try again later`, ADR-0021 §S11) : le client recule puis revient.
      */
     private onHandshake;
     /**
@@ -222,8 +241,69 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * par connexion).
      */
     private acknowledgeSubscription;
-    /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
+    /**
+     * Poignée publique de la connexion, créée au premier besoin (abonnement, trame entrante) puis gardée sur son état.
+     *
+     * Cold path : une fois par connexion. Les deux fermetures la relient à CE
+     * contrôleur, dont les fabriques servent ses canaux.
+     */
+    private connectionOf;
+    /**
+     * Abonnement imposé par le serveur (`RealtimeHub.subscribeConnection`) — la politique fixe par le verrou des trames, puis le chemin d'un `subscribe` du client, `allow` compris (ADR-0022 §6 décision 2).
+     *
+     * Le verdict est rendu à l'appelant par `RealtimeConnection.settleImposed` :
+     * à l'acquittement ({@link acknowledgeSubscription}) ou au refus
+     * ({@link refuseChannel}) — qui n'envoie alors rien au client, qui n'a rien
+     * demandé.
+     */
+    private imposeChannel;
+    /**
+     * Met fin à l'abonnement de la connexion à un canal, sur décision du serveur, et le lui notifie (`realtime:closed`).
+     *
+     * Même chemin que l'`unsubscribe` du client (hub ET état de la connexion),
+     * jamais un second : retirer le seul sink du hub laisserait l'entrée de la
+     * connexion, et le `subscribe` suivant serait acquitté sans rien rouvrir.
+     * Retire aussi la marque « admise » et le verdict retenu de ce canal.
+     *
+     * @returns `false` si la connexion n'est pas abonnée à ce canal.
+     */
+    private endChannel;
+    /**
+     * Retire la connexion d'un canal : hub, état de la connexion, admission de sa règle — le chemin UNIQUE d'une sortie, demandée par le client ou décidée par le serveur.
+     *
+     * @returns `false` si la connexion n'était pas abonnée.
+     */
+    private leaveChannel;
+    /**
+     * Refus d'un abonnement : rendu à l'appelant serveur s'il s'agit d'une imposition, au client sinon — et aux deux quand le client avait aussi demandé ce canal.
+     */
+    private refuseChannel;
+    /**
+     * Abonne la connexion à un canal via le hub partagé (idempotent par connexion).
+     *
+     * Un canal dont la politique déclare `allow` passe d'abord par la file
+     * d'admission de la connexion ; tout autre canal s'ouvre tout de suite, sans
+     * rien lire de plus qu'aujourd'hui (une recherche de politique au `subscribe`,
+     * trame de contrôle rare).
+     */
     private startChannel;
+    /**
+     * Soumet l'abonnement à la règle `allow` du canal — APRÈS le verrou des trames, qui a déjà jugé `authenticated`/`roles`/`scopes` (ADR-0022 §6, décision 1 ter, moment 2).
+     *
+     * `allow` s'applique même sans module de sécurité : il ne fait que retirer
+     * des abonnés, jamais en ajouter — l'ignorer ouvrirait `user:<id>` à tous.
+     * La file de la connexion n'est créée qu'à son premier canal à `allow`.
+     */
+    private admitChannel;
+    /**
+     * Rend un refus d'abonnement observable (`realtime:denied`) — le détail ne part qu'hors production.
+     *
+     * @param detail - phrase pour le développeur ; `undefined` quand l'appelant
+     *   ne l'a pas rédigée (production).
+     */
+    private denyChannel;
+    /** Ouvre l'abonnement au hub et l'acquitte — canal sans `allow`, ou admis par sa règle. */
+    private openChannel;
     /**
      * Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
      * (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
@@ -245,7 +325,7 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      */
     private actionParamsWrapper;
     /**
-     * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
+     * Handler de la méthode RPC `api.request {path}` — le **pont socket**
      * (POC Ph.3) : résout le path porté par le message via le Router
      * (`cleanPathOverride` — l'URL de la connexion n'est jamais mutée) puis
      * exécute l'action SANS la rendre (`executeAction`) : la valeur nue est