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

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

@@ -0,0 +1,112 @@
+import type { ChannelPresence } from "./channelPresence.js";
+import { RemotePresence } from "./remotePresence.js";
+/** Fenêtre des lots, demandes et réponses entre pods (ms) — ADR-0025 P2. */
+export declare const PRESENCE_BATCH_MS = 50;
+/** Intervalle local de la preuve de vie (ms), annoncé aux pairs — ADR-0025 P2, « Oubli ». */
+export declare const PRESENCE_INTERVAL_MS = 5000;
+/** Délai d'oubli d'un pair muet, en intervalles ANNONCÉS (≥ 2) — ADR-0025 P2. */
+export declare const PRESENCE_FORGET_FACTOR = 3;
+/**
+ * Ce que la présence répartie demande au hub qui la porte — le bus, et les canaux à présence DIFFUSÉS qu'il sert.
+ */
+export interface IPresenceBusHost {
+    /** `originId` de ce pod (celui de son backplane). */
+    readonly originId: string;
+    /** Publie sur le bus (la file d'envoi tranche : la preuve de vie passe hors quota). */
+    publish(channel: string, payload: object): void;
+    /**
+     * Résout un canal reçu : sa présence s'il est servi et diffusé ici, `null` s'il déclare la présence sans être servi, `false` s'il ne la déclare pas (refus compté).
+     */
+    lookup(channel: string): ChannelPresence | null | false;
+    /** Présence d'un canal servi et diffusé ici, `null` sinon. */
+    served(channel: string): ChannelPresence | null;
+    /** Les présences servies et diffusées ici — itérées aux seules transitions. */
+    servedPresences(): Iterable<ChannelPresence>;
+    /** Nombre de présences servies et diffusées ici. */
+    servedCount(): number;
+    /**
+     * Échos de ses propres messages comptés par le pilote (`IBackplaneInfo.echoTotal`), `undefined` s'il n'en expose pas — l'oubli reste alors normal.
+     */
+    echoTotal(): number | undefined;
+}
+/** Réglages de la présence répartie (défauts de l'ADR). */
+export interface IPresenceBusOptions {
+    /** Intervalle de la preuve de vie (ms). */
+    readonly interval?: number;
+    /** Délai d'oubli, en intervalles annoncés (≥ 2). */
+    readonly factor?: number;
+    /** Tirage dans [0, 1) — incarnation et gigue ; injecté par les tests. */
+    readonly random?: () => number;
+    /** Horloge murale (ms) — incarnation seulement ; injectée par les tests. */
+    readonly wallClock?: () => number;
+}
+/**
+ * Présence répartie d'UN pod (ADR-0025 P2) — ce qu'il émet sur le bus (lots de 50 ms, demandes d'état, réponses, preuve de vie) et ce qu'il en reçoit (vue des pairs, {@link RemotePresence}).
+ *
+ * Sans minuteur ni horloge : le hub la fait avancer à son tic UNIQUE
+ * ({@link PresenceBus.tick}) et arme ce tic sur {@link PresenceBus.due}, O(1).
+ * Elle ne parle qu'à `IBackplane` par son hôte : un pilote neuf (Kafka,
+ * NATS…) n'écrit rien pour la présence.
+ *
+ * Coût : rien n'existe tant qu'aucun canal à présence n'est diffusé ; un
+ * changement local = un ajout dans un `Set` ; un lot = un parcours des seuls
+ * canaux changés.
+ */
+export declare class PresenceBus {
+    #private;
+    /** Vue des pairs. */
+    readonly remote: RemotePresence;
+    /** Vie de ce processus : `Date.now() × 1024 + aléa sur 10 bits` (entier sûr jusqu'en 2248). */
+    readonly incarnation: number;
+    /**
+     * @throws RangeError si le délai d'oubli est sous 2 intervalles (cf `RemotePresence`).
+     */
+    constructor(host: IPresenceBusHost, options?: IPresenceBusOptions);
+    /** Prochain instant (ms monotone) où le bus a quelque chose à faire — O(1). */
+    due(): number;
+    /**
+     * Présences à rafraîchir depuis le dernier appel (agrégat changé, état incomplet changé) — `null` si aucune ; le hub les touche.
+     */
+    takeTouched(): Set<ChannelPresence> | null;
+    /**
+     * Un canal à présence diffusé vient d'être servi (premier abonné local) : la vue reste incomplète le temps que la demande d'état groupée soit servie.
+     */
+    served(presence: ChannelPresence, now: number): void;
+    /** La part locale d'une présence a changé : elle part au prochain lot. */
+    changed(presence: ChannelPresence, now: number): void;
+    /**
+     * Applique un message du canal des lots, demandes et réponses.
+     *
+     * @returns `true` si c'est un type de message inconnu de cette version (le
+     *   hub le compte dans `ingressUnknownDiscardedTotal`) ; `false` sinon — y
+     *   compris refusé, compté ici (`presenceRejectedTotal`).
+     */
+    receive(origin: string, payload: unknown, now: number): boolean;
+    /** Applique une preuve de vie ; une forme fausse est refusée et comptée. */
+    receiveAlive(origin: string, payload: unknown, now: number): void;
+    /** Fait avancer la présence répartie à l'instant `now` (tic unique du hub). */
+    tick(now: number): void;
+    /**
+     * Arrêt propre (ADR-0025 P5) : le dernier lot part, puis une preuve de vie FINALE — les pairs retirent aussitôt les présents de ce pod, sans attendre le délai d'oubli. Plus rien ne part ensuite ; idempotent.
+     *
+     * Rien n'est émis si ce pod ne s'est jamais annoncé (aucune preuve de vie
+     * émise ni vue des pairs) : personne n'a rien à retirer.
+     */
+    end(): void;
+    /** Arrêt propre émis ? */
+    get ended(): boolean;
+    /** Bus perdu, constaté par l'écho : la vue est figée et `partial` (instantané). */
+    get busLost(): boolean;
+    /** Pertes du bus constatées par l'écho. */
+    get busLostTotal(): number;
+    /** Réarmements du délai d'oubli (tic en retard, retour de l'écho). */
+    get rearmTotal(): number;
+    /** Compteurs de la sonde. */
+    get batchTotal(): number;
+    /** Demandes d'état émises (ciblées et non ciblées). */
+    get requestTotal(): number;
+    /** Parts de réponse d'état émises. */
+    get answerTotal(): number;
+    /** Preuves de vie émises. */
+    get aliveTotal(): number;
+}

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

