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

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

@@ -1,4 +1,12 @@
-import { JsonRpcPeer, isPlatformChannel } from "nodefony";
+import { JsonRpcPeer, isPlatformChannel, type IFrameCodec, type IFrameCodecSet, type RealtimeFrameData } from "nodefony";
+import { RealtimeConnection } from "./RealtimeConnection.js";
+import { type IChannelPresenceView } from "./channelPresence.js";
+import type { IRealtimeConnection } from "../../interfaces/IRealtimeConnection.js";
+import type { IChannelAdmission, IChannelPolicies, 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";
@@ -26,8 +34,21 @@ export type OriginGuard = (origin: string | undefined) => boolean;
  * `@nodefony/security` au boot via {@link RealtimeService.setFrameAuthorizer}.
  * Doctrine SYNC stricte (cf `JsonRpcPeerOptions.beforeDispatch`) : un `await` par
  * frame coûterait une microtask et sérialiserait le pipeline RPC du peer.
+ *
+ * `judgesWrite` : le verrou sait juger une politique d'ÉCRITURE distincte de la
+ * lecture (ADR-0022 §6, décision 1 quater). Un verrou qui ne le déclare pas ne
+ * lirait que la lecture, et laisserait ouverte une écriture plus stricte : le
+ * hub refuse alors de démarrer dès qu'une telle écriture est déclarée.
+ *
+ * `explain` : la phrase qui dit POURQUOI une trame a été refusée, quand le
+ * verrou sait la rédiger (`null` sinon). Lu après un refus seulement
+ * ({@link RealtimeHub.explainDenial}) — jamais sur le trajet d'une trame
+ * acceptée. Elle va au journal du serveur, et au client hors production.
  */
-export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean;
+export type FrameAuthorizer = ((frame: unknown, token: IRealtimeToken) => boolean) & {
+    readonly judgesWrite?: true;
+    readonly explain?: (frame: unknown, token: IRealtimeToken) => string | null;
+};
 /**
  * Seuil d'alerte slow-consumer (octets de `bufferedAmount`). Au-delà, la connexion
  * est comptée comme « lente » par la sonde (PAS encore de drop/close — la sonde MESURE
@@ -108,18 +129,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, frame?: ChannelFrame) => void;
+/**
+ * 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 ChannelSink = (payload: unknown, serialized?: string) => void;
+export type ChannelFrameBuilder = (payload: unknown) => unknown;
 /**
- * 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é.
+ * 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 type ChannelSerializer = (payload: unknown) => string;
+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
@@ -128,6 +193,17 @@ export type ChannelSerializer = (payload: unknown) => string;
  * a déclenché la création (elle peut fermer alors que le provider partagé survit).
  */
 export type ChannelFactory = (channel: string, publish: RealtimePublish) => (() => void) | null;
+/**
+ * Qui a déclaré une sorte de politique sous un nom, et laquelle — retenu au démarrage pour refuser deux classes en désaccord sur un même nom.
+ */
+export interface IChannelPolicyClaim {
+    /** Constructeur du contrôleur qui a déclaré le premier. */
+    readonly owner: object;
+    /** Son nom, pour le message de refus. */
+    readonly ownerName: string;
+    /** La politique déclarée. */
+    readonly policy: IChannelPolicy;
+}
 /**
  * RealtimeHub — broker temps réel **PAR INSTANCE** (1 pod = 1 process = 1 hub local).
  *
@@ -157,6 +233,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 +253,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 +271,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 +297,131 @@ export declare class RealtimeHub {
      * et retire le canal (libère timers/listeners). No-op si non abonné.
      */
     unsubscribe(channel: string, sink: ChannelSink): void;
+    /**
+     * Présence d'un canal vue de CE pod (ADR-0025 P3) — `count`, `unnamed`, `members` (toujours, quel que soit le seuil de la trame), `partial`.
+     *
+     * La voie de l'observateur qui lit sans figurer (modérateur, tableau de
+     * bord). Chemin froid : une copie à chaque appel.
+     *
+     * @param channel - nom exact du canal.
+     * @returns la vue (vide si personne n'est là), ou `null` si la politique du
+     *   canal ne déclare pas `presence`.
+     */
+    presence(channel: string): IChannelPresenceView | null;
+    /**
+     * Arrêt propre de la présence répartie (ADR-0025 P5) — le dernier lot part, puis une preuve de vie FINALE : les pairs retirent aussitôt les présents de ce serveur, sans attendre le délai d'oubli. Plus rien ne part ensuite ; idempotent, sans effet sans bus.
+     *
+     * Appelé par le module à l'arrêt du noyau (`onTerminate`), AVANT que le bus ne
+     * se ferme. Les connexions qui se ferment ensuite ne publient plus rien : la
+     * preuve de vie finale les a déjà retirées chez les pairs.
+     */
+    endPresence(): void;
+    /**
+     * Un abonnement vient d'être acquitté : sur un canal à présence, la liste complète part vers CETTE connexion, puis les changements en attente partent si la fenêtre le permet.
+     *
+     * Appelé par le contrôleur APRÈS `realtime:subscribed`, à chaque (re-)`subscribe`
+     * — aucune borne : la contre-pression peut avoir jeté la liste d'avant sans
+     * le dire, et c'est le re-`subscribe` qui répare (ADR-0025 P2 bis). La liste
+     * est encodée une fois par envoi de changements et par codec, puis servie
+     * telle quelle.
+     *
+     * @param channel - nom exact du canal acquitté.
+     * @param connection - la connexion abonnée.
+     */
+    presenceSubscribed(channel: string, connection: RealtimeConnection): 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 +435,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?: 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}).
      */
