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

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,41 @@
+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.
+ * Chaque nom est déclaré au hub SORTE PAR SORTE (lecture, écriture), sans
+ * héritage : le hub les fusionne avec les motifs de toutes les classes
+ * (ADR-0022 §6, décision 1 quater). Deux classes qui déclarent la même sorte
+ * différemment sous un même nom refusent le démarrage : la seconde effaçait la
+ * première sans un mot.
+ *
+ * @throws BootConfigurationError Politique illisible ou contredite, `allow`
+ *   posé sur une action ou sur une écriture distincte de la lecture, classe
+ *   d'admission non résolue, ou deux classes en désaccord sur un nom.
+ */
+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/channelPolicyResolution.d.ts

@@ -0,0 +1,112 @@
+import { type IChannelAdmission, type IChannelPolicies } from "nodefony";
+import type { IChannelPolicy } from "../../interfaces/IChannelPolicy.js";
+import type { IChannelAdmissionRule } from "./connectionAdmission.js";
+/**
+ * Politiques qui s'appliquent à un nom, résolues : la LECTURE, l'ÉCRITURE quand elle en diffère, et — quand la lecture porte `allow` — la règle d'admission prête à appeler.
+ *
+ * Satisfait {@link IChannelPolicies} : le hub la rend telle quelle au juge, sans
+ * allocation.
+ */
+export interface IChannelPolicyEntry extends IChannelPolicies {
+    readonly admission: IChannelAdmissionRule | null;
+}
+/**
+ * Ce qu'UNE déclaration (nom exact ou motif) pose sur un nom, par sorte — et sa vue seule, calculée une fois.
+ *
+ * `read` et `write` sont `null` quand cette déclaration ne pose pas la sorte :
+ * la résolution la cherche alors dans une déclaration plus générale
+ * (ADR-0022 §6, décision 1 quater). `fallback` est le défaut fermé d'une action
+ * sans politique : son écriture tant que rien d'exact ne déclare le nom et
+ * qu'aucun motif ne pose d'écriture.
+ */
+export interface IPolicyDeclaration {
+    readonly read: IChannelPolicy | null;
+    readonly write: IChannelPolicy | null;
+    readonly fallback: IChannelPolicy | null;
+    /** Instance de la classe d'admission désignée par l'une des politiques, gardée pour une fusion ultérieure. */
+    readonly instance: IChannelAdmission | undefined;
+    /** Vue de cette déclaration seule, ou `null` si elle ne pose rien. */
+    readonly self: IChannelPolicyEntry | null;
+}
+/** Déclaration portée par un MOTIF de nom (`chat:room:*`), compilée et pesée. */
+export interface IPatternDeclaration extends IPolicyDeclaration {
+    readonly source: string;
+    readonly re: RegExp;
+    /** Longueur du littéral (`*` retirés) : le plus spécifique d'abord. */
+    readonly weight: number;
+}
+/**
+ * Règle d'admission prête à appeler d'une politique, ou `null` sans `allow`.
+ *
+ * Une flèche se retient telle quelle. Une classe exige son instance — résolue au
+ * démarrage, jamais ici : le hub n'a pas d'injecteur, et résoudre à la première
+ * poignée de main laisserait sans politique un exemplaire qui n'émet que des
+ * webhooks. La méthode est liée une fois, et la règle se construit une fois :
+ * le `subscribe` n'alloue rien et n'appelle qu'une fonction.
+ *
+ * @throws BootConfigurationError La politique désigne une classe d'admission et
+ *   aucune instance de CETTE classe n'est fournie.
+ */
+export declare function admissionRuleOf(name: string, policy: IChannelPolicy, admission: IChannelAdmission | undefined): IChannelAdmissionRule | null;
+/**
+ * Construit une déclaration et sa vue seule : lecture déclarée, sinon l'écriture, sinon le défaut d'action ; écriture gardée seulement si elle exige autre chose que la lecture.
+ *
+ * @param name - nom exact ou motif (pour les messages).
+ * @param read - lecture déclarée, ou `null`.
+ * @param write - écriture déclarée, ou `null`.
+ * @param fallback - défaut fermé d'une action, ou `null`.
+ * @param admission - instance de la classe d'admission quand la politique qui
+ *   sert de lecture en désigne une.
+ */
+export declare function declarationOf(name: string, read: IChannelPolicy | null, write: IChannelPolicy | null, fallback: IChannelPolicy | null, admission: IChannelAdmission | undefined): IPolicyDeclaration;
+/**
+ * Politique INTÉGRÉE du canal personnel `user:<id>` (ADR-0022 §6, D1) — connexion authentifiée, admise sur SON canal seulement.
+ *
+ * Constante de module : elle ne s'inscrit nulle part, donc aucun `clear()`,
+ * aucun ordre de démarrage, aucun oubli ne peut la retirer. Elle sert de REPLI
+ * de LECTURE aux noms `user:…` : seule une déclaration qui vise `user:`
+ * (nom exact, ou motif dont le littéral commence par `user:`) la remplace — un
+ * motif attrape-tout (`*`) ne retire pas la garde « son canal seulement ».
+ */
+export declare const USER_CHANNEL_DECLARATION: IPolicyDeclaration;
+/**
+ * Résout les politiques d'un nom (ADR-0022 §6, décision 1 quater) : la LECTURE appartient à la déclaration la plus spécifique qui déclare quelque chose sur ce nom ; l'ÉCRITURE vient de la plus spécifique qui déclare une écriture.
+ *
+ * L'ordre de spécificité : le nom exact, puis les motifs du plus spécifique au
+ * plus général. Pourquoi deux règles et non une :
+ * - la LECTURE reste à la déclaration propriétaire du nom (déclarée, sinon
+ *   héritée de sa propre écriture) : une commande `task:start` déclarée par
+ *   `@RealtimeInbound` sous une famille `task:*` à `allow` ne devient pas un
+ *   canal à membres, et une écriture exacte ne voit pas sa lecture s'ouvrir par
+ *   un motif plus général ;
+ * - l'ÉCRITURE descend jusqu'au motif qui en déclare une : elle s'ajoute à la
+ *   lecture (une trame entrante exige les deux), elle ne peut que durcir — une
+ *   écriture de famille (`mix:*` réservée) n'est plus perdue sur un nom exact
+ *   qui ne déclare que sa lecture.
+ *
+ * Ensuite : un nom `user:…` sans déclaration qui le vise garde la politique
+ * intégrée du canal personnel (un motif qui ne vise pas `user:` est ignoré) ;
+ * une action sans politique (nom exact qui ne déclare rien) prend la lecture du
+ * motif qui la couvre et le défaut fermé pour écriture — un motif de lecture
+ * public ne l'ouvre donc pas.
+ *
+ * Rend la vue d'une déclaration quand une seule suffit (aucune allocation) ;
+ * n'alloue que si l'écriture vient d'une autre déclaration que la lecture.
+ *
+ * @param name - nom résolu.
+ * @param exact - déclaration exacte de ce nom, ou `undefined`.
+ * @param patterns - motifs, triés du plus spécifique au plus général, ou `null`.
+ * @returns les politiques, ou `null` si aucune ne couvre le nom.
+ */
+export declare function resolveDeclaredPolicies(name: string, exact: IPolicyDeclaration | undefined, patterns: readonly IPatternDeclaration[] | null): IChannelPolicyEntry | null;
+/**
+ * Défaut de l'ensemble des déclarations qui refuse le démarrage, ou `null` : une ÉCRITURE à `allow` qui s'appliquerait sous une lecture différente (son `allow` ne serait évalué nulle part), ou — face à un verrou qui ne juge pas l'écriture — une écriture qui diffère d'une lecture qu'elle peut rencontrer.
+ *
+ * Cold path (inscription d'une politique, pose du verrou) : toutes les paires.
+ *
+ * @param exact - déclarations exactes, par nom.
+ * @param patterns - déclarations par motif.
+ * @param writeJudged - le verrou en place sait juger l'écriture (ou aucun verrou).
+ * @returns le message du refus, ou `null`.
+ */
+export declare function policyDeclarationsDefect(exact: ReadonlyMap<string, IPolicyDeclaration> | null, patterns: readonly IPatternDeclaration[] | null, writeJudged: boolean): string | null;

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