@@ -0,0 +1,21 @@
+import type { IBackplane } from "../../interfaces/IBackplane.js";
+import type { RealtimeHub } from "./RealtimeHub.js";
+/**
+ * Délai laissé au bus pour faire partir ce qui est déjà émis à l'arrêt (ms) — sous la limite d'arrêt du noyau (15 s) et sous le délai de grâce d'un orchestrateur.
+ */
+export declare const BACKPLANE_STOP_TIMEOUT_MS = 2000;
+/**
+ * Arrêt propre du temps réel d'un processus — la présence répartie annonce sa fin (dernier lot, puis preuve de vie FINALE, ADR-0025 P5), puis le bus POSSÉDÉ s'arrête en laissant partir ce qui est émis, dans une limite de temps.
+ *
+ * Sans l'attente du bus, la sortie du processus au tick suivant perdait la
+ * preuve de vie finale sur un bus réseau (Redis) : les pairs gardaient ce
+ * serveur jusqu'au délai d'oubli. Un bus fourni par l'application (`owned`
+ * `null`) n'est pas arrêté ici : c'est à elle de le faire.
+ *
+ * @param hub - le hub du processus.
+ * @param owned - le bus que l'appelant a créé et doit arrêter, `null` sinon.
+ * @param timeoutMs - limite de l'arrêt du bus.
+ * @returns `false` si le bus n'a pas fini dans la limite (ou a échoué) — ce
+ *   qui restait peut être perdu, les pairs oublieront ce serveur au délai.
+ */
+export declare function shutdownRealtime(hub: RealtimeHub, owned: IBackplane | null, timeoutMs?: number): Promise<boolean>;

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

