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

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

@@ -1,4 +1,11 @@
-import { JsonRpcPeer, isPlatformChannel } from "nodefony";
+import { JsonRpcPeer, isPlatformChannel, type IFrameCodec, type IFrameCodecSet, type RealtimeFrameData } from "nodefony";
+import { RealtimeConnection } from "./RealtimeConnection.js";
+import type { IRealtimeConnection } from "../../interfaces/IRealtimeConnection.js";
+import type { IChannelAdmission, UserChannelPayload } from "nodefony";
+import { AdmissionBudget, type IAdmissionLimits } from "./admissionBudget.js";
+import type { IChannelAdmissionRule } from "./connectionAdmission.js";
+import type { IRealtimeConnectionState } from "../../interfaces/IRealtimeConnectionState.js";
+import type { ContractServerEmit, EventNames, EventPayload, IRealtimeContract } from "nodefony";
 import type { RealtimePublish } from "../../interfaces/IRealtimeController.js";
 import type { IClientLogsLimits } from "../../interfaces/IClientLogsLimits.js";
 import type { IChannelPolicy } from "../../interfaces/IChannelPolicy.js";
@@ -108,18 +115,62 @@ export interface IRevocableConnection {
  * Sink d'un canal : pousse une charge vers UNE connexion abonnée (son `peer.notify`).
  * 1 sink = 1 connexion. Le hub fan-out la charge à tous les sinks d'un canal.
  *
- * `serialized` n'est fourni que si le canal a déclaré un {@link ChannelSerializer}
- * ET qu'il a plusieurs abonnés : la frame ayant été sérialisée une fois pour tous,
- * le sink peut l'envoyer telle quelle au lieu de refaire le travail. Absent, le
- * sink se débrouille comme avant — un sink historique à un seul paramètre ignore
- * simplement l'argument.
+ * `frame` n'est fourni que si le canal a déclaré un {@link ChannelFrameBuilder} ET
+ * qu'il a plusieurs abonnés : la frame est la MÊME pour tous, le sink en demande
+ * l'encodage pour le codec de SA connexion ({@link ChannelFrame.encodeFor}) au lieu
+ * de refaire le travail. Absent, le sink se débrouille comme avant — un sink à un
+ * seul paramètre ignore simplement l'argument.
  */
-export type ChannelSink = (payload: unknown, serialized?: string) => void;
+export type ChannelSink = (payload: unknown, frame?: ChannelFrame) => void;
 /**
- * Sérialiseur de la frame d'un canal, fourni par l'abonné (le hub ignore tout du
- * protocole). Appelé **au plus une fois par publication**, jamais par abonné.
+ * Fabrique la frame protocolaire d'un canal (l'objet, pas ses octets), fournie par
+ * l'abonné : le hub ignore tout du protocole. Appelée **au plus une fois par
+ * publication**, jamais par abonné ; l'encodage, lui, se fait une fois par codec.
  */
-export type ChannelSerializer = (payload: unknown) => string;
+export type ChannelFrameBuilder = (payload: unknown) => unknown;
+/**
+ * Frame d'UNE publication diffusée à plusieurs abonnés, encodée **au plus une fois
+ * par codec** (ADR-0022 §2) : un canal suivi par des connexions texte et CBOR paie
+ * deux encodages, jamais un par connexion. L'encodage est paresseux — un codec
+ * qu'aucun abonné n'utilise ne coûte rien.
+ *
+ * Deux places suffisent : un hub sert au plus son codec texte et son codec
+ * binaire. Un troisième codec reste servi, sans mise en cache.
+ */
+export declare class ChannelFrame {
+    private readonly message;
+    private codecA;
+    private dataA;
+    private codecB;
+    private dataB;
+    private claimedA;
+    private claimedB;
+    /** @param message - la frame protocolaire, telle que rendue par le {@link ChannelFrameBuilder}. */
+    constructor(message: unknown);
+    /**
+     * Rend la frame encodée pour un codec, en l'encodant à la première demande.
+     *
+     * @param codec - le codec de la connexion qui va l'écrire.
+     * @returns la trame à écrire telle quelle, ou `undefined` si la frame n'est pas
+     *   encodable : l'abonné qui en {@link ChannelFrame.claimFailure | réclame}
+     *   l'échec reprend son chemin habituel, qui porte le filet (journal).
+     */
+    encodeFor(codec: IFrameCodec): RealtimeFrameData | undefined;
+    /**
+     * Réclame l'échec d'encodage de cette frame pour un codec : `true` au PREMIER
+     * abonné qui le demande, `false` ensuite.
+     *
+     * Un seul abonné reprend alors son chemin habituel, dont le filet journalise
+     * l'échec ; les autres sautent la trame, qu'ils ne pourraient pas encoder non
+     * plus. Sans cela, une charge non encodable — un `$bytes` forgé par un client,
+     * une valeur cyclique — coûtait un encodage et une ligne de journal PAR abonné.
+     * Un codec hors des deux places réclame à chaque fois : il n'est pas retenu.
+     *
+     * @param codec - le codec dont {@link ChannelFrame.encodeFor} a rendu `undefined`.
+     * @returns `true` si l'appelant doit dire l'échec.
+     */
+    claimFailure(codec: IFrameCodec): boolean;
+}
 /**
  * Fabrique le provider PARTAGÉ d'un canal (listener/ticker qui pousse via `publish`).
  * Appelée UNE fois, au 1ᵉʳ abonné. Renvoie son `dispose` (appelé au dernier
@@ -157,6 +208,12 @@ export type ChannelFactory = (channel: string, publish: RealtimePublish) => (()
  */
 export declare class RealtimeHub {
     #private;
+    /**
+     * Budget des admissions de l'exemplaire (appels d'`allow` en vol, coupe-circuit,
+     * `allowTimedOutTotal`/`allowSaturatedTotal`) — partagé par les files de toutes
+     * les connexions. Bornes posées par {@link setAdmissionLimits} au boot.
+     */
+    readonly admissionBudget: AdmissionBudget;
     /**
      * Abonnement demandé par une **connexion cliente** — même chose que
      * {@link subscribe}, plus le plancher des canaux de plateforme.
@@ -171,9 +228,11 @@ export declare class RealtimeHub {
      * sécurité en pose un, c'est lui qui décide (avec les rôles, ce que le hub ne
      * sait pas faire) et le plancher s'efface.
      *
+     * @param member - la connexion qui s'abonne : inscrite au registre du canal,
+     *   elle devient un membre identifiable ({@link channelMembers}).
      * @returns `true` si abonné, `false` si canal inconnu ou fermé par le plancher.
      */
-    subscribeClient(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean;
+    subscribeClient(channel: string, sink: ChannelSink, factory: ChannelFactory, buildFrame?: ChannelFrameBuilder, member?: RealtimeConnection): boolean;
     /**
      * Abonne un consommateur qui **répond du canal** : il apporte la `factory`, donc
      * la réponse à « ce canal existe-t-il, et qui le produit ? ». Le provider partagé
@@ -187,7 +246,7 @@ export declare class RealtimeHub {
      *
      * @returns `true` si abonné, `false` si canal inconnu (`factory` a renvoyé `null`).
      */
-    subscribe(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean;
+    subscribe(channel: string, sink: ChannelSink, factory: ChannelFactory, buildFrame?: ChannelFrameBuilder): boolean;
     /**
      * **Écoute passive** — un service du serveur reçoit ce qui passe sur un canal
      * sans prétendre le produire. C'est la porte de {@link ServerRealtimeSocket} :
@@ -213,6 +272,99 @@ export declare class RealtimeHub {
      * et retire le canal (libère timers/listeners). No-op si non abonné.
      */
     unsubscribe(channel: string, sink: ChannelSink): void;
+    /**
+     * Les connexions abonnées à un canal par un client — **local à ce pod** : les membres servis par un autre exemplaire n'y figurent pas.
+     *
+     * Les écouteurs et services du serveur (`listen`, `subscribe`) ne sont pas
+     * des membres. Chemin froid : une copie à chaque appel.
+     *
+     * @param channel - nom exact du canal.
+     * @returns les membres de ce pod, vide si le canal n'en a aucun ici.
+     */
+    channelMembers(channel: string): IRealtimeConnection[];
+    /**
+     * Abonne d'office une connexion à un canal — **local à ce pod** : seule une connexion acceptée par ce processus peut l'être.
+     *
+     * Même porte qu'un `subscribe` du client (ADR-0022 §6 décision 2) : la
+     * politique fixe du canal (rôles, scopes, plancher de plateforme), puis sa
+     * règle `allow` s'il en déclare une. Un refus n'abonne pas, et seul
+     * l'appelant l'apprend ; jamais un abonnement qui contourne `allow` — le
+     * client rejoue ses abonnements à chaque reconnexion, et ce rejeu passe par
+     * `allow` : l'application écrit donc l'appartenance là où `allow` la lit.
+     *
+     * Le client est notifié par `realtime:subscribed { channel, imposed: true }`
+     * et inscrit le canal dans ses abonnements ; il peut le quitter.
+     *
+     * Plusieurs exemplaires : la requête qui décide doit atteindre le processus
+     * qui tient la socket — la passer par la socket elle-même (`@RealtimeInbound`,
+     * qui reçoit la connexion), ou faire autoriser l'entrée par `allow` (registre
+     * partagé) et laisser le navigateur s'abonner.
+     *
+     * @param channel - nom exact du canal.
+     * @param connection - la connexion à abonner (reçue par un gestionnaire `@RealtimeInbound`, ou lue dans {@link channelMembers}).
+     * @returns `true` une fois l'abonnement acquitté ; `false` si refusé, si la
+     *   connexion est fermée ou inconnue de ce processus, ou si le client s'en
+     *   désabonne avant le verdict.
+     */
+    subscribeConnection(channel: string, connection: IRealtimeConnection): Promise<boolean>;
+    /**
+     * Retire une connexion d'un canal — **local à ce pod** ; elle reçoit `realtime:closed { reason: "evicted" }`.
+     *
+     * ⚠️ **Éjecter coupe la connexion du canal, seul `allow` exclut**
+     * (ADR-0022 §6 décision 3). Le client ne rejoue pas un canal dont il a été
+     * éjecté, mais c'est une politesse : une page rechargée refait `subscribe`.
+     * Sur un canal à `allow`, l'éjecté revient si l'application n'a pas retiré
+     * l'appartenance là où `allow` la lit ; sur un canal sans `allow`, sa
+     * politique fixe le laisse rentrer.
+     *
+     * @param channel - nom exact du canal.
+     * @param connection - la connexion à retirer.
+     * @returns `false` si la connexion n'est pas membre du canal, est fermée, ou
+     *   inconnue de ce processus — jamais un geste muet.
+     */
+    evictConnection(channel: string, connection: IRealtimeConnection): boolean;
+    /**
+     * Termine un canal pour tous ses membres, **sur tous les serveurs** : chacun reçoit `realtime:closed { reason: "ended" }`, et le producteur est libéré.
+     *
+     * **Traverse les pods** : avec un backplane branché, l'ordre part sur le bus
+     * (`PLATFORM_BUS_CHANNELS.control`, scellé comme toute publication) et chaque
+     * serveur l'applique à SES membres. Livraison « au plus une fois » du bus :
+     * un pod qui manque l'ordre, ou qui démarre après, est rattrapé par la
+     * fabrique, qui rend `null` pour une instance terminée. Un canal de la
+     * plateforme (`nodefony:`) reste local — il décrit un pod, pas une partie.
+     *
+     * Les écouteurs du serveur (`listen`) restent inscrits, sur un canal redevenu
+     * PASSIF : le prochain `subscribe` d'un client rejoue la fabrique, et c'est
+     * elle qui tranche. **Seule la fabrique clôt un canal** (ADR-0021 S4) — le
+     * hub ne garde aucune marque « fermé » : une fabrique qui rend encore un
+     * producteur pour ce nom le rouvre. D'où la règle d'écriture d'un canal à
+     * durée de vie : son nom porte l'identifiant de l'instance
+     * (`room:42:<partie>`), et la fabrique rend `null` pour une instance terminée.
+     *
+     * @param channel - nom exact du canal.
+     * @returns le nombre de membres de CE pod à qui la fin a été notifiée — les
+     *   autres serveurs l'appliquent sans compte rendu.
+     */
+    closeChannel(channel: string): number;
+    /**
+     * Éjecte un compte d'un canal, **sur tous les serveurs** : chacune de ses connexions membres reçoit `realtime:closed { reason: "evicted" }`.
+     *
+     * Tous les onglets du compte sont visés, où qu'ils soient servis ; l'ordre
+     * traverse les pods comme {@link closeChannel}. ⚠️ **Éjecter coupe, seul
+     * `allow` exclut** (ADR-0022 §6 décision 3) : pour que le compte ne revienne
+     * pas, l'application retire l'appartenance là où `allow` la lit.
+     *
+     * ⚠️ Sur un bus PARTAGÉ, un tiers qui y écrit peut rejouer un ordre capté :
+     * sur un canal durable, il recouperait le compte à chaque réadmission (risque
+     * accepté et borné, ADR-0022 §6 d4) — bus privé exigé ; changer le secret du
+     * bus rend caducs les ordres déjà captés.
+     *
+     * @param channel - nom exact du canal.
+     * @param user - identifiant du compte (`IRealtimeConnection.userId`).
+     * @returns le nombre de connexions de CE pod éjectées. Un nom vide ou de plus
+     *   de 1 024 caractères n'éjecte rien et ne part pas sur le bus.
+     */
+    evictUser(channel: string, user: string): number;
     /**
      * Publie une charge sur un canal : **fan-out local** **+** propagation conditionnelle
      * au {@link IBackplane} (autres workers/pods). C'est le point d'entrée des providers
@@ -226,8 +378,29 @@ export declare class RealtimeHub {
      *
      * Anti-boucle : un message **reçu** du backplane ne repasse PAS par ici (il appelle
      * `publishLocal` directement) → aucune ré-émission cross-process, pas de tempête.
+     *
+     * @param payload - objet, tableau ou octets ; omise = signal sans charge.
+     * @throws TypeError si la charge est un scalaire ou `null` ({@link isRealtimePayload},
+     *   ADR-0021 S1) — un scalaire se publie dans un objet (`{ value }`).
      */
-    publish(channel: string, payload: unknown): void;
+    publish(channel: string, payload?: object): void;
+    /**
+     * Livre une charge à UNE identité — tous ses onglets, tous les serveurs, et personne d'autre (ADR-0022 §6, D1).
+     *
+     * Publie sur son canal personnel `user:<userId>` : seuls les onglets de cette
+     * identité ont pu s'y abonner (politique intégrée, admission par égalité de
+     * chaîne), et le préfixe traverse le bus dès qu'un bus est branché. Rien à
+     * déclarer côté application. Personne n'écoute ? La charge est perdue, sans
+     * erreur : c'est une diffusion, pas une boîte aux lettres.
+     *
+     * @param userId - l'`id` STABLE du compte (`RealtimeIdentity.id`), jamais le
+     *   login.
+     * @param payload - objet, tableau ou octets ; omise = signal sans charge.
+     * @throws TypeError si la charge est un scalaire ou `null` (cf {@link publish}).
+     */
+    publishToUser(userId: string, payload?: object): void;
+    /** Préfixes déclarés diffusables entre serveurs, dans l'ordre de déclaration — lu par la ligne de démarrage. */
+    broadcastPrefixes(): readonly string[];
     /**
      * Fan-out d'une charge aux **seuls abonnés locaux** d'un canal (process courant).
      * NE propage PAS au backplane → c'est la voie d'**ingress** d'un message venu d'un
@@ -269,7 +442,11 @@ export declare class RealtimeHub {
      * sur le chemin chaud). À équilibrer par {@link unregisterConnection} au close.
      */
     registerConnection(conn: IRealtimeConnProbe): void;
-    /** Retire une connexion du registre de la sonde (au close). No-op si absente. */
+    /**
+     * Retire une connexion du registre de la sonde (au close) et verse ses cumuls à
+     * ceux des connexions fermées : les totaux de {@link probe} restent monotones.
+     * No-op si absente — une double sortie ne compte pas deux fois.
+     */
     unregisterConnection(conn: IRealtimeConnProbe): void;
     /**
      * Inscrit une connexion à identité RÉVOCABLE au registre de
@@ -361,6 +538,30 @@ export declare class RealtimeHub {
      * `defineRealtimeConfig().slowConsumer.bytes` (sinon la clé de config serait morte).
      */
     setSlowConsumerBytes(bytes: number): void;
+    /**
+     * Les codecs de frame du serveur (ADR-0022 §2) : le texte, et le codec binaire
+     * accordé aux clients qui l'offrent — `null` tant que la configuration n'en
+     * active aucun. Lu une fois par connexion, au handshake, jamais par trame.
+     */
+    get frameCodecs(): IFrameCodecSet;
+    /**
+     * Pose le codec binaire du serveur — 1× au boot par `RealtimeService.init()`,
+     * depuis la clé `codec` de la configuration. Sans argument : texte seul.
+     *
+     * @param codec - le codec activé (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+     */
+    setFrameCodec(codec?: IFrameCodec): void;
+    /**
+     * Le codec des connexions texte — celui qu'emprunte aussi le REST du plan
+     * d'administration, pour qu'une valeur lue par `GET` soit celle que la socket
+     * livre (#618 D9). Avec un codec binaire activé, c'est le JSON à convention
+     * d'octets ; sinon le JSON natif.
+     */
+    get textFrameCodec(): IFrameCodec;
+    /**
+     * Pose les bornes des admissions (`authenticateTimeoutMs`, `allowTimeoutMs`, `maxPendingAllowsPerConnection`, `maxPendingAllowsTotal`) — 1× au boot par `RealtimeService.init()`.
+     */
+    setAdmissionLimits(limits: IAdmissionLimits): void;
     /**
      * Associe un token au peer (posé par `RealtimeController.onHandshake()` après
      * succès `authenticator.authenticate()` ou fallback anonyme). Lazy alloc de
@@ -439,9 +640,18 @@ export declare class RealtimeHub {
      *
      * @param name   - nom exact du canal (subscribe), de la méthode inbound, ou
      *   MOTIF de famille s'il contient `*`.
+     * Une politique à `allow` porte sa règle d'admission : une flèche est
+     * retenue telle quelle ; une classe exige son instance, résolue au démarrage
+     * par l'injecteur, dont la méthode est liée ICI, une fois — le `subscribe`
+     * n'appelle qu'une fonction prête.
+     *
      * @param policy - exigences ({@link IChannelPolicy}) lues par security.
+     * @param admission - instance de la classe d'admission quand `policy.allow`
+     *   en est une ; ignorée sinon.
+     * @throws BootConfigurationError La politique désigne une classe d'admission
+     *   et aucune instance de CETTE classe n'est fournie.
      */
-    registerChannelPolicy(name: string, policy: IChannelPolicy): void;
+    registerChannelPolicy(name: string, policy: IChannelPolicy, admission?: IChannelAdmission): void;
     /**
      * Nombre maximum de `*` dans un motif.
      *
@@ -459,6 +669,31 @@ export declare class RealtimeHub {
      * la frame `subscribe`/inbound. O(1), 0 alloc quand le registre est vide.
      */
     resolveChannelPolicy(name: string): IChannelPolicy | null;
+    /**
+     * Règle d'admission prête à appeler pour ce canal — `null` s'il ne déclare pas `allow`. Lue au `subscribe`, jamais par trame.
+     *
+     * Même résolution que {@link resolveChannelPolicy} (nom exact, puis motif le
+     * plus spécifique) : la règle suit TOUJOURS la politique qui s'applique.
+     */
+    resolveChannelAdmission(name: string): IChannelAdmissionRule | null;
+    /**
+     * Les politiques de cette classe de contrôleur sont-elles déjà inscrites ? Une poignée de main n'en paie que ce `has`.
+     *
+     * @param owner - le constructeur du contrôleur.
+     */
+    hasPolicyOwner(owner: object): boolean;
+    /**
+     * Marque les politiques de cette classe comme inscrites — APRÈS l'inscription réussie, jamais avant : une politique refusée doit l'être de nouveau à la poignée de main suivante, pas laisser le canal ouvert.
+     *
+     * @param owner - le constructeur du contrôleur.
+     */
+    addPolicyOwner(owner: object): void;
+    /**
+     * Une politique est-elle déclarée sous ce nom EXACT — motifs ignorés ? C'est la question du défaut fermé des actions.
+     *
+     * @param name - nom d'action ou de canal.
+     */
+    hasExactChannelPolicy(name: string): boolean;
     /** Des politiques de canal sont-elles déclarées (au moins une) ? */
     hasChannelPolicies(): boolean;
     /**
@@ -466,14 +701,14 @@ export declare class RealtimeHub {
      * DYNAMIQUE n'est couvert par aucune politique déclarée, alors que d'autres
      * canaux du module en portent une.
      *
-     * Le registre des politiques est indexé par nom **EXACT** : `@RealtimeChannel`
-     * déclare `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence,
-     * forage, suffixe) est servi par la fabrique dynamique et **ne matche pas**.
-     * L'auteur croit alors son canal gardé ; il ne l'est pas, et rien ne le lui
-     * dit. C'est ce silence qu'on ferme ici — et depuis qu'une politique peut se
-     * déclarer par MOTIF (`chat:room:*`), cet avertissement ne parle plus que des
-     * canaux qu'aucun motif ne couvre : il désigne un vrai trou, pas une limite
-     * de l'outil.
+     * Le registre des politiques lit le nom **EXACT**, puis les **MOTIFS**
+     * déclarés ({@link resolveChannelPolicy}) : `@RealtimeChannel` déclare
+     * `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence, forage,
+     * suffixe) servi par la fabrique dynamique ne matche ce nom que si un motif
+     * (`chat:room:*`) le couvre. Sans motif, l'auteur croit son canal gardé ; il
+     * ne l'est pas, et rien ne le lui dit. C'est ce silence qu'on ferme ici :
+     * l'avertissement ne parle que des canaux qu'aucun motif ne couvre — un vrai
+     * trou, pas une limite de l'outil.
      *
      * Appelé par le contrôleur, seul à savoir par quelle voie le canal a été
      * servi. Muet si aucune politique n'est déclarée (module aux canaux libres :
@@ -514,6 +749,21 @@ export declare class RealtimeHub {
     /** Bornes en vigueur, ou `null` si le canal montant est fermé. */
     get clientLogsLimits(): IClientLogsLimits | null;
     runAuthorizer(frame: unknown, peer: JsonRpcPeer): boolean;
+    /**
+     * Inscrit une connexion qui vient de retenir son premier « oui » du verrou.
+     *
+     * Appelé par `gateFrame`, jamais par trame chaude ; à équilibrer par
+     * {@link untrackRetainedVerdicts} à la fermeture.
+     *
+     * @param state - état de la connexion.
+     */
+    trackRetainedVerdicts(state: IRealtimeConnectionState): void;
+    /**
+     * Retire une connexion fermée du registre des verdicts retenus.
+     *
+     * @param state - état de la connexion.
+     */
+    untrackRetainedVerdicts(state: IRealtimeConnectionState): void;
     /**
      * Ce peer pourrait-il s'abonner à ce canal ? — même décision que `subscribe`,
      * sans trace ni effet de bord.
@@ -533,6 +783,53 @@ export declare class RealtimeHub {
     /** Dispose tous les providers et vide le hub (arrêt process / reset de test). */
     clear(): void;
 }
-/** Renvoie le hub realtime du process (singleton lazy). */
+/**
+ * Le hub lu à travers le contrat `C` : mêmes méthodes que {@link RealtimeHub},
+ * mais `publish` n'accepte que les canaux de `serverToClient`, chacun avec la
+ * charge qu'il déclare. C'est le MÊME objet que le hub libre — une vue de type,
+ * sans un octet ni une instruction de plus.
+ *
+ * @typeParam C - le contrat de l'application.
+ */
+export interface IContractRealtimeHub<C extends IRealtimeContract> extends Omit<RealtimeHub, "publish" | "publishToUser"> {
+    /**
+     * Livre à UNE identité la charge que le contrat déclare pour le canal
+     * personnel (clé gabarit `` [k: `user:${string}`]: … `` de `serverToClient`)
+     * — cf {@link RealtimeHub.publishToUser}. Contrat sans cette clé : ne compile
+     * pas, la forme du message privé se déclare d'abord.
+     *
+     * @param userId - l'`id` STABLE du compte, jamais le login.
+     */
+    publishToUser(userId: string, payload: UserChannelPayload<ContractServerEmit<C>> & object): void;
+    /**
+     * Publie sur un canal déclaré par le contrat (fan-out local, puis backplane
+     * si le canal est broadcast) — cf {@link RealtimeHub.publish}.
+     *
+     * @throws TypeError si la charge n'est pas un objet ({@link isRealtimePayload}).
+     */
+    publish<K extends EventNames<ContractServerEmit<C>>>(channel: K, payload: EventPayload<ContractServerEmit<C>, K> & object): void;
+}
+/**
+ * Renvoie le hub realtime du process (singleton lazy) — forme LIBRE : tout nom
+ * de canal, toute charge objet.
+ */
 export declare function getRealtimeHub(): RealtimeHub;
+/**
+ * Renvoie le hub realtime du process lu à travers le contrat `C` : la diffusion
+ * d'un service, d'un job ou d'une boucle de jeu est vérifiée par le contrat
+ * partagé avec le navigateur. Même objet que la forme libre : 0 octet, 0 ns.
+ *
+ * Le contrat est choisi par l'appelant — rien n'empêche d'en nommer un autre que
+ * celui du contrôleur qui sert le canal ; c'est le fichier partagé qui fait foi.
+ *
+ * @typeParam C - le contrat de l'application.
+ *
+ * @example
+ * ```ts
+ * const chat = getRealtimeHub<ChatContract>();
+ * chat.publish("chat:room", { from: "ana", text: "salut" }); // charge vérifiée
+ * getRealtimeHub().publish("n'importe:quoi", { x: 1 });       // forme libre
+ * ```
+ */
+export declare function getRealtimeHub<C extends IRealtimeContract>(): IContractRealtimeHub<C>;
 export default RealtimeHub;

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

@@ -31,7 +31,7 @@ export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEvents
     private readonly hub;
     constructor(hub?: import("./RealtimeHub.js").RealtimeHub);
     /** Émet sur un canal — fan-out aux abonnés via le hub (+ backplane si broadcast). */
-    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : object): void;
     /**
      * S'abonne (ref-compté) à un canal pour le RECEVOIR. Au 1ᵉʳ consommateur, pose un
      * sink d'**écoute passive** auprès du hub : le service reçoit ce qui passe, sans

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

@@ -0,0 +1,71 @@
+/** Rendu par {@link AdmissionBudget.acquire} quand une place est réservée. */
+export declare const ADMISSION_GRANTED = -1;
+/** Rendu par {@link AdmissionBudget.authenticateWithin} quand l'authentification n'a pas répondu à temps. */
+export declare const AUTHENTICATE_TIMED_OUT: unique symbol;
+/** Bornes des admissions, lues dans la configuration realtime (`authenticateTimeoutMs`, `allowTimeoutMs`, `maxPendingAllowsPerConnection`, `maxPendingAllowsTotal`). */
+export interface IAdmissionLimits {
+    readonly authenticateTimeoutMs: number;
+    readonly allowTimeoutMs: number;
+    readonly maxPendingAllowsPerConnection: number;
+    readonly maxPendingAllowsTotal: number;
+}
+/**
+ * Budget des admissions d'UN exemplaire — appels d'`allow` en vol, coupe-circuit et compteurs de refus (ADR-0021 §S10 bis point 3, §S9).
+ *
+ * Partagé par toutes les connexions du hub ; chaque connexion garde sa propre
+ * file ({@link ConnectionAdmission}). Aucune horloge n'est lue tant que le
+ * coupe-circuit est fermé : une règle synchrone ne paie que deux incréments.
+ */
+export declare class AdmissionBudget {
+    #private;
+    /** Délai de l'authentification à la poignée de main (ADR-0021 §S11). */
+    authenticateTimeoutMs: number;
+    /** Délai d'un appel d'`allow`, compté depuis la réception du `subscribe`, file comprise. */
+    timeoutMs: number;
+    /** Appels d'`allow` en vol par connexion ; au-delà, la demande attend son tour. */
+    maxPerConnection: number;
+    /** Applique les bornes de la configuration (boot, cold path). */
+    configure(limits: IAdmissionLimits): void;
+    /**
+     * Réserve une place pour UN appel d'`allow`.
+     *
+     * @returns {@link ADMISSION_GRANTED} si la place est prise ; sinon la demande
+     *   est comptée dans `allowSaturatedTotal` et la valeur rendue est le délai à
+     *   annoncer au client (`retryAfterMs`, coupe-circuit ouvert), ou `0` quand il
+     *   n'est pas connu (plafond global atteint).
+     */
+    acquire(): number;
+    /** Rend la place d'un appel terminé, dépassé ou abandonné à la fermeture. */
+    release(): void;
+    /** Un appel d'`allow` n'a pas répondu dans son délai : compté, et porté au coupe-circuit. */
+    recordTimeout(now: number): void;
+    /** Une demande a épuisé son délai dans la file, sans appel d'`allow`. */
+    recordQueueExpired(): void;
+    /** Délai restant du coupe-circuit à `now`, ou `undefined` s'il est fermé. */
+    retryAfter(now: number): number | undefined;
+    /** Faut-il journaliser cette cause maintenant ? Vrai au plus une fois par fenêtre et par cause. */
+    shouldWarn(kind: "timeout" | "throw" | "authenticate", now: number): boolean;
+    /**
+     * Borne l'authentification d'une poignée de main par `authenticateTimeoutMs` (ADR-0021 §S11).
+     *
+     * Une identité arrivée après le délai est IGNORÉE : la promesse rendue est
+     * déjà réglée sur {@link AUTHENTICATE_TIMED_OUT}, et un rejet tardif ne lève
+     * rien (la promesse d'origine garde son gestionnaire). Le minuteur est coupé
+     * dès la réponse et ne retient pas le processus à l'arrêt. Chaque dépassement
+     * compte une poignée de main dans `authenticateTimedOutTotal`.
+     *
+     * @param pending - la promesse rendue par `authenticate()`
+     * @returns le jeton, ou {@link AUTHENTICATE_TIMED_OUT} au dépassement
+     */
+    authenticateWithin<T>(pending: Promise<T>): Promise<T | typeof AUTHENTICATE_TIMED_OUT>;
+    /** Appels d'`allow` en vol sur l'exemplaire. */
+    get pending(): number;
+    /** Cumul `allowTimedOutTotal` — unité : un appel d'`allow`. */
+    get timedOutTotal(): number;
+    /** Cumul `allowSaturatedTotal` — unité : une demande d'abonnement. */
+    get saturatedTotal(): number;
+    /** Cumul `authenticateTimedOutTotal` — unité : une poignée de main. */
+    get authenticateTimedOutTotal(): number;
+    /** Remet compteurs, coupe-circuit et bornes à leurs défauts (hub vidé). */
+    reset(): void;
+}

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

@@ -0,0 +1,34 @@
+import type { ChannelAdmissionClass, IChannelAdmission } from "nodefony";
+import type RealtimeHub from "./RealtimeHub.js";
+/**
+ * Résout l'instance d'une classe d'admission pour un canal — fournie par le module realtime au démarrage, absente à la poignée de main.
+ */
+export type AdmissionResolver = (admissionClass: ChannelAdmissionClass, channel: string) => IChannelAdmission;
+/**
+ * Inscrit au hub les politiques déclarées par une classe de contrôleur — une fois par classe et par hub, et seulement si l'inscription entière réussit.
+ *
+ * Appelée pour chaque contrôleur connu au démarrage du noyau, puis à la
+ * poignée de main pour une classe qui y aurait échappé : celle-ci ne paie alors
+ * qu'un `has`. Une politique refusée ne marque PAS la classe — elle est refusée
+ * de nouveau à la poignée de main suivante plutôt que de laisser le canal
+ * ouvert.
+ *
+ * @param hub - le hub qui porte le registre.
+ * @param ctor - constructeur du contrôleur.
+ * @param resolveAdmission - résolution des classes d'admission ; `null` hors
+ *   démarrage, et le hub refuse alors une politique qui en désigne une.
+ * @throws BootConfigurationError Politique illisible, `allow` posé sur une
+ *   action, ou classe d'admission non résolue.
+ */
+export declare function registerControllerPolicies(hub: RealtimeHub, ctor: object, resolveAdmission: AdmissionResolver | null): void;
+/**
+ * Fabrique la résolution des classes d'admission du démarrage : portée singleton exigée, instance du conteneur réutilisée, sinon construite UNE fois par l'injecteur.
+ *
+ * @param get - l'instance déjà construite d'une classe : le démarrage la lit
+ *   dans le conteneur du noyau par sa clé (`null` tant que la classe n'y a
+ *   jamais été rangée), le harnais de test parmi les instances que le test lui
+ *   donne. `undefined` → construite par l'injecteur.
+ * @param log - journal du module (une ligne par canal résolu).
+ * @returns le résolveur, qui mémorise l'instance de chaque classe.
+ */
+export declare function createAdmissionResolver(get: (key: string | null, admissionClass: ChannelAdmissionClass) => unknown, log: (message: string) => void): AdmissionResolver;

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

@@ -0,0 +1,68 @@
+import type { ChannelAllowFunction, ISubscriberIdentity } from "nodefony";
+import { type AdmissionBudget } from "./admissionBudget.js";
+/**
+ * Règle d'admission d'un canal telle que le hub la tient prête — construite UNE fois à l'inscription de la politique, lue au `subscribe`.
+ */
+export interface IChannelAdmissionRule {
+    /** La règle, flèche ou méthode `allow` déjà liée à son instance. */
+    readonly allow: ChannelAllowFunction;
+    /** `anonymous: true` de la politique : l'anonyme est présenté à `allow` au lieu d'être refusé d'office. */
+    readonly anonymous: boolean;
+}
+/**
+ * Ce que la file d'admission demande à sa connexion — ouvrir le canal, le refuser, journaliser. Implémenté par `RealtimeController`, une fois par connexion.
+ */
+export interface IAdmissionHost {
+    /** Ouvre l'abonnement admis (et l'acquitte). */
+    open(channel: string): void;
+    /** Rend le refus observable (`realtime:denied`) ; `detail` n'est rédigé qu'hors production. */
+    deny(channel: string, reason: "forbidden" | "unavailable", detail: string | undefined, retryAfterMs?: number): void;
+    /** Journal d'exploitation (déjà limité en fréquence par l'appelant). */
+    warn(message: string): void;
+}
+/**
+ * Admission des abonnements d'UNE connexion aux canaux qui déclarent `allow` — appels bornés, file d'attente, délai, verdict (ADR-0021 §S10 et §S10 bis).
+ *
+ * Coûts, par construction :
+ * - une règle qui répond `true`/`false` sans promesse ne crée ni minuteur, ni
+ *   promesse, ni entrée d'attente ;
+ * - au-delà de `maxPendingAllowsPerConnection` appels en vol, la demande ATTEND
+ *   son tour (jamais `limit` : le rejeu au `welcome` renvoie tous les canaux
+ *   d'un coup) ; la file reste `null` tant que personne n'attend ;
+ * - un seul minuteur par connexion, armé sur l'échéance de tête : les demandes
+ *   arrivent dans l'ordre de leurs échéances, la plus ancienne non tranchée est
+ *   donc toujours la prochaine à expirer.
+ *
+ * Seul `=== true` admet ; une exception ou un rejet valent `forbidden` ; un
+ * délai dépassé ou une saturation valent `unavailable`, et un verdict arrivé
+ * après coup est ignoré.
+ */
+export declare class ConnectionAdmission {
+    #private;
+    /**
+     * @param host - la connexion qui ouvre ou refuse.
+     * @param budget - le budget de l'exemplaire (plafond global, coupe-circuit).
+     * @param who - identité d'admission gelée de la connexion.
+     * @param explain - rédiger le détail des refus (hors production).
+     */
+    constructor(host: IAdmissionHost, budget: AdmissionBudget, who: ISubscriberIdentity, explain: boolean);
+    /** Demandes en attente de verdict — comptées dans le plafond de canaux de la connexion. */
+    get unsettled(): number;
+    /**
+     * Un abonnement à ce canal attend-il déjà son verdict ? S'il avait été annulé par un `unsubscribe`, il est ranimé : le verdict à venir répondra.
+     *
+     * @returns `true` si la demande est déjà en attente (rien d'autre à faire).
+     */
+    revive(channel: string): boolean;
+    /** `unsubscribe` pendant l'attente : le verdict à venir sera jeté sans réponse. */
+    cancel(channel: string): void;
+    /**
+     * Demande l'admission sur `channel` selon sa règle — l'anonyme est refusé d'office sauf `anonymous: true`.
+     *
+     * @param channel - nom exact du canal demandé.
+     * @param rule - règle résolue par le hub pour ce canal.
+     */
+    request(channel: string, rule: IChannelAdmissionRule): void;
+    /** Fermeture de la connexion : minuteur coupé, places rendues, verdicts à venir jetés. */
+    close(): void;
+}