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

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

@@ -0,0 +1,75 @@
+/**
+ * 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;
+/**
+ * Un texte venu du bus est-il recevable — chaîne non vide d'au plus {@link MAX_CONTROL_FIELD_LENGTH} caractères ?
+ *
+ * Seule borne des textes du bus (nom de canal, identifiant de compte), lue par
+ * les ordres de contrôle ET par les messages de présence (ADR-0025 P2).
+ *
+ * @param value - champ reçu (forme inconnue).
+ */
+export declare function isBoundedBusText(value: unknown): value is string;
+/**
+ * La charge est-elle un ordre d'un TYPE que cette version ne connaît pas — `op` lisible, mais hors de la liste fermée ?
+ *
+ * C'est ce qu'émet un serveur d'une version plus récente pendant un
+ * déploiement progressif (ADR-0025, « Règle de lecture du bus ») : l'ordre
+ * n'est pas appliqué, mais il ne se compte pas comme une injection. Rien
+ * d'autre que `op` n'est lu — ses autres champs appartiennent à une version
+ * qui n'est pas celle-ci. Une charge sans `op` textuel, ou d'un type CONNU de
+ * forme fausse, n'est pas « inconnue » : elle est invalide.
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ * @returns `true` si le type d'ordre est inconnu de cette version.
+ */
+export declare function isUnknownControlOrder(payload: unknown): boolean;
+/**
+ * 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.
@@ -19,9 +20,85 @@ export declare function sealBackplaneEnvelope(msg: IBackplaneMessage, secret?: s
  * `sig`. Sans secret, l'enveloppe nue est acceptée (compat ; l'alerte de boot qui
  * signale ce mode non authentifié est portée par le wiring du driver).
  *
+ * Le sceau se vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+ * forme qu'écrit {@link sealBackplaneEnvelope} — aucune re-sérialisation ; une
+ * autre forme retombe sur la re-sérialisation de la charge lue.
+ *
  * @param raw - message brut lu sur le bus.
  * @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
  * @returns le message vérifié, ou `null` s'il doit être ignoré (malformé, non
  *   scellé alors qu'un secret est exigé, sceau invalide).
  */
 export declare function openBackplaneEnvelope(raw: string, secret?: string | null): IBackplaneMessage | null;
+/**
+ * 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 UNE fois : le sceau se calcule sur ses octets,
+ * et l'enveloppe s'assemble autour d'eux. Un codec qui n'écrit pas le CBOR le plus
+ * court (constaté, cf {@link framesAsCbor}) encode l'enveloppe entière une seconde
+ * fois — correct pour tout format, plus coûteux.
+ *
+ * @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 vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+ * forme qu'assemble l'émetteur — aucun ré-encodage ; une autre forme retombe sur
+ * le ré-encodage de la charge décodée (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;
+/**
+ * Reconnaît l'**écho** d'un pod — ce que le bus lui renvoie de ses propres
+ * publications — à la FIN du message, sans le décoder (ADR-0021 S6, ADR-0025).
+ *
+ * Un bus pub/sub comme Redis rend à l'émetteur chacune de ses publications : sur un
+ * pod chargé, c'est un message reçu sur deux, et la présence répartie en fait un
+ * signal (le bus est vivant tant que l'écho revient). Le reconnaître coûte, sous un
+ * secret, UN HMAC sur la tranche de la charge : ni `JSON.parse`, ni décodage CBOR.
+ *
+ * Sous un secret, l'écho est VÉRIFIÉ avant d'être compté : un tiers qui forgerait
+ * l'origine de ce pod pour simuler un bus vivant échoue au sceau. Sans secret, rien
+ * ne peut l'être — le bus est ouvert, et le wiring l'annonce au démarrage.
+ *
+ * Un message que ce lecteur ne reconnaît pas (forme tierce, sceau faux) n'est PAS
+ * jeté : il suit la voie ordinaire, qui le vérifie en entier.
+ */
+export declare class BackplaneEcho {
+    #private;
+    /**
+     * @param originId - identité de CE pod sur le bus.
+     * @param secret - secret partagé, ou `null` sur un bus non scellé.
+     */
+    constructor(originId: string, secret: string | null);
+    /**
+     * Ce message texte est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+     *
+     * @param raw - message brut lu sur le sujet texte.
+     */
+    text(raw: string): boolean;
+    /**
+     * Ce message binaire est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+     *
+     * @param raw - octets lus sur le sujet binaire.
+     * @param codec - le codec binaire du serveur ; un codec qui n'écrit pas le CBOR
+     *   attendu (cf {@link framesAsCbor}) laisse tout message à la voie ordinaire.
+     */
+    bytes(raw: Uint8Array, codec: IFrameCodec): boolean;
+}

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