@@ -0,0 +1,151 @@
+import { type IPresenceAlive, type IPresenceRequest, type PresenceMessage } from "../backplane/presenceMessage.js";
+/**
+ * Agrégat d'un canal servi par ce pod — ce que la vue distante ajuste quand la présence d'un pair change (ADR-0025 P2).
+ *
+ * Les deux méthodes reçoivent un DELTA : la vue distante range ce que chaque
+ * pod annonce (valeurs absolues) et ne transmet que la différence, si bien que
+ * l'agrégat n'a jamais à reparcourir les pods.
+ */
+export interface IPresenceAggregate {
+    /**
+     * L'identité a `delta` onglets de plus (négatif : de moins) chez les pairs.
+     *
+     * @param key - identité nommée.
+     * @param delta - entier non nul.
+     */
+    remoteTabs(key: string, delta: number): void;
+    /**
+     * Les pairs comptent `delta` connexions non nommées de plus (négatif : de moins).
+     *
+     * @param delta - entier non nul.
+     */
+    remoteUnnamed(delta: number): void;
+    /**
+     * Un pair PART (oublié, arrêt propre, vie remplacée) avec les `tabs` onglets de l'identité qu'il annonçait — retenu par la grâce du canal s'il en déclare une (ADR-0025 P5), annulé si l'identité revient pendant ce délai.
+     *
+     * @param key - identité nommée.
+     * @param tabs - onglets retirés, entier > 0.
+     * @param now - instant monotone local (ms).
+     */
+    remoteLeave(key: string, tabs: number, now: number): void;
+}
+/**
+ * Résout un canal reçu du bus : son agrégat s'il est SERVI ici, `null` s'il déclare la présence sans être servi (lu puis jeté, sans stockage), `false` s'il ne déclare pas la présence sur ce pod (refusé, compté).
+ */
+export type PresenceAggregateLookup = (channel: string) => IPresenceAggregate | null | false;
+/** Réglages de la vue distante. */
+export interface IRemotePresenceOptions {
+    /** Résolution d'un canal reçu (cf {@link PresenceAggregateLookup}). */
+    readonly lookup: PresenceAggregateLookup;
+    /** Délai d'oubli en intervalles ANNONCÉS par le pair (≥ 2, défaut de l'ADR : 3). */
+    readonly factor: number;
+    /**
+     * Intervalle LOCAL (ms) : cadence des demandes répétées pendant un trou, et
+     * intervalle supposé d'un pair dont aucune preuve de vie n'est encore arrivée.
+     */
+    readonly interval: number;
+}
+/**
+ * Vue de la présence des PAIRS, rangée par pod puis par canal (ADR-0025 P2) — la règle répartie, sans horloge, sans minuteur, sans bus.
+ *
+ * Elle applique ce que le bus apporte — lots chaînés par `seq`/`prev`, réponses
+ * d'état en parts appliquées d'un bloc, preuves de vie —, détecte les trous
+ * (règle pure `classifyNumberedChange`, RFC 5263 §4.5), départage les vies d'un
+ * même `originId` par l'incarnation, oublie un pair muet au bout de `factor`
+ * intervalles ANNONCÉS, et ne transmet aux agrégats que des DELTAS. L'instant
+ * (`now`, horloge monotone) est passé à chaque appel : la règle se prouve à
+ * l'horloge simulée, au compte exact.
+ *
+ * Coût : un canal non servi ne stocke rien ; oublier un pod libère ses tables
+ * d'un coup ; un message ne parcourt que ses propres entrées. Aucun parcours de
+ * tous les pods hors de {@link RemotePresence.expire},
+ * {@link RemotePresence.nextDeadline}, {@link RemotePresence.rearm} et
+ * {@link RemotePresence.takeRequests}, appelés au tic.
+ */
+export declare class RemotePresence {
+    #private;
+    /**
+     * @throws RangeError si `factor` < 2 (Phoenix Tracker exige le même plancher :
+     *   sous deux intervalles, une seule preuve de vie retardée fait oublier un pair
+     *   vivant) ou si `interval` n'est pas un entier > 0.
+     */
+    constructor(options: IRemotePresenceOptions);
+    /** Pairs connus (pierres tombales comprises). */
+    get size(): number;
+    /** Pairs dont la vue est en trou — la présence servie est alors `partial`. */
+    get gaps(): number;
+    /** Messages refusés : canal non déclaré à présence ici, plafond dépassé (`presenceRejectedTotal`). */
+    get rejectedTotal(): number;
+    /** Messages déjà vus ou d'une vie plus ancienne (`presenceStaleDiscardedTotal`). */
+    get staleTotal(): number;
+    /** Pairs oubliés faute de signe de vie. */
+    get forgottenTotal(): number;
+    /** Arrêts propres reçus (preuve de vie `final`) — présents retirés sans attendre l'oubli. */
+    get endedTotal(): number;
+    /** Trous ouverts depuis le début (lot perdu, pair inconnu, vie neuve). */
+    get gapTotal(): number;
+    /**
+     * Compte un message de présence REFUSÉ par le lecteur à liste fermée (forme invalide) — même compteur que les refus de la vue.
+     */
+    countRejected(): void;
+    /**
+     * Applique un message du canal des lots, demandes et réponses.
+     *
+     * @param origin - `originId` de l'émetteur, lu dans l'enveloppe.
+     * @param message - message validé par `readPresenceMessage`.
+     * @param now - instant monotone local (ms).
+     * @returns la demande d'état si le message en est une, FRAÎCHE, à servir par
+     *   le répondeur ; `null` sinon.
+     */
+    receive(origin: string, message: PresenceMessage, now: number): IPresenceRequest | null;
+    /**
+     * Applique une preuve de vie.
+     *
+     * @param origin - `originId` de l'émetteur.
+     * @param alive - preuve de vie validée par `readPresenceAlive`.
+     * @param now - instant monotone local (ms).
+     */
+    receiveAlive(origin: string, alive: IPresenceAlive, now: number): void;
+    /**
+     * Pairs à qui demander leur état MAINTENANT — en trou, et pas encore redemandés depuis un intervalle local ; ils sont marqués demandés.
+     *
+     * @param now - instant monotone local (ms).
+     * @param served - canaux à présence servis ici, nommés par la demande ; une
+     *   réponse ne ferme le trou que si elle les couvre tous.
+     * @returns les `originId` à viser (`to`), `null` s'il n'y en a pas.
+     */
+    takeRequests(now: number, served: readonly string[]): string[] | null;
+    /**
+     * Oublie les pairs muets depuis `factor` intervalles ANNONCÉS, et retire les pierres tombales échues.
+     *
+     * @param now - instant monotone local (ms).
+     * @returns le nombre de pairs VIVANTS oubliés (hors pierres tombales).
+     */
+    expire(now: number): number;
+    /**
+     * Plus proche échéance d'oubli APPARUE depuis le dernier appel — celle d'une preuve de vie, dont l'intervalle annoncé peut être plus court que le local ; `Infinity` sinon. O(1), relevée à chaque réception pour que le porteur avance son tic sans attendre le suivant.
+     *
+     * Tout autre message recule l'échéance, et celle d'un pair neuf tombe au
+     * moins deux intervalles LOCAUX plus loin : le tic suivant la relève à temps.
+     * {@link RemotePresence.nextDeadline} reste la valeur exacte, recalculée au tic.
+     */
+    takeCloserDeadline(): number;
+    /** Prochaine échéance d'oubli (ms monotone), `Infinity` sans pair. */
+    nextDeadline(): number;
+    /**
+     * Réarme le délai d'oubli de TOUS les pairs — après un tic en retard (récepteur gelé) ou au retour de l'écho (bus revenu).
+     *
+     * Sans lui, un pod bloqué 20 s oublierait d'un coup tous les pairs vivants
+     * dont les preuves de vie attendent encore dans son tampon : les minuteurs
+     * passent avant la lecture des sockets (Lifeguard).
+     *
+     * @param now - instant monotone local (ms).
+     */
+    rearm(now: number): void;
+    /**
+     * Retire un canal de toutes les vues — il n'est plus servi ici (dernier abonné local parti). L'agrégat n'est pas notifié : il disparaît avec le canal.
+     */
+    dropChannel(channel: string): void;
+    /** Oublie tout, sans notifier les agrégats (arrêt, réinitialisation). */
+    clear(): void;
+}

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