-    publish(channel: string, payload: unknown): void;
+    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 +499,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 +595,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
@@ -377,6 +635,10 @@ export declare class RealtimeHub {
      * **Seam #1 (P13 → P6)** — pose le verrou de frame (cf {@link FrameAuthorizer}).
      * `null` retire la politique (bypass total). Posé 1× au boot par
      * `@nodefony/security` depuis les zones `realtime: true`. Cold path.
+     *
+     * @throws BootConfigurationError Le verrou ne déclare pas `judgesWrite`
+     *   alors qu'une écriture distincte de la lecture est inscrite : il la
+     *   laisserait ouverte.
      */
     setFrameAuthorizer(authorizer: FrameAuthorizer | null, options?: {
         readonly silentProbe?: FrameAuthorizer | null;
@@ -420,10 +682,7 @@ export declare class RealtimeHub {
      */
     hasUnenforcedChannelPolicies(): boolean;
     /**
-     * **Seam #1b** — déclare la politique d'autorisation d'un canal/méthode
-     * (`@RealtimeChannel`/`@RealtimeInbound` avec opts). Appelé au handshake par
-     * le controller pour CHAQUE canal décoré (idempotent : même nom = écrase, les
-     * controllers d'un même endpoint déclarent la même policy). Cold path.
+     * **Seam #1b** — pose la politique d'un canal/méthode en REMPLAÇANT ce que ce nom déclarait (voie programmatique ; les décorateurs passent par {@link RealtimeHub.declareChannelPolicy}). Cold path.
      *
      * Deux formes de nom, et la seconde garde une FAMILLE :
      *
@@ -433,15 +692,42 @@ export declare class RealtimeHub {
      *   Le `*` remplace n'importe quelle suite de caractères ; tout le reste du
      *   motif est littéral (échappé), y compris `.` et `(`.
      *
-     * Précédence : le nom **exact** l'emporte toujours — c'est ainsi qu'on ouvre
-     * une exception dans une famille gardée. Entre deux motifs, le plus
-     * **spécifique** gagne (littéral le plus long).
+     * Précédence, SORTE PAR SORTE (ADR-0022 §6, décision 1 quater) : la lecture
+     * d'un nom vient de la déclaration la plus spécifique qui POSE une lecture —
+     * le nom **exact**, puis le motif au littéral le plus long ; l'écriture de
+     * même. C'est ainsi qu'on ouvre une exception dans une famille gardée, sans
+     * effacer la sorte que l'exception ne déclare pas.
      *
-     * @param name   - nom exact du canal (subscribe), de la méthode inbound, ou
+     * @param name - nom exact du canal, de la méthode entrante ou de l'action, ou
      *   MOTIF de famille s'il contient `*`.
-     * @param policy - exigences ({@link IChannelPolicy}) lues par security.
+     * @param policy - exigences de LECTURE ({@link IChannelPolicy}) lues par
+     *   security ; seules exigées au `subscribe`.
+     * @param admission - instance de la classe d'admission quand `policy.allow`
+     *   en est une ; ignorée sinon.
+     * @param write - exigences d'ÉCRITURE, exigées EN PLUS de la lecture sur une
+     *   trame entrante ; `null` : ce nom n'en déclare pas.
+     * @throws BootConfigurationError Classe d'admission sans instance ; `allow`
+     *   sur une écriture qui rencontre une lecture différente ; écriture distincte
+     *   face à un verrou qui ne sait pas la juger.
+     */
+    registerChannelPolicy(name: string, policy: IChannelPolicy, admission?: IChannelAdmission, write?: IChannelPolicy | null): void;
+    /**
+     * Déclare la lecture et/ou l'écriture d'un nom en les AJOUTANT à ce qu'il déclarait — une sorte posée remplace la sienne, une sorte `null` garde celle d'avant. Voie des décorateurs (`channelPolicyRegistry.ts#registerControllerPolicies`). Cold path.
+     *
+     * @param name - nom exact ou motif.
+     * @param read - lecture déclarée, ou `null`.
+     * @param write - écriture déclarée, ou `null`.
+     * @param admission - instance de la classe d'admission désignée par l'une ou
+     *   l'autre ; ignorée sinon.
+     * @throws BootConfigurationError Mêmes refus que {@link RealtimeHub.registerChannelPolicy}.
+     */
+    declareChannelPolicy(name: string, read: IChannelPolicy | null, write: IChannelPolicy | null, admission?: IChannelAdmission): void;
+    /**
+     * Pose le défaut FERMÉ d'une action (`{ authenticated: true }`) — son ÉCRITURE tant que rien d'exact ne déclare son nom et qu'aucun motif ne pose d'écriture ; une lecture de motif s'y ajoute sans l'ouvrir. Idempotent : une poignée de main n'en paie qu'une lecture.
+     *
+     * @param name - nom de l'action.
      */
-    registerChannelPolicy(name: string, policy: IChannelPolicy): void;
+    declareActionDefault(name: string): void;
     /**
      * Nombre maximum de `*` dans un motif.
      *
@@ -459,6 +745,51 @@ export declare class RealtimeHub {
      * la frame `subscribe`/inbound. O(1), 0 alloc quand le registre est vide.
      */
     resolveChannelPolicy(name: string): IChannelPolicy | null;
+    /**
+     * Lecture ET écriture qui s'appliquent à ce nom, en UNE résolution — `null` si aucune politique ne le couvre (ADR-0022 §6, décision 1 quater).
+     *
+     * Même résolution que {@link resolveChannelPolicy} : l'entrée la plus
+     * spécifique (nom exact, puis motif) gouverne les deux sortes. Rendue telle
+     * quelle : aucune allocation, une seule recherche par trame jugée.
+     *
+     * @param name - nom du canal, de la méthode entrante ou de l'action.
+     */
+    resolveChannelPolicies(name: string): IChannelPolicies | null;
+    /**
+     * Retient la PREMIÈRE classe qui déclare une sorte de politique sous ce nom, et rend celle qui l'avait déjà déclarée — pour refuser au démarrage deux classes en désaccord.
+     *
+     * @param name - nom exact ou motif.
+     * @param kind - sorte déclarée : lecture ou écriture.
+     * @param owner - constructeur du contrôleur qui déclare.
+     * @param policy - la politique déclarée.
+     * @returns la déclaration antérieure de cette sorte, ou `null`.
+     */
+    claimChannelPolicy(name: string, kind: "read" | "write", owner: object, policy: IChannelPolicy): IChannelPolicyClaim | 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;
+    /**
+     * Ce nom EXACT porte-t-il une déclaration — motifs ignorés ?
+     *
+     * @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 +797,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 :
@@ -495,25 +826,53 @@ export declare class RealtimeHub {
      * @param factory - {@link ChannelFactory} qui crée le provider partagé.
      */
     registerSystemChannel(channel: string, factory: ChannelFactory): void;
+    /**
+     * Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
+     *
+     * @param limits - bornes de débit et de taille, ou `null` pour refermer le canal.
+     */
+    setClientLogsLimits(limits: IClientLogsLimits | null): void;
+    /** Bornes en vigueur, ou `null` si le canal montant est fermé. */
+    get clientLogsLimits(): IClientLogsLimits | null;
+    /**
+     * La raison d'un refus du verrou, quand il sait la dire — `null` sinon, ou si l'explication lève.
+     *
+     * Chemin FROID : appelé après un refus, jamais par trame acceptée. Le
+     * verdict, lui, est déjà rendu : une explication fautive ne change rien à la
+     * décision, elle se tait.
+     *
+     * @param frame - la trame refusée.
+     * @param peer - la connexion qui l'a émise.
+     * @returns la phrase, ou `null`.
+     */
+    explainDenial(frame: unknown, peer: JsonRpcPeer): string | null;
     /**
      * Pont hot-path entre `JsonRpcPeer.beforeDispatch` et le verrou métier : lit
      * le token déjà caché du peer (O(1), 0 lecture base) puis délègue à
-     * l'authorizer. `true` (autorisée) si aucun verrou posé (bypass 0-coût) —
-     * mais en pratique `beforeDispatch` n'est branché que si `hasFrameAuthorizer()`.
+     * l'authorizer. `true` (autorisée) si aucun verrou posé : `beforeDispatch`
+     * est armé sur TOUTE connexion, et c'est ici que le bypass se paie — un
+     * appel et une comparaison de champ.
      *
      * @param frame - frame JSON-RPC entrante (brute) à autoriser.
      * @param peer  - peer émetteur (clé du mapping `peer → token`).
      * @returns `true` si la frame peut être dispatchée, `false` si refusée.
      */
+    runAuthorizer(frame: unknown, peer: JsonRpcPeer): boolean;
     /**
-     * Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
+     * Inscrit une connexion qui vient de retenir son premier « oui » du verrou.
      *
-     * @param limits - bornes de débit et de taille, ou `null` pour refermer le canal.
+     * Appelé par `gateFrame`, jamais par trame chaude ; à équilibrer par
+     * {@link untrackRetainedVerdicts} à la fermeture.
+     *
+     * @param state - état de la connexion.
      */
-    setClientLogsLimits(limits: IClientLogsLimits | null): void;
-    /** Bornes en vigueur, ou `null` si le canal montant est fermé. */
-    get clientLogsLimits(): IClientLogsLimits | null;
-    runAuthorizer(frame: unknown, peer: JsonRpcPeer): boolean;
+    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 +892,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