@@ -0,0 +1,48 @@
+import type { IFrameCodec } from "nodefony";
+import type { IBackplaneMessage } from "../../interfaces/IBackplane.js";
+import type { BackplaneNotice } from "./publishQueue.js";
+/**
+ * **Entrée d'un bus partagé** — le tri de ce qu'un pilote reçoit, mutualisé pour
+ * que tout pilote à transport réseau (Redis aujourd'hui ; Kafka, NATS, RabbitMQ…
+ * demain) l'hérite sans le réécrire : écho de ce pod reconnu et compté, sceau
+ * vérifié, refus comptés et annoncés.
+ *
+ * Le pilote ne garde que son transport : il passe chaque message reçu à
+ * {@link text} ou {@link bytes} et remet au hub ce qui en sort.
+ *
+ * Ordre du tri, du moins cher au plus cher :
+ *  1. l'ÉCHO de ce pod se reconnaît à la fin du message, sans le décoder — un HMAC
+ *     sous un secret (cf {@link BackplaneEcho}) ;
+ *  2. sinon, l'enveloppe est ouverte et son sceau vérifié sur la tranche reçue ;
+ *  3. un message ouvert qui porte l'origine de ce pod sous une autre forme est
+ *     encore un écho — compté, jamais réinjecté (anti-boucle).
+ */
+export declare class BackplaneIngress {
+    #private;
+    /**
+     * @param originId - identité de CE pod sur le bus.
+     * @param secret - secret partagé, ou `null` sur un bus non scellé.
+     * @param notice - annonce des sceaux refusés ; omis = silencieux (tests).
+     */
+    constructor(originId: string, secret: string | null, notice?: BackplaneNotice | null);
+    /**
+     * Trie un message reçu sur le sujet TEXTE du bus.
+     *
+     * @param raw - message brut tel que lu sur le transport.
+     * @returns le message à remettre au hub, ou `null` s'il est jeté (écho de ce
+     *   pod, malformé, sceau refusé — chacun compté).
+     */
+    text(raw: string): IBackplaneMessage | null;
+    /**
+     * Trie un message reçu sur le sujet BINAIRE du bus (ADR-0021 S6).
+     *
+     * @param raw - octets tels que lus sur le transport.
+     * @param codec - le codec binaire du serveur.
+     * @returns le message à remettre au hub, ou `null` s'il est jeté.
+     */
+    bytes(raw: Uint8Array, codec: IFrameCodec): IBackplaneMessage | null;
+    /** Échos de ce pod reçus du bus (monotone) — le bus rend ce qu'on y publie. */
+    get echoTotal(): number;
+    /** Messages jetés au sceau refusé, sous un secret (monotone). */
+    get sealRejectedTotal(): number;
+}

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