@@ -17,7 +17,17 @@
 /**
  * Sérialise la notification `realtime:subscribed { channel }`.
  *
+ * Connexion TEXTE seulement : sous codec binaire, l'accusé passe par
+ * `peer.notify` (`RealtimeController.ts#RealtimeController.acknowledgeSubscription`).
+ *
  * @param channel - le canal acquitté (entrée réseau : échappé par `JSON.stringify`).
  * @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
  */
 export declare function subscribedAckFrame(channel: string): string;
+/**
+ * Sérialise `realtime:subscribed { channel, imposed: true }` — l'acquittement d'un abonnement imposé par le serveur.
+ *
+ * @param channel - le canal imposé (échappé par `JSON.stringify`).
+ * @returns la trame JSON-RPC 2.0 prête à écrire sur le transport.
+ */
+export declare function imposedSubscribedAckFrame(channel: string): string;

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

@@ -0,0 +1,19 @@
+import type { RealtimeIdentity } from "nodefony";
+import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Vue PUBLIQUE de l'identité d'une connexion, annoncée au client par `realtime:welcome` — tirée de l'identité d'admission quand le jeton en produit une.
+ *
+ * Un objet NEUF, champ par champ, et jamais l'identité d'admission elle-même :
+ * celle-ci porte `issuer` et `account`, qui restent au serveur — la sérialiser
+ * telle quelle les enverrait au client (ADR-0021 §S10 point 1). Les tableaux
+ * de rôles et de scopes, eux, sont repris par RÉFÉRENCE : gelés une fois à la
+ * construction de l'identité, ils ne se recopient pas.
+ *
+ * Un jeton sans `getIdentity` (authentificateur tiers) annonce `id: null` : son
+ * identifiant stable n'est pas connu, et le déduire du login serait le défaut
+ * même que `id` corrige.
+ *
+ * @param token - jeton figé à la poignée de main.
+ * @returns l'identité à placer dans le `welcome`.
+ */
+export declare function welcomeIdentityOf(token: IRealtimeToken): RealtimeIdentity;