@@ -0,0 +1,155 @@
+import type { IChannelPolicy, IPresenceView, IRealtimePresenceCount, IRealtimePresenceList, RealtimePresenceFrame } from "nodefony";
+import type { IPresenceChannelDelta, IPresenceChannelState } from "../backplane/presenceMessage.js";
+import type { ChannelFrame } from "./RealtimeHub.js";
+import type { IPresenceAggregate } from "./remotePresence.js";
+/**
+ * Fenêtre de regroupement des changements de présence vers le navigateur (ms) — front montant : le premier changement d'un canal calme part tout de suite, les suivants attendent la fin de la fenêtre (ADR-0025 P2 bis).
+ */
+export declare const PRESENCE_WINDOW_MS = 250;
+/** Seuil par défaut d'identités nommées au-delà duquel la trame ne porte que les nombres (ADR-0025 P2 bis). */
+export declare const DEFAULT_PRESENCE_MAX_NAMED = 1000;
+/** Réglages RÉSOLUS de la présence d'un canal — défauts appliqués. */
+export interface IPresenceSettings {
+    /** Délai de grâce d'un départ (ms), `0` = départs exacts. */
+    readonly grace: number;
+    /** Identités nommées au-delà desquelles la trame ne porte que les nombres. */
+    readonly maxNamed: number;
+}
+/**
+ * Ce qu'un observateur serveur lit de la présence d'un canal (`hub.presence()`, ADR-0025 P3) — les membres TOUJOURS, quel que soit le seuil de la trame.
+ *
+ * La forme est celle du cœur (`IPresenceView`), que le navigateur lit aussi : serveur et client voient le même objet.
+ */
+export type IChannelPresenceView = IPresenceView;
+/**
+ * Défaut de la valeur de la clé `presence` d'une politique, ou `null` si elle est recevable — en clair, pour que le refus au démarrage dise QUOI corriger.
+ *
+ * @param value - valeur de `policy.presence` (`unknown` : une politique se lit
+ *   depuis une métadonnée publique).
+ */
+export declare function presenceDefect(value: unknown): string | null;
+/**
+ * Réglages résolus de la présence qu'une politique déclare, ou `null` si elle n'en déclare pas.
+ *
+ * Précondition : la politique a passé {@link presenceDefect}.
+ */
+export declare function presenceSettingsOf(policy: IChannelPolicy | null | undefined): IPresenceSettings | null;
+/**
+ * Deux politiques déclarent-elles la même présence ? Défauts appliqués : `true` et `{ grace: 0 }` sont la même.
+ *
+ * Sert à refuser deux déclarations d'un même nom qui ne diffèrent que par la
+ * présence — une seule s'appliquerait. Démarrage seulement.
+ */
+export declare function samePresence(a: IChannelPolicy, b: IChannelPolicy): boolean;
+/**
+ * État de présence LOCAL d'un canal à présence (ADR-0025 P2 bis, P5) — identités nommées et onglets, connexions non nommées, version, changements en attente de la fenêtre, départs en grâce.
+ *
+ * Alloué au premier client d'un canal qui déclare `presence`, jamais pour un
+ * autre canal. Ne connaît ni l'horloge ni le protocole : le hub lui passe
+ * l'instant et fabrique les trames. Les changements portent des valeurs
+ * ABSOLUES (nombre d'onglets, départ), donc rejouer un changement déjà inclus
+ * dans une liste ne change rien — c'est ce qui permet de servir à un nouvel
+ * abonné la liste prise au dernier envoi, encodée une fois.
+ *
+ * Sur un canal DIFFUSÉ entre pods, c'est aussi l'agrégat de la vue des pairs
+ * ({@link IPresenceAggregate}) : les compteurs portent le TOTAL (local + pairs),
+ * et une table à part garde la seule part locale — ce que ce pod annonce à ses
+ * pairs, en deltas par lot. Ailleurs, cette table n'existe pas.
+ */
+export declare class ChannelPresence implements IPresenceAggregate {
+    #private;
+    readonly channel: string;
+    readonly settings: IPresenceSettings;
+    /** Canal diffusé entre pods : sa part locale part sur le bus, la vue des pairs s'y ajoute. */
+    readonly distributed: boolean;
+    /** Fin de la fenêtre de regroupement en cours (horloge monotone, ms). */
+    windowEnd: number;
+    /** Liste complète encodée, servie telle quelle jusqu'au prochain envoi. */
+    listFrame: ChannelFrame | null;
+    /** Le canal est-il encore tenu par le hub ? `false` après son retrait. */
+    live: boolean;
+    /**
+     * Fin de la synchronisation initiale avec les pairs (ms monotone) — la vue
+     * n'est que locale tant que la demande d'état du premier abonné n'a pas eu le
+     * temps d'être servie ; `0` = synchronisée (ou canal non diffusé).
+     */
+    syncUntil: number;
+    /**
+     * @param distributed - le canal est diffusé entre pods (bus branché, préfixe
+     *   diffusé) : la part locale est tenue à part pour le bus.
+     */
+    constructor(channel: string, settings: IPresenceSettings, distributed?: boolean);
+    /** La part locale a-t-elle changé depuis le dernier lot ? */
+    get busDirty(): boolean;
+    /** La vue est-elle connue incomplète (synchronisation initiale, trou chez un pair) ? */
+    get partial(): boolean;
+    /** Version courante de la vue (+1 par trame de changements). */
+    get version(): number;
+    /** Des changements attendent-ils un envoi ? */
+    get dirty(): boolean;
+    /**
+     * Une connexion entre.
+     *
+     * @param key - identité nommée, ou `null` pour une connexion non nommée.
+     */
+    join(key: string | null): void;
+    /**
+     * Une connexion sort.
+     *
+     * Un départ nommé attend la grâce du canal ; un départ non nommé est décompté
+     * tout de suite (rien ne reconnaîtrait son retour).
+     *
+     * @param key - même valeur qu'à {@link ChannelPresence.join}.
+     * @param now - instant monotone (ms), pour la grâce.
+     */
+    leave(key: string | null, now: number): void;
+    /** Publie les départs dont la grâce est écoulée. */
+    expire(now: number): void;
+    /** Prochaine échéance de grâce (ms monotone), `Infinity` sans départ retenu — O(1). */
+    nextDeadline(): number;
+    /**
+     * Trame complète à la version COURANTE — la liste, ou les nombres seuls au-delà du seuil.
+     *
+     * Une liste ne prend jamais de numéro : servie à un nouvel abonné, elle ferait
+     * voir un trou à tous les autres (ADR-0025 P2 bis).
+     */
+    listParams(): IRealtimePresenceList | IRealtimePresenceCount;
+    /**
+     * Consomme les changements en attente et rend la trame à envoyer à tous les membres, ou `null` s'il n'y en a pas.
+     *
+     * Sous le seuil : les changements, version +1. Au-delà : les nombres seuls,
+     * version inchangée (trame complète). Au retour sous le seuil : la liste.
+     * Toute trame envoyée périme la liste encodée.
+     */
+    takeChanges(): RealtimePresenceFrame | null;
+    /** Vue de l'observateur serveur : les membres toujours, une copie. */
+    view(): IChannelPresenceView;
+    /**
+     * Pose l'état « incomplet » de la vue ; un changement fait partir une trame (la version suit) et périme la liste encodée.
+     */
+    setPartial(partial: boolean): void;
+    /** {@inheritDoc IPresenceAggregate.remoteTabs} */
+    remoteTabs(key: string, delta: number): void;
+    /** {@inheritDoc IPresenceAggregate.remoteUnnamed} */
+    remoteUnnamed(delta: number): void;
+    /** {@inheritDoc IPresenceAggregate.remoteLeave} */
+    remoteLeave(key: string, tabs: number, now: number): void;
+    /**
+     * Consomme les changements de la part locale depuis le dernier lot et rend l'entrée du lot, en valeurs absolues — `null` s'ils s'annulent tous.
+     */
+    takeBusDelta(): IPresenceChannelDelta | null;
+    /** État COMPLET de la part locale, pour une réponse d'état (paires à plat). */
+    localState(): IPresenceChannelState;
+    /**
+     * Des départs LOCAUX attendent-ils la fin de leur grâce ? Le dernier client
+     * parti d'un pod n'y échappe pas : la présence reste servie au bus jusqu'à
+     * l'échéance (ADR-0025 P5), puis se libère.
+     */
+    get hasLocalGrace(): boolean;
+    /** La part locale compte-t-elle quelqu'un ? */
+    get hasLocal(): boolean;
+    /**
+     * Le canal n'est plus servi ici : toute la part locale part à zéro au prochain lot, pour que les pairs ne gardent aucun fantôme.
+     */
+    release(): void;
+}

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;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Une route montée, vue par le contrôle des routes de contrat : son chemin
+ * complet, les méthodes qu'elle accepte et les schémas qu'elle valide.
+ */
+export interface IMountedBridgeRoute {
+    /** Chemin complet, préfixe du contrôleur compris (`/chat/send`). */
+    readonly path: string;
+    /** Méthodes acceptées, en capitales ; `undefined` = aucune déclarée (tous les verbes HTTP, jamais la socket). */
+    readonly methods: ReadonlySet<string> | undefined;
+    /** Schémas d'entrée de l'action (`schema` de la route), ou `null`. */
+    readonly schema: {
+        readonly body?: unknown;
+        readonly query?: unknown;
+        readonly params?: unknown;
+    } | null;
+}
+/**
+ * Lit la table `serverRoutes` qu'une classe de contrôleur déclare en statique —
+ * `null` quand elle n'en déclare pas (aucun contrôle).
+ *
+ * @param ctor - la classe du contrôleur.
+ * @returns la table, ou `null`.
+ * @throws BootConfigurationError si la table n'est pas un objet.
+ */
+export declare function readContractRoutes(ctor: object): Record<string, unknown> | null;
+/**
+ * Vérifie, au démarrage, que chaque route du contrat est SERVIE par le pont :
+ * une route montée au même chemin, qui accepte le verbe par la socket, et dont
+ * les schémas sont LES MÊMES OBJETS que ceux que la table déclare. Coût nul par
+ * requête : la vérification n'a lieu qu'une fois.
+ *
+ * Sans elle, un contrat qui type `chat.post("/chat/send", …)` compilerait
+ * contre une route absente, servie en HTTP seulement, ou validant un autre
+ * schéma — et l'erreur n'apparaîtrait qu'au premier appel.
+ *
+ * @param owner - nom de la classe qui déclare la table (pour le message).
+ * @param table - la table `serverRoutes` (`"<VERBE> <chemin>"` → `{ body?, query? }`).
+ * @param mounted - les routes montées.
+ * @throws BootConfigurationError à la première entrée qui n'est pas servie ;
+ *   le message nomme la classe, l'entrée et la cause.
+ */
+export declare function assertContractRoutes(owner: string, table: Record<string, unknown>, mounted: readonly IMountedBridgeRoute[]): void;

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

