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

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

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

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

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

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

@@ -1,4 +1,5 @@
 import type { RealtimeClosedReason } from "nodefony";
+import type { ChannelFrame } from "./RealtimeHub.js";
 /**
  * Ce que la poignée d'une connexion demande au contrôleur qui la sert — imposer
  * un abonnement, y mettre fin. Implémenté par `RealtimeController`, une fois par
@@ -14,4 +15,6 @@ export interface IRealtimeConnectionHost {
      * @returns `false` si la connexion n'est pas abonnée à ce canal.
      */
     end(channel: string, reason: RealtimeClosedReason): boolean;
+    /** Écrit une trame partagée, encodée pour le codec de cette connexion. */
+    send(frame: ChannelFrame): void;
 }

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

@@ -3,6 +3,23 @@ import type { ContextType } from "@nodefony/http";
 import { Controller } from "@nodefony/framework";
 import type { ControllerScope } from "@nodefony/framework";
 import type { IRealtimeController, RealtimePublish, RealtimeInboundHandlers, RealtimeActionHandler } from "../../interfaces/IRealtimeController.js";
+/**
+ * Préfixe de la ligne `ERROR` écrite quand la poignée de main lève (socket fermée
+ * en 1011). Le harnais de test la relit pour citer l'exception : le client, lui,
+ * ne reçoit que « internal error » — rien d'interne ne sort par la socket.
+ */
+export declare const HANDSHAKE_FAILED_LOG = "WS realtime handshake failed";
+/**
+ * L'attente d'un `Retry-After` (RFC 9110 §10.2.3), en secondes : un délai
+ * (`120`) tel quel, une date HTTP ramenée à l'écart avec `now` (jamais
+ * négatif). Une valeur illisible, ou absente, ne dit rien : `null`.
+ *
+ * @param value - l'en-tête posé par l'action, s'il l'a été
+ * @param now - l'instant de référence d'une date HTTP, en ms (défaut : l'horloge,
+ *   lue seulement pour une date)
+ * @returns les secondes à attendre, ou `null`
+ */
+export declare function retryAfterSeconds(value: string | undefined, now?: number): number | null;
 /**
  * RealtimeController — base d'un endpoint WebSocket temps réel SERVEUR (JSON-RPC 2.0).
  *
@@ -340,7 +357,8 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * mutualisé tant que Ph.6 n'a pas tranché).
      *
      * Erreurs → {@link RpcError} (`data.status` = statut HTTP équivalent) :
-     * `-32602` params invalides, 404 path inconnu, 408 timeout d'action…
+     * `-32602` params invalides, 404 path inconnu, 408 timeout d'action… Un
+     * `Retry-After` posé par l'action part en `data.retryAfter` (secondes).
      * Tout autre throw de l'action reste opaque (`-32603`, Zero Trust).
      */
     private invokeApiRequest;

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

@@ -1,7 +1,8 @@
 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, UserChannelPayload } from "nodefony";
+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";
@@ -33,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
@@ -179,6 +193,17 @@ export declare class ChannelFrame {
  * 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).
  *
@@ -272,6 +297,38 @@ 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.
      *
@@ -578,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;
@@ -621,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 :
      *
@@ -634,24 +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 `*`.
-     * 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 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.
-     * @throws BootConfigurationError La politique désigne une classe d'admission
-     *   et aucune instance de CETTE classe n'est fournie.
+     * @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): void;
+    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.
+     */
+    declareActionDefault(name: string): void;
     /**
      * Nombre maximum de `*` dans un motif.
      *
@@ -669,6 +745,26 @@ 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.
      *
@@ -689,7 +785,7 @@ export declare class RealtimeHub {
      */
     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.
+     * Ce nom EXACT porte-t-il une déclaration — motifs ignorés ?
      *
      * @param name - nom d'action ou de canal.
      */
@@ -730,16 +826,6 @@ export declare class RealtimeHub {
      * @param factory - {@link ChannelFactory} qui crée le provider partagé.
      */
     registerSystemChannel(channel: string, factory: ChannelFactory): void;
-    /**
-     * 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()`.
-     *
-     * @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.
-     */
     /**
      * Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
      *
@@ -748,6 +834,29 @@ export declare class RealtimeHub {
     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é : `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;
     /**
      * Inscrit une connexion qui vient de retenir son premier « oui » du verrou.

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

@@ -17,8 +17,15 @@ export type AdmissionResolver = (admissionClass: ChannelAdmissionClass, channel:
  * @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.
+ * 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;
 /**

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;