package/dist/types/nodefony/src/service/RealtimeService.d.ts

@@ -1,4 +1,4 @@
-import { Service, Module, type JsonRpcPeer } from "nodefony";
+import { Service, Module, type IChannelPolicies, type IFrameCodec, type JsonRpcPeer } from "nodefony";
 import { type RealtimeHub, type ChannelFactory, type ChannelSink, type FrameAuthorizer } from "../server/RealtimeHub.js";
 import type { IBackplane } from "../../interfaces/IBackplane.js";
 import type { IRealtimeProbe } from "../../interfaces/IRealtimeProbe.js";
@@ -58,13 +58,21 @@ declare class RealtimeService extends Service {
     getConfig(): IRealtimeConfig;
     /** Hub singleton (broker fan-out canaux PARTAGÉS du process courant). */
     getHub(): RealtimeHub;
+    /**
+     * Le codec texte des connexions socket, lu PAR NOM par le REST du plan
+     * d'administration (`AdminApiController`, framework ne dépend pas de realtime) :
+     * les octets d'une réponse `GET` y prennent la même forme que sur la socket.
+     */
+    get textFrameCodec(): IFrameCodec;
     /** Backplane actuellement branché sur le hub (ou null = Loopback implicite). */
     getBackplane(): IBackplane | null;
     /**
      * Publie une charge sur un canal — fan-out local + propagation backplane si
      * canal broadcast. Délégué à `RealtimeHub.publish`.
+     *
+     * @throws TypeError si la charge est un scalaire ou `null` (cf `isRealtimePayload`).
      */
-    publish(channel: string, payload: unknown): void;
+    publish(channel: string, payload?: object): void;
     /**
      * Abonne un sink à un canal partagé — factory invoquée au 1ᵉʳ abonné, dispose
      * appelé au dernier désabonné. Délégué à `RealtimeHub.subscribe`.
@@ -155,6 +163,13 @@ declare class RealtimeService extends Service {
      * @returns la politique déclarée, ou `null`.
      */
     resolveChannelPolicy(channel: string): IChannelPolicy | null;
+    /**
+     * **Seam #1b** — lecture ET écriture distincte d'un nom, en une résolution (ADR-0022 §6, décision 1 quater). Lu par `@nodefony/security` sur chaque trame jugée.
+     *
+     * @param channel - nom du canal, de la méthode entrante ou de l'action.
+     * @returns les deux politiques, ou `null` si aucune ne couvre ce nom.
+     */
+    resolveChannelPolicies(channel: string): IChannelPolicies | null;
     /**
      * Renvoie le token associé à un peer (posé au handshake par le hub). Jamais
      * `null` (Zero Trust : `ANONYMOUS_REALTIME_TOKEN` si aucun authenticator n'a

package/dist/types/nodefony/src/service/publicOrigin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Schémas qu'accepte `realtime.publicOrigin` : celui de la socket (`ws:`,
+ * `wss:`) ou celui de l'hôte qui la sert (`http:`, `https:`), ramené au
+ * premier.
+ */
+export declare const REALTIME_ORIGIN_PROTOCOLS: readonly string[];
+/**
+ * Rend la source `connect-src` qui autorise la socket servie à `publicOrigin`,
+ * toujours sous son schéma de socket.
+ *
+ * Une source `wss://hôte` couvre `wss:` ET `https:` du même hôte (CSP Level 3,
+ * « scheme-part match ») ; une source `https://hôte` ne couvrirait PAS la
+ * socket. D'où la conversion `https:` → `wss:`, `http:` → `ws:`.
+ *
+ * @param publicOrigin - origine nue où la socket est servie
+ * @returns la source à déclarer (`wss://rt.example.com:8443`), ou `null` si la
+ *   valeur n'est pas une origine nue d'un schéma accepté
+ */
+export declare function realtimeConnectSource(publicOrigin: string): string | null;

package/dist/types/nodefony/src/transport/WsConnectionTransport.d.ts

@@ -1,4 +1,4 @@
-import { type IRealtimeTransport } from "nodefony";
+import { type IRealtimeTransport, type RealtimeFrameData, type RealtimeOutboundData } from "nodefony";
 import { type WsBackpressurePolicy } from "@nodefony/http";
 import type { IRealtimeConnProbe } from "../../interfaces/IRealtimeProbe.js";
 /**
@@ -16,29 +16,6 @@ export interface RawWsConnection {
      */
     readonly bufferedAmount?: number;
 }