@@ -23,3 +23,9 @@
 export declare function deniedDetail(env: string | undefined | null, detail: string): {
     detail?: string;
 };
+/**
+ * Le détail d'un refus part-il au client dans ce mode ? Hors production seulement — la règle de {@link deniedDetail}, lue AVANT de rédiger la phrase : en production, aucune chaîne n'est composée pour être jetée.
+ *
+ * @param env - le mode du kernel serveur, s'il est connu ; une absence vaut production.
+ */
+export declare function explainsDenials(env: string | undefined | null): boolean;

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

@@ -0,0 +1,66 @@
+import type { IJsonRpcNotification, IJsonRpcRequest } from "nodefony";
+import type { IRealtimeConnectionState } from "../../interfaces/IRealtimeConnectionState.js";
+import type { RealtimeHub } from "./RealtimeHub.js";
+/**
+ * Verdicts du verrou retenus par connexion, au plus (ADR-0022 §6, décision 1 ter).
+ *
+ * Borne la table qu'un client remplit en poussant sur des canaux entrants : au-delà,
+ * le verrou est consulté à chaque trame, il n'est jamais contourné. Une admission
+ * par `allow` n'y est pas soumise — elle est déjà bornée par le plafond de canaux
+ * de la connexion.
+ */
+export declare const MAX_RETAINED_FRAME_VERDICTS = 64;
+/**
+ * Retire TOUTE admission d'un canal à la connexion — marque de sa règle ET verdict retenu du verrou — quand le serveur l'en éjecte ou le termine (ADR-0022 §6 décision 3).
+ *
+ * Plus fort que {@link releaseRuleAdmission}, qui garde le verdict du verrou :
+ * après une éjection, une trame entrante sur ce canal repasse par le verrou.
+ *
+ * @param state - état de la connexion.
+ * @param channel - canal dont la connexion est retirée.
+ */
+export declare function revokeAdmission(state: IRealtimeConnectionState, channel: string): void;
+/**
+ * Retire l'admission d'un canal à la fin de son abonnement quand elle en dépendait — celle d'un canal à `allow`, dont l'abonnement est la condition.
+ *
+ * Un verdict du verrou sur un canal SANS `allow` ne tient qu'à l'identité et
+ * survit au désabonnement ; sur un canal à `allow`, il ne valait que le temps
+ * de l'abonnement (ADR-0022 §6, décisions 1 et 1 quater).
+ *
+ * @param state - état de la connexion.
+ * @param channel - canal quitté.
+ * @param hub - hub qui porte les règles d'admission.
+ */
+export declare function releaseRuleAdmission(state: IRealtimeConnectionState, channel: string, hub: RealtimeHub): void;
+/**
+ * Oublie les verdicts du verrou retenus par la connexion — leur politique vient
+ * de changer. Ceux des canaux à `allow` compris : une écriture inscrite après
+ * coup doit être jugée à la trame suivante, abonnement ou pas. `allow`, lui,
+ * n'est pas redemandé — l'abonnement reste.
+ *
+ * @param state - état de la connexion.
+ */
+export declare function dropRetainedVerdicts(state: IRealtimeConnectionState): void;
+/**
+ * Juge une trame entrante que la connexion n'a pas admise d'office (ADR-0022 §6, décision 1 ter).
+ *
+ * Dans l'ordre :
+ * - une REQUÊTE (action, `api.request`) passe par le verrou, toujours ;
+ * - `ping` et `unsubscribe` passent sans règle ;
+ * - `subscribe` passe par le verrou (`allow` est jugé après, à l'ouverture) ;
+ * - un nom hérité du prototype de la table entrante est refusé ;
+ * - un canal entrant à `allow` exige l'abonnement de CETTE connexion (`allow`
+ *   n'est jamais rappelé), puis passe par le verrou comme les autres ;
+ * - un canal entrant passe par le verrou — lecture ET écriture —, dont le « oui »
+ *   est retenu ;
+ * - toute autre notification passe par le verrou.
+ *
+ * Le premier test du contrôleur (`admitted[method] === true`) a déjà écarté les trames
+ * admises : rien ici n'est sur le chemin d'une trame chaude.
+ *
+ * @param state - état de la connexion.
+ * @param frame - trame déjà classée par le pair.
+ * @param hub - hub qui porte le verrou et les règles.
+ * @returns `true` si la trame peut être distribuée.
+ */
+export declare function gateFrame(state: IRealtimeConnectionState, frame: IJsonRpcRequest | IJsonRpcNotification, hub: RealtimeHub): boolean;