@@ -0,0 +1,150 @@
+import type { PresencePairs } from "nodefony";
+/**
+ * Messages de la présence répartie entre serveurs — la LISTE FERMÉE de ce qui
+ * circule sur `PLATFORM_BUS_CHANNELS.presence` (lots, demandes, réponses d'état)
+ * et `PLATFORM_BUS_CHANNELS.presenceAlive` (preuve de vie), ADR-0025 P2.
+ *
+ * Comme un ordre de contrôle (`controlOrder.ts#readControlOrder`), chaque
+ * message voyage dans la charge d'un message ordinaire du bus, sous le sceau de
+ * l'enveloppe : aucun champ neuf dans l'enveloppe, aucune méthode neuve dans
+ * `IBackplane`. L'émetteur (`originId`) se lit dans l'enveloppe, jamais dans la
+ * charge.
+ *
+ * Lecture par champs PROPRES (`ownField`), textes bornés (`isBoundedBusText`),
+ * entiers sûrs ; un champ inconnu est toléré (déploiement progressif), un champ
+ * connu de forme fausse fait refuser le message entier. Les tableaux rendus
+ * sont CEUX reçus, validés en place — aucune copie, aucune allocation par
+ * membre : le lecteur ne les modifie pas, l'appelant non plus.
+ */
+/** Plus petit intervalle de preuve de vie qu'un pair peut annoncer (ms). */
+export declare const MIN_PRESENCE_INTERVAL_MS = 100;
+/** Plus grand intervalle de preuve de vie qu'un pair peut annoncer (ms) — 10 min. */
+export declare const MAX_PRESENCE_INTERVAL_MS = 600000;
+/**
+ * Plafond d'identités nommées qu'un pod peut annoncer pour UN canal — au-delà,
+ * l'entrée est refusée (ADR-0025 P2, « plafond de membres par pod et par canal »).
+ */
+export declare const MAX_PRESENCE_MEMBERS = 100000;
+/** Plafond d'entrées de canal dans un même message (lot, demande ou part de réponse). */
+export declare const MAX_PRESENCE_CHANNELS = 4096;
+/** Plafond de parts d'une réponse d'état (`n`). */
+export declare const MAX_PRESENCE_PARTS = 4096;
+/**
+ * Changements d'un pod sur UN canal, en valeurs ABSOLUES : rejouer une entrée
+ * déjà comprise dans un état ne change rien.
+ */
+export interface IPresenceChannelDelta {
+    /** Nom exact du canal. */
+    readonly channel: string;
+    /** Identités dont le NOMBRE d'onglets sur ce pod change, à plat `[identité, onglets, …]` (onglets ≥ 1) ; `null` si aucune. */
+    readonly set: PresencePairs | null;
+    /** Identités qui n'ont plus aucun onglet sur ce pod ; `null` si aucune. */
+    readonly gone: readonly string[] | null;
+    /** Connexions non nommées de ce pod sur ce canal — valeur absolue. */
+    readonly unnamed: number;
+}
+/** État COMPLET d'un pod sur un canal, dans une réponse d'état. */
+export interface IPresenceChannelState {
+    /** Nom exact du canal. */
+    readonly channel: string;
+    /** Toutes les identités nommées de ce pod, à plat `[identité, onglets, …]` (onglets ≥ 1). */
+    readonly members: PresencePairs;
+    /** Connexions non nommées de ce pod sur ce canal. */
+    readonly unnamed: number;
+}
+/** Lot de changements d'un pod, scellé toutes les 50 ms, chaîné par `prev`. */
+export interface IPresenceBatch {
+    /** Discriminant. */
+    readonly op: "batch";
+    /** Vie du processus émetteur (`Date.now() × 1024 + aléa sur 10 bits`). */
+    readonly incarnation: number;
+    /** Numéro du message, strictement croissant par (`originId`, incarnation), ≥ 1. */
+    readonly seq: number;
+    /** `seq` du lot précédent de l'émetteur, `0` pour le premier ; `< seq`. */
+    readonly prev: number;
+    /** Changements par canal. */
+    readonly channels: readonly IPresenceChannelDelta[];
+}
+/** Demande d'état — le *fetch* de RFC 2778 §2.1, la *presence probe* de RFC 6121 §4.3. */
+export interface IPresenceRequest {
+    /** Discriminant. */
+    readonly op: "request";
+    /** Vie du processus demandeur. */
+    readonly incarnation: number;
+    /** Numéro du message (même suite que les lots du demandeur). */
+    readonly seq: number;
+    /** Canaux dont l'état est demandé. */
+    readonly channels: readonly string[];
+    /**
+     * Pod visé (`originId`) — il répond TOUJOURS, même vide (RFC 6121 §4.3.2) ;
+     * `null` = demande non ciblée, servie par les seuls pods qui ont des présents.
+     */
+    readonly to: string | null;
+}
+/**
+ * Une part d'une réponse d'état. Les `n` parts d'une réponse partent d'un bloc,
+ * à `seq` consécutifs (`seq` de la part `i` = `seq` de la part 0 + `i`), et
+ * s'appliquent d'un bloc : une part perdue laisse la vue inchangée.
+ */
+export interface IPresenceStatePart {
+    /** Discriminant. */
+    readonly op: "state";
+    /** Vie du processus qui répond. */
+    readonly incarnation: number;
+    /** Numéro du message. */
+    readonly seq: number;
+    /** `seq` du dernier lot émis avant la réponse — il ferme le trou (RFC 5263 §4.5) ; `< seq`. */
+    readonly last: number;
+    /** Rang de la part, `0 ≤ i < n`. */
+    readonly i: number;
+    /** Nombre de parts de la réponse, `1 ≤ n ≤ MAX_PRESENCE_PARTS`. */
+    readonly n: number;
+    /** États complets par canal (un canal peut s'étendre sur plusieurs parts). */
+    readonly channels: readonly IPresenceChannelState[];
+}
+/** Message lu sur `PLATFORM_BUS_CHANNELS.presence`. */
+export type PresenceMessage = IPresenceBatch | IPresenceRequest | IPresenceStatePart;
+/** Preuve de vie, lue sur `PLATFORM_BUS_CHANNELS.presenceAlive` — quelques dizaines d'octets, indépendante du nombre de canaux. */
+export interface IPresenceAlive {
+    /** Vie du processus émetteur. */
+    readonly incarnation: number;
+    /** Numéro du message (même suite que les lots). */
+    readonly seq: number;
+    /** `seq` du dernier lot émis, `0` si aucun ; `< seq`. */
+    readonly last: number;
+    /** Intervalle de l'émetteur (ms), ANNONCÉ : il fixe le délai d'oubli chez les pairs (RFC 6665 §3.1.1). */
+    readonly interval: number;
+    /** `true` = arrêt propre : les pairs l'oublient aussitôt (RFC 6121 §4.5.1). */
+    readonly final: boolean;
+}
+/**
+ * Lit un message du canal de présence — `null` si sa forme n'est pas celle d'un message connu.
+ *
+ * Une seule garde pour les deux bords : l'émetteur la passe en test (il n'émet
+ * jamais ce que ses pairs refuseraient), le récepteur avant d'appliquer.
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ * @returns le message, ou `null` (forme invalide, ou type inconnu : cf
+ *   {@link isUnknownPresenceMessage} pour les distinguer).
+ */
+export declare function readPresenceMessage(payload: unknown): PresenceMessage | null;
+/**
+ * La charge est-elle un message de présence d'un TYPE que cette version ne connaît pas — `op` lisible, hors de la liste fermée ?
+ *
+ * C'est ce qu'émet un serveur plus récent pendant un déploiement progressif :
+ * jeté et compté dans `ingressUnknownDiscardedTotal`, jamais comme une
+ * injection (ADR-0025, « Règle de lecture du bus »).
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ */
+export declare function isUnknownPresenceMessage(payload: unknown): boolean;
+/**
+ * Lit une preuve de vie — `null` si sa forme est fausse.
+ *
+ * `interval` hors de [{@link MIN_PRESENCE_INTERVAL_MS}, {@link MAX_PRESENCE_INTERVAL_MS}]
+ * est refusé : un pair qui annoncerait 1 ms se ferait oublier à chaque tic, un
+ * qui annoncerait une heure garderait ses fantômes une demi-journée.
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ */
+export declare function readPresenceAlive(payload: unknown): IPresenceAlive | null;

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