-/**
- * Contre-pression WS — **la règle vit dans `@nodefony/http`**, ce transport ne
- * fait que l'appliquer (`decideSend`). Deux implémentations de la même
- * protection avaient déjà divergé en silence : 4 MiB côté `http`, 1 MiB ici.
- *
- * Réglage = config du serveur WebSocket (`websocket.maxBackpressure`,
- * `.backpressurePolicy`, `.backpressureCloseAfterDrops`) — une seule source pour
- * `send`/`broadcast` HTTP **et** pour le realtime.
- *
- * ⚠️ NE PAS confondre avec `slowConsumer.bytes` (config realtime) : celle-ci ne
- * règle QUE le seuil de COMPTAGE de la sonde, jamais l'action.
- */
-/**
- * WsConnectionTransport — transport {@link IRealtimeTransport} CÔTÉ SERVEUR :
- * wrap d'une connexion `ws` (1 par client connecté). Pendant serveur du
- * `BrowserWsTransport` → la connexion serveur compose le MÊME `JsonRpcPeer` que
- * le client (symétrie isomorphe).
- *
- * Particularité serveur : l'inbound n'est PAS piloté par un event socket mais par
- * le **pipeline framework** (la route WS appelle `feed(raw)` à chaque message) ;
- * la fermeture est signalée par `fireClose()` (hook `onFinish` du Context). Le
- * `connect`/`onOpen` sont des no-op (la connexion est déjà ouverte au handshake).
- */
 export declare class WsConnectionTransport implements IRealtimeTransport, IRealtimeConnProbe {
     private readonly conn;
     private _onMessage;
@@ -57,7 +34,7 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
         closeAfterDrops?: number;
     });
     connect(): void;
-    send(raw: string): void;
+    send(raw: RealtimeOutboundData): void;
     /**
      * Émet des octets tels quels — trame binaire RFC 6455, hors JSON-RPC (#617).
      * Même contre-pression (`decideSend`, la règle unique) et mêmes compteurs que
@@ -73,13 +50,13 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
      * Compte une trame ENTRANTE écartée et rend le cumul de sa nature — `1` dit
      * « première », le seul instant où l'appelant journalise.
      *
-     * @param kind - `binary` (sans lecteur) ou `malformed` (texte non JSON).
+     * @param kind - `binary` (sans lecteur) ou `malformed` (illisible par le codec).
      * @returns le cumul de cette nature, après incrément.
      */
     discard(kind: "binary" | "malformed"): number;
     /** Cumul de trames BINAIRES reçues et écartées faute de lecteur — monotone. */
     get binaryDiscarded(): number;
-    /** Cumul de trames TEXTE reçues et écartées parce que non JSON — monotone. */
+    /** Cumul de trames reçues et écartées parce qu'illisibles par le codec de la connexion — monotone. */
     get malformedDiscarded(): number;
     close(code?: number, reason?: string): void;
     get readyState(): number;
@@ -92,11 +69,20 @@ export declare class WsConnectionTransport implements IRealtimeTransport, IRealt
     /** Cumul de frames jetées par back-pressure (drop + close slow-consumer) — monotone. */
     get dropped(): number;
     onOpen(): void;
-    onMessage(cb: (raw: string) => void): void;
+    onMessage(cb: (raw: RealtimeFrameData) => void): void;
     onClose(cb: (code: number, reason: string) => void): void;
     onError(): void;
-    /** Pump entrant : le pipeline framework pousse ici chaque message reçu. */
-    feed(raw: string): void;
+    /**
+     * Pump entrant : le pipeline framework pousse ici chaque frame reçue — texte,
+     * ou octets d'une connexion qui a négocié un codec binaire (ADR-0022 §2).
+     *
+     * Une vue sur un `SharedArrayBuffer` n'est pas une trame : `ws` livre
+     * toujours un `Buffer` sur un `ArrayBuffer`, le type de Node l'admet
+     * seulement. Elle est comptée comme illisible, jamais transmise au pair.
+     *
+     * @param raw - la trame telle que reçue.
+     */
+    feed(raw: string | Uint8Array): void;
     /** Fermeture : appelée par le owner sur `onFinish` (close WS). */
     fireClose(code?: number, reason?: string): void;
 }

package/dist/types/nodefony/testing/backplaneConformance.d.ts

@@ -0,0 +1,78 @@
+import type { IBackplane } from "../interfaces/IBackplane.js";
+/**
+ * Lanceur de tests de l'appelant — le sous-ensemble que la suite emploie.
+ *
+ * Formes compatibles telles quelles : `{ describe, it }` de vitest, de
+ * `node:test` et de `bun:test`.
+ */
+export interface IConformanceRunner {
+    /** Ouvre un groupe de cas. */
+    describe(name: string, body: () => void): unknown;
+    /** Déclare un cas asynchrone ; un rejet le fait échouer. */
+    it(name: string, body: () => Promise<void>): unknown;
+}
+/**
+ * Réglages de {@link runBackplaneConformance}.
+ */
+export interface IBackplaneConformanceOptions extends IConformanceRunner {
+    /**
+     * Le driver scelle-t-il ses messages (`sealBackplaneEnvelope`) ? Défaut `true`.
+     * `false` n'est admis que pour un driver dont le bus ne quitte pas la machine :
+     * un driver qui se déclare `crossPod` sans sceller fait échouer la suite.
+     */
+    sealed?: boolean;
+    /**
+     * Silence attendu, en millisecondes, avant de conclure qu'un message n'arrivera
+     * PAS (refus, rejeu, écho). Défaut 100 ; à relever pour un bus lent.
+     */
+    quietMs?: number;
+    /** Délai maximal d'arrivée d'un message attendu, en millisecondes. Défaut 2 000. */
+    timeoutMs?: number;
+    /**
+     * Octets publiés d'une traite avant l'ordre du cas « ordre sous saturation ».
+     * Défaut : deux fois le seuil par défaut de la file d'envoi (16 Mio). Un driver
+     * dont la file est bornée plus haut relève cette valeur : si la rafale ne
+     * sature pas la file que `describe().queue` déclare, le cas échoue plutôt que
+     * de passer sans rien prouver.
+     */
+    floodBytes?: number;
+}
+/**
+ * Fabrique d'un pair du driver, relié au MÊME bus que les autres pairs de la suite.
+ *
+ * Appelée plusieurs fois par cas : chaque appel rend un nouveau pair, d'`originId`
+ * propre, non démarré (la suite appelle `start` et `stop`).
+ *
+ * @param secret - secret du sceau, ou `null` pour un bus nu.
+ */
+export type BackplanePeerFactory = (secret: string | null) => IBackplane | Promise<IBackplane>;
+/** Noms des cas — stables : un test négatif les désigne. */
+export declare const BACKPLANE_CONFORMANCE_CASES: {
+    readonly fanout: "diffusion : chaque pair reçoit TOUT, l'émetteur ne reçoit pas son écho";
+    readonly order: "ordre par émetteur : les publications d'un pair arrivent dans l'ordre";
+    readonly noReplay: "pas de rejeu : un pair démarré après une publication ne la reçoit pas";
+    readonly seal: "sceau : un message non scellé ou mal scellé est refusé";
+    readonly control: "ordres de contrôle : le canal de contrôle traverse intact";
+    readonly controlUnderLoad: "ordre sous saturation : un ordre de contrôle n'est jamais jeté pour faire place aux publications";
+    readonly aliveUnderLoad: "preuve de vie sous saturation : la preuve de vie de la présence n'est jamais jetée pour faire place aux publications";
+    readonly reserved: "espace réservé : refusé et compté à l'entrée du hub, la diffusion passe sans revenir";
+    readonly presence: "présence entre deux pods : chaque hub voit les présents de l'autre, l'arrêt propre les retire sans attendre l'oubli, sans doublon ni rejeu";
+    readonly replaceHandler: "onMessage remplace le handler précédent";
+    readonly stop: "stop coupe la réception, et se rappelle sans erreur";
+};
+/**
+ * Déclare la suite de conformité d'un driver de backplane auprès du lanceur de
+ * tests de l'appelant.
+ *
+ * Vérifie, sur plusieurs pairs reliés au même bus : la diffusion à TOUS les pairs
+ * sans écho, l'ordre par émetteur, l'absence de rejeu au démarrage, le sceau
+ * (message non scellé ou mal scellé refusé), le transport des ordres de contrôle,
+ * même quand une rafale de publications sature la file d'envoi, le refus de
+ * l'espace réservé à l'entrée du hub, la présence répartie entre deux hubs
+ * (ADR-0025), le remplacement du handler et l'arrêt.
+ *
+ * @param name - nom du driver, affiché dans le rapport.
+ * @param makePeer - fabrique d'un pair relié au bus commun.
+ * @param options - le lanceur (`describe`, `it`) et les réglages.
+ */
+export declare function runBackplaneConformance(name: string, makePeer: BackplanePeerFactory, options: IBackplaneConformanceOptions): void;

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