@@ -24,6 +24,18 @@
  * Ce qui est jeté est le message **nouveau**, pas le plus ancien : contrairement au
  * WS (drop latest-wins sur une file qu'on possède), ce qui est déjà remis au client
  * réseau ne peut plus être repris.
+ *
+ * **Les ordres de contrôle ne sont JAMAIS jetés** (#762) : terminer un canal ou
+ * éjecter un compte passe hors quota, même file saturée. Sinon, sous charge, un
+ * modérateur éjecte un compte sur un serveur et ce compte continue de lire sur un
+ * autre, sans que personne le sache. Les ordres sont rares et petits (une décision
+ * du serveur, quelques dizaines d'octets) : les exempter ne rouvre pas la mémoire.
+ * La **preuve de vie** de la présence répartie passe aussi hors quota (ADR-0025
+ * P2) : jetée, elle ferait oublier un pod vivant chez ses pairs ; elle est petite
+ * et d'intervalle borné. Liste des canaux prioritaires : `isPriorityBusChannel`
+ * (cœur), seule source.
+ * Un ordre que le bus REFUSE malgré tout (bus injoignable) est compté à part
+ * (`controlLostTotal`) et annoncé une fois par épisode.
  */
 import type { IBackplaneQueueInfo } from "../../interfaces/IBackplane.js";
 /** Sévérité d'une transition de la file — mappée telle quelle sur le syslog. */
@@ -59,12 +71,24 @@ export declare class BackplanePublishQueue {
      * (sinon elle ne partirait jamais — famine silencieuse), quitte à dépasser
      * transitoirement. Même règle que le drop WS, qui teste `bufferedAmount` seul.
      *
+     * Un canal prioritaire (`isPriorityBusChannel` du cœur : ordre de contrôle,
+     * preuve de vie de la présence) est admis hors quota : la file l'applique, pas
+     * le driver, pour qu'un driver qui emploie la file la porte sans y penser.
+     *
+     * @param channel - canal logique de la publication.
      * @param bytes - taille de la charge sérialisée.
      * @param emit - envoi réel ; appelé UNIQUEMENT si la publication est admise.
      *   Son retour est suivi s'il s'agit d'une promesse (transport asynchrone).
      * @returns `true` si la publication est partie, `false` si elle a été jetée.
      */
-    send(bytes: number, emit: () => unknown): boolean;
+    send(channel: string, bytes: number, emit: () => unknown): boolean;
+    /**
+     * Attend que toutes les publications en vol soient acquittées ou refusées par le bus — à l'arrêt, pour que ce qui est déjà émis (la preuve de vie finale de la présence) parte avant la sortie du processus.
+     *
+     * Ne borne rien : un bus qui ne répond plus ne la résout jamais. L'appelant
+     * pose la limite (l'arrêt du noyau a la sienne).
+     */
+    settled(): Promise<void>;
     /** Compteurs pour la carte d'identité du backplane (sonde + Studio). */
     describe(): IBackplaneQueueInfo;
 }

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,20 @@
+import type { RealtimeClosedReason } from "nodefony";
+import type { ChannelFrame } from "./RealtimeHub.js";
+/**
+ * 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;
+    /** Écrit une trame partagée, encodée pour le codec de cette connexion. */
+    send(frame: ChannelFrame): void;
+}