@@ -29,9 +29,9 @@
  *
  * @packageDocumentation
  */
-import { type IRealtimeDenied } from "nodefony";
+import { type IChannelAdmission, type IRealtimeDenied } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import type { RealtimeController } from "../src/server/RealtimeController.js";
+import { type RealtimeController } from "../src/server/RealtimeController.js";
 import { type RealtimeHub, type FrameAuthorizer } from "../src/server/RealtimeHub.js";
 import type { IRealtimeToken } from "../interfaces/IRealtimeToken.js";
 /**
@@ -102,6 +102,16 @@ export interface IRealtimeHarnessOptions {
      * ainsi qu'on éprouve un fan-out.
      */
     readonly resetHub?: boolean;
+    /**
+     * Les classes d'admission du controller (`@RealtimeChannel(nom, { allow:
+     * MaClasse })`), déjà construites avec leurs services. En production, le
+     * démarrage les résout dans le conteneur ; le harnais n'a pas de noyau, et
+     * sans elles une politique qui désigne une classe est REFUSÉE à la poignée de
+     * main. Les passer ici les inscrit par le même chemin que le démarrage, gardes
+     * comprises (`@injectable`, singleton, méthode `allow`). Le test construit
+     * ainsi l'admission avec le MÊME service que le controller.
+     */
+    readonly admissions?: readonly IChannelAdmission[];
 }
 /**
  * Vue de test d'un controller temps réel connecté : ce qu'il a reçu, ce qu'il a
@@ -174,3 +184,4 @@ export interface IRealtimeHarness<C extends RealtimeController> {
  * @returns le harnais, prêt pour `connect()`.
  */
 export declare function createRealtimeHarness<C extends RealtimeController>(create: (context: ContextType) => C, options?: IRealtimeHarnessOptions): IRealtimeHarness<C>;
+export { runBackplaneConformance, BACKPLANE_CONFORMANCE_CASES, type BackplanePeerFactory, type IBackplaneConformanceOptions, type IConformanceRunner, } from "./backplaneConformance.js";

package/dist/types/nodefony/testing/presenceClient.d.ts

@@ -0,0 +1,20 @@
+import { PresenceView, type NumberedChangeOutcome, type RealtimePresenceFrame } from "nodefony";
+import type { RealtimeHub } from "../src/server/RealtimeHub.js";
+/** Un client de présence branché sur un hub : ses trames `realtime:presence`, sa vue, et son départ. */
+export interface IPresenceClient {
+    /** Trames reçues, dans l'ordre. */
+    frames: RealtimePresenceFrame[];
+    /** Sort de chaque trame appliquée à {@link view} (même index que {@link frames}). */
+    outcomes: NumberedChangeOutcome[];
+    /**
+     * Vue du canal tenue par la vue PURE du cœur — celle du navigateur (`NodefonySocket`) : ce que le serveur écrit, le navigateur le lit ainsi.
+     */
+    view: PresenceView;
+    leave: () => void;
+}
+/**
+ * Abonne à `channel` une connexion de `hub` — nommée `user`, ou anonyme (`null`) — et relève les trames de présence qu'elle reçoit, lues et appliquées par le lecteur et la vue du cœur, comme le ferait un navigateur. Une trame que le lecteur refuse est un défaut du serveur : le banc lève en la citant.
+ */
+export declare function presenceClient(hub: RealtimeHub, channel: string, user: string | null): IPresenceClient;
+/** Présents nommés d'un canal vus par `hub` (identité → onglets), triés. */
+export declare function presenceView(hub: RealtimeHub, channel: string): Record<string, number>;