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

package/dist/nodefony/testing/presenceClient.js

@@ -0,0 +1,54 @@
+import { RealtimeConnection } from "../src/server/RealtimeConnection.js";
+import { PresenceView, REALTIME_PRESENCE_METHOD, isPresenceFrame, ownField } from "nodefony";
+// nodefony/testing/presenceClient.ts
+/**
+* Abonne à `channel` une connexion de `hub` — nommée `user`, ou anonyme (`null`) — et relève les trames de présence qu'elle reçoit, lues et appliquées par le lecteur et la vue du cœur, comme le ferait un navigateur. Une trame que le lecteur refuse est un défaut du serveur : le banc lève en la citant.
+*/
+function presenceClient(hub, channel, user) {
+	const frames = [];
+	const outcomes = [];
+	const view = new PresenceView(channel);
+	const codec = hub.textFrameCodec;
+	const conn = new RealtimeConnection({
+		impose: () => {},
+		end: () => false,
+		send: (frame) => {
+			const data = frame.encodeFor(codec);
+			if (typeof data !== "string") return;
+			const msg = JSON.parse(data);
+			if (ownField(msg, "method") !== REALTIME_PRESENCE_METHOD) return;
+			const params = ownField(msg, "params");
+			if (!isPresenceFrame(params)) throw new Error(`trame de présence mal formée : ${data}`);
+			frames.push(params);
+			outcomes.push(view.apply(params));
+		}
+	}, () => ({
+		type: user === null ? "anonymous" : "test",
+		authenticated: user !== null,
+		id: user,
+		userIdentifier: user ?? "anon.",
+		roles: [],
+		scopes: [],
+		issuer: null,
+		account: user !== null
+	}));
+	const sink = () => {};
+	if (!hub.subscribeClient(channel, sink, () => () => {}, void 0, conn)) throw new Error(`abonnement à « ${channel} » refusé`);
+	hub.presenceSubscribed(channel, conn);
+	return {
+		frames,
+		outcomes,
+		view,
+		leave: () => {
+			hub.unsubscribe(channel, sink);
+		}
+	};
+}
+/** Présents nommés d'un canal vus par `hub` (identité → onglets), triés. */
+function presenceView(hub, channel) {
+	const v = hub.presence(channel);
+	const out = {};
+	if (v !== null) for (const [k, e] of [...v.members].sort(([a], [b]) => a.localeCompare(b))) out[k] = e.tabs;
+	return out;
+}
+export { presenceClient, presenceView };

package/dist/types/index.d.ts

@@ -27,7 +27,7 @@ import RealtimeController from "./nodefony/src/server/RealtimeController.js";
 import ServerRealtimeSocket, { serverSocket } from "./nodefony/src/server/ServerRealtimeSocket.js";
 import RealtimeHub, { getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel } from "./nodefony/src/server/RealtimeHub.js";
 import LoopbackBackplane from "./nodefony/src/backplane/LoopbackBackplane.js";
-import RedisBackplane, { createRedisServiceTransport, resolveRedisChannel, REDIS_RT_CHANNEL } from "./nodefony/src/backplane/RedisBackplane.js";
+import RedisBackplane, { createRedisServiceTransport, resolveRedisChannel, resolveRedisBytesChannel, REDIS_RT_CHANNEL } from "./nodefony/src/backplane/RedisBackplane.js";
 import { resolveBackplaneOriginId } from "./nodefony/src/backplane/originId.js";
 import ClusterBackplane, { processIpcTransport } from "./nodefony/src/backplane/ClusterBackplane.js";
 import { registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers } from "./nodefony/src/backplane/backplaneRegistry.js";
@@ -70,26 +70,58 @@ declare class Realtime extends Module<IRealtimeConfig> {
      * `onKernelBoot` court donc avant et garantit l'ordre.
      */
     onKernelBoot(): Promise<this>;
+    /**
+     * Phase `onReady` — inscrit au hub les politiques de canal de TOUS les contrôleurs temps réel connus, et résout leurs classes d'admission, avant que le moindre serveur n'écoute.
+     *
+     * Pas à `onKernelBoot` : chaque module enregistre ses contrôleurs dans SON
+     * `onBoot` (`@controllers`), et ceux d'un module listé après celui-ci n'y
+     * seraient pas encore. `onReady` passe après tous les `onBoot` et avant
+     * `initServers` : aucune poignée de main ne précède l'inscription, et un
+     * exemplaire qui n'émet que des webhooks a ses politiques comme les autres.
+     *
+     * @throws BootConfigurationError Politique illisible, `allow` sur une
+     *   action, classe d'admission sans singleton, sans `allow` ou dont une
+     *   dépendance manque — la classe et le canal sont nommés.
+     */
+    onKernelReady(): Promise<this>;
+    /**
+     * Les routes montées par le routeur du framework, vues par le contrôle des
+     * routes de contrat : chemin, méthodes, schémas d'entrée.
+     *
+     * @returns la liste, vide si le routeur du framework est absent.
+     */
+    private mountedRoutes;
 }
 export default Realtime;
 export { Realtime };
-export { RealtimeController, ServerRealtimeSocket, serverSocket, RealtimeHub, getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel, LoopbackBackplane, ClusterBackplane, RedisBackplane, createRedisServiceTransport, resolveRedisChannel, resolveBackplaneOriginId, REDIS_RT_CHANNEL, registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers, processIpcTransport, ClusterProbeClient, setClusterProbeClient, processProbeTransport, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, WsConnectionTransport, createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth, RealtimeService, };
-export { ANONYMOUS_REALTIME_TOKEN } from "./nodefony/src/server/AnonymousRealtimeToken.js";
+export { RealtimeController, ServerRealtimeSocket, serverSocket, RealtimeHub, getRealtimeHub, SLOW_CONSUMER_BYTES, RESERVED_SYSTEM_PREFIXES, isReservedSystemChannel, LoopbackBackplane, ClusterBackplane, RedisBackplane, createRedisServiceTransport, resolveRedisChannel, resolveRedisBytesChannel, resolveBackplaneOriginId, REDIS_RT_CHANNEL, registerBackplaneDriver, getBackplaneDriver, listBackplaneDrivers, processIpcTransport, ClusterProbeClient, setClusterProbeClient, processProbeTransport, clusterProbeHealth, clusterProbeRequestEnrich, clusterProbeInstance, mergeClusterHealth, WsConnectionTransport, createRealtimeAdminApi, buildRealtimeHealth, buildOwnHealth, RealtimeService, };
+export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_SUBSCRIBER_IDENTITY, } from "./nodefony/src/server/AnonymousRealtimeToken.js";
 export { defineRealtimeConfig, realtimeConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
 export type { IRealtimeConfig, IRealtimeConfigInput, } from "./nodefony/config/defineModuleConfig.js";
-export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, getDeclaredBroadcastPrefixes, } from "./nodefony/decorators/realtimeDecorators.js";
+export { RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, RealtimePolicy, getDeclaredBroadcastPrefixes, } from "./nodefony/decorators/realtimeDecorators.js";
 export type { RealtimeChannelFactory } from "./nodefony/decorators/realtimeDecorators.js";
-export type { IRealtimeController, RealtimePublish, RealtimeInboundHandler, } from "./nodefony/interfaces/IRealtimeController.js";
+export { ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict, } from "./nodefony/src/server/ContractRealtimeController.js";
+export type { ContractRealtimeMethodHandlers, ContractPolicyNames, RealtimeContractOf, } from "./nodefony/src/server/ContractRealtimeController.js";
+export type { IContractRealtimeHub } from "./nodefony/src/server/RealtimeHub.js";
+export type { IRealtimeController, RealtimePublish, ContractRealtimePublish, RealtimeInboundHandler, TypedRealtimeInboundHandler, RealtimeInboundHandlers, RealtimeActionHandler, } from "./nodefony/interfaces/IRealtimeController.js";
 export type { IChannelPolicy } from "./nodefony/interfaces/IChannelPolicy.js";
 export type { IRealtimeConnectionState } from "./nodefony/interfaces/IRealtimeConnectionState.js";
+export type { IRealtimeConnection } from "./nodefony/interfaces/IRealtimeConnection.js";
 export type { IClientLogsLimits } from "./nodefony/interfaces/IClientLogsLimits.js";
 export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from "./nodefony/src/server/syslogUplink.js";
 export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.js";
-export type { ChannelSink, ChannelFactory, } from "./nodefony/src/server/RealtimeHub.js";
+export type { ChannelSink, ChannelFactory, ChannelFrameBuilder, } from "./nodefony/src/server/RealtimeHub.js";
+export { ChannelFrame } from "./nodefony/src/server/RealtimeHub.js";
+export { PRESENCE_WINDOW_MS, DEFAULT_PRESENCE_MAX_NAMED, } from "./nodefony/src/server/channelPresence.js";
+export type { IChannelPresenceView } from "./nodefony/src/server/channelPresence.js";
 export type { IBackplane, IBackplaneMessage, BackplaneHandler, IBackplaneInfo, } from "./nodefony/interfaces/IBackplane.js";
 export type { IClusterBackplaneTransport, ClusterBackplaneEnvelope, } from "./nodefony/src/backplane/ClusterBackplane.js";
-export type { IRedisBackplaneTransport, IRedisPublisher, IRedisSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
+export type { IRedisBackplaneTransport, IRedisPublisher, IRedisSubscriber, IRedisBytesSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
 export type { BackplaneFactory, IBackplaneFactoryContext, } from "./nodefony/src/backplane/backplaneRegistry.js";
+export { sealBackplaneEnvelope, openBackplaneEnvelope, BackplaneEcho, } from "./nodefony/src/backplane/envelope.js";
+export { BACKPLANE_STOP_TIMEOUT_MS, shutdownRealtime, } from "./nodefony/src/server/realtimeShutdown.js";
+export { BackplanePublishQueue, DEFAULT_MAX_QUEUE_BYTES, type BackplaneNotice, type BackplaneNoticeSeverity, } from "./nodefony/src/backplane/publishQueue.js";
+export { BackplaneIngress } from "./nodefony/src/backplane/ingress.js";
 export type { IClusterProbeTransport } from "./nodefony/src/cluster/ClusterProbeClient.js";
 export type { RawWsConnection } from "./nodefony/src/transport/WsConnectionTransport.js";
 export type { IRealtimeProbe, IRealtimeHealth, IRealtimeClusterHealth, IRealtimeChannelStat, IRealtimeConnProbe, } from "./nodefony/interfaces/IRealtimeProbe.js";

package/dist/types/nodefony/config/config.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 export declare const realtimeConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
+    codec: z.ZodDefault<z.ZodEnum<{
+        cbor: "cbor";
+        json: "json";
+    }>>;
     backplane: z.ZodDefault<z.ZodObject<{
         driver: z.ZodDefault<z.ZodString>;
         namespace: z.ZodOptional<z.ZodString>;
@@ -18,6 +22,11 @@ export declare const realtimeConfigSchema: z.ZodObject<{
     limits: z.ZodDefault<z.ZodObject<{
         maxChannelsPerConnection: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
+    authenticateTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    allowTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxPendingAllowsPerConnection: z.ZodDefault<z.ZodNumber>;
+    maxPendingAllowsTotal: z.ZodDefault<z.ZodNumber>;
+    publicOrigin: z.ZodOptional<z.ZodString>;
     csrf: z.ZodDefault<z.ZodObject<{
         checkOrigin: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/types/nodefony/decorators/realtimeDecorators.d.ts

@@ -19,9 +19,40 @@
  *  `undefined` (pas d'allocation), fallback sur les overrides classiques.
  */
 import "reflect-metadata";
-import type { RpcActionHandler } from "nodefony";
+import type { ChannelAdmissionClass, ChannelAllow, RpcActionHandler } from "nodefony";
 import type { RealtimePublish, RealtimeInboundHandler } from "../interfaces/IRealtimeController.js";
 import type { IChannelPolicy } from "../interfaces/IChannelPolicy.js";
+import type { ContractPolicyNames, RealtimeContractOf } from "../src/server/ContractRealtimeController.js";
+/**
+ * `allow` désigne-t-il une classe d'admission (`@injectable`) plutôt qu'une flèche ?
+ *
+ * Tranché par la métadonnée `@injectable`, jamais par le texte de la fonction
+ * (`class …`), qu'un minifieur réécrit (ADR-0021 §S10 bis).
+ *
+ * @param allow - valeur du membre `allow` d'une politique déjà validée.
+ * @returns `true` pour une classe à résoudre par l'injecteur.
+ */
+export declare function isAdmissionClass(allow: ChannelAllow): allow is ChannelAdmissionClass;
+/**
+ * Défaut d'une politique de canal, ou `null` si elle est recevable — en clair, pour que le refus au démarrage dise QUOI corriger.
+ *
+ * @param value - valeur lue sous la métadonnée des politiques (`unknown` :
+ *   `Reflect.defineMetadata` est public).
+ * @returns la raison du refus, ou `null`.
+ */
+export declare function channelPolicyDefect(value: unknown): string | null;
+/**
+ * Deux politiques exigent-elles exactement la même chose ? Structurel : deux littéraux identiques écrits dans deux classes le sont ; `allow` se compare par référence.
+ *
+ * Sert à refuser deux déclarations CONTRADICTOIRES d'un même nom (une seule
+ * s'appliquerait) sans refuser deux déclarations ÉQUIVALENTES, et à ne juger
+ * l'écriture que si elle diffère de la lecture. Démarrage seulement.
+ *
+ * @param a - une politique recevable.
+ * @param b - une politique recevable.
+ * @returns `true` si aucun pair ne peut satisfaire l'une sans l'autre.
+ */
+export declare function samePolicy(a: IChannelPolicy, b: IChannelPolicy): boolean;
 /**
  * Politique appliquée à une action RPC dont l'auteur n'a rien déclaré :
  * **exiger une connexion authentifiée**. Une action est une méthode que le pair
@@ -62,9 +93,12 @@ export type RealtimeChannelFactory = (channel: string, publish: RealtimePublish)
  * défaut, toute action applicative serait publique sans que rien ne le dise.
  * Pour une action délibérément ouverte, l'écrire : `{ authenticated: false }`.
  *
- * Si une politique est **déjà déclarée sous ce nom** (canal homonyme via
- * `@RealtimeChannel`/`@RealtimeInbound`), elle est conservée : le défaut ne
- * rétrograde jamais une politique existante, souvent plus stricte.
+ * Une politique d'action est une politique d'**écriture** : l'appel exige aussi
+ * la lecture déclarée sous le même nom. Sans politique, l'action **hérite** de la
+ * lecture d'un canal homonyme (`@RealtimeChannel`) si elle existe — le défaut ne
+ * rétrograde jamais une politique déclarée —, et sinon du défaut fermé, quel que
+ * soit l'ordre des méthodes. Deux politiques explicites différentes sur le même
+ * nom (action et `@RealtimeInbound`) refusent le démarrage.
  *
  * ⚠️ Le NOM peut primer sur ta politique : le plancher système de
  * `@nodefony/security` réserve les préfixes plateforme (`kernel:`, `syslog:`…)
@@ -90,16 +124,66 @@ export type RealtimeChannelFactory = (channel: string, publish: RealtimePublish)
  */
 export declare function RealtimeAction(method: string, policy?: IChannelPolicy): MethodDecorator;
 /**
- * Décorateur **méthode** — expose un **canal pub/sub** sous le nom `channel`
- * (match EXACT, sans préfixe `:<ms>` ni regex). La méthode décorée DOIT renvoyer
- * un `dispose: () => void` (la base le mémorise et l'appelle au dernier
+ * Noms d'une table de politiques absents du contrat de la classe décorée —
+ * `never` quand tous y sont, ou que la classe n'a pas de contrat.
+ */
+type NamesNotInContract<P, T> = [RealtimeContractOf<T>] extends [never] ? never : Exclude<keyof P, ContractPolicyNames<RealtimeContractOf<T>>>;
+/**
+ * Contrainte posée sur la classe décorée : aucune si les noms sont tous dans le
+ * contrat ; sinon un membre `notInContract` exigé, que l'erreur affiche avec les
+ * noms fautifs.
+ */
+type PolicyNamesCheck<P, T> = [NamesNotInContract<P, T>] extends [never] ? unknown : {
+    readonly notInContract: NamesNotInContract<P, T>;
+};
+/**
+ * Décorateur de **classe** — pose les politiques d'accès d'actions ou de canaux
+ * par leur NOM, sans déclarer de handler.
+ *
+ * C'est la voie des actions servies par la table de `realtimeActions()` : cette
+ * table ne sait pas porter de politique, et un `@RealtimeAction` ajouté pour la
+ * seule politique ferait fabriquer, à chaque connexion, un handler aussitôt
+ * écrasé par la table (et contournerait l'injection de ses paramètres décorés).
+ * Ici, rien par connexion : les politiques sont écrites UNE fois, à la
+ * définition de la classe, dans le même registre que celles des décorateurs de
+ * méthode. Une action de la table sans politique garde le défaut FERMÉ
+ * (connexion authentifiée).
+ *
+ * Un nom qui porte `*` est un motif (famille de canaux), comme partout ailleurs.
+ *
+ * La politique vaut pour la LECTURE et l'ÉCRITURE du nom (le même objet, jugé
+ * une fois). Elle prime sur le défaut fermé d'une action ; contredire une
+ * politique explicite d'un décorateur de méthode refuse le démarrage.
+ *
+ * **Sur un contrôleur de contrat** (`extends ContractRealtimeController<C>`), le
+ * décorateur lit le contrat sur la classe qu'il décore : chaque nom doit être
+ * une méthode ou un canal de `C`, sinon la classe ne compile pas, et l'erreur
+ * nomme le fautif (`notInContract`). Le contrat ne se répète pas. Sur un
+ * contrôleur sans contrat, tout nom est accepté. Vérification à la compilation
+ * seulement : coût d'exécution nul.
+ *
+ * @param policies - nom d'action ou de canal → politique.
+ *
+ * @example
+ *   @RealtimePolicy({ "orders:quote": { roles: ["ROLE_SALES"] } })
+ *   class OrdersRt extends ContractRealtimeController<OrdersContract> { … }
+ */
+export declare function RealtimePolicy<P extends {
+    readonly [name: string]: IChannelPolicy | undefined;
+}>(policies: P): <T extends abstract new (...args: never[]) => object>(target: T & PolicyNamesCheck<P, T>) => void;
+/**
+ * Décorateur **méthode** — expose un **canal pub/sub** sous le nom `channel`, ou
+ * une FAMILLE de canaux sous un motif (`chat:room:*`). La méthode décorée DOIT
+ * renvoyer un `dispose: () => void` (la base le mémorise et l'appelle au dernier
  * désabonné, comme avec l'override classique).
  *
- * v1 — match EXACT uniquement. Les canaux à pattern (`/^nodefony:orm:rich@(\d+)/`) ou à
- * suffixe de granularité (`nodefony:dashboard:1000`) restent dans l'override
- * `createRealtimeChannel()` (la base donne PRIORITÉ aux décorateurs, puis tombe
- * sur l'override en fallback — coexistence sans casse). Un mode `pattern: RegExp`
- * arrivera plus tard sans rompre cette API.
+ * Un motif (`*` = toute suite de caractères, la grammaire des politiques) sert
+ * chaque nom qu'il couvre : `@RealtimeChannel("chat:room:*", { allow })` déclare
+ * la règle ET la fabrique de tous les salons, et la méthode reçoit le nom réel
+ * (`chat:room:42`) en premier argument. Ordre de résolution au `subscribe` : le
+ * nom exact décoré, puis l'override `createRealtimeChannel()` (canaux à suffixe
+ * de granularité, regex — un contrôleur qui en a un garde son comportement),
+ * puis les motifs décorés, du plus spécifique au plus général.
  *
  * Le `this` est lié à l'instance ; le factory peut donc lire `this.kernel`, etc.
  * Mais ATTENTION : un provider est **partagé** entre toutes les connexions au
@@ -107,8 +191,20 @@ export declare function RealtimeAction(method: string, policy?: IChannelPolicy):
  * créé. Capturer des **valeurs long-lived** (broker, syslog) dans la closure,
  * jamais `this.context` (lié à la connexion créatrice qui peut fermer).
  *
+ * La `policy` est celle de **LECTURE** : exigée au `subscribe`, et en plus de
+ * l'écriture sur toute trame entrante du même nom. Absente, la lecture hérite de
+ * l'écriture (`@RealtimeInbound`) si elle est déclarée — une application qui ne
+ * garde que l'écriture reste protégée en lecture. Pour un canal que tout le
+ * monde lit et que seuls certains écrivent, l'écrire : `{ authenticated: false }`.
+ *
  * @example
  *   class ChatController extends RealtimeController {
+ *     // Tous les salons : la règle et la fabrique, une seule fois.
+ *     @RealtimeChannel("chat:room:*", { allow: RoomAdmission })
+ *     room(_channel: string): () => void {
+ *       return () => {};
+ *     }
+ *
  *     @RealtimeChannel("chat:room42")
  *     room42(_channel: string, publish: RealtimePublish): () => void {
  *       const timer = setInterval(() => publish("chat:room42", { ts: Date.now() }), 1000);
@@ -129,6 +225,20 @@ export declare function RealtimeChannel(channel: string, policy?: IChannelPolicy
  * pousser tant qu'aucun handler n'est enregistré ici). Cf seam P13.8a
  * (`beforeDispatch`) pour la gate sécurité par voter P6.
  *
+ * La `policy` est celle d'**ÉCRITURE** : une trame entrante exige la LECTURE du
+ * même nom (`@RealtimeChannel`) ET elle — l'écriture n'est jamais moins stricte
+ * que la lecture. Sans lecture déclarée, la lecture en hérite.
+ *
+ * @example
+ *   class ChatController extends RealtimeController {
+ *     @RealtimeChannel("chat:typing", { authenticated: false }) // tout le monde lit
+ *     typing(_channel: string, _publish: RealtimePublish): () => void {
+ *       return () => {};
+ *     }
+ *     @RealtimeInbound("chat:typing", { authenticated: true }) // seuls les connectés écrivent
+ *     onTyping(): void {}
+ *   }
+ *
  * @example
  *   class ChatController extends RealtimeController {
  *     @RealtimeInbound("chat:send")
@@ -161,14 +271,84 @@ export type RealtimeActionWrapper = (method: RealtimeActionMethod, propertyKey:
 export declare function getRealtimeActions(instance: object, wrap?: RealtimeActionWrapper): Record<string, RpcActionHandler> | null;
 /** Lecture (lazy, au handshake) du registre des canaux décorés. */
 export declare function getRealtimeChannels(instance: object): Record<string, RealtimeChannelFactory> | null;
+/**
+ * La fabrique décorée sous un MOTIF qui couvre `channel` — `@RealtimeChannel("chat:room:*")` sert `chat:room:42` —, ou `null` si aucun motif ne le couvre.
+ *
+ * Même grammaire que les politiques (`compileChannelPattern`) et même
+ * départage (`channelPatternWeight`, le plus spécifique d'abord) : un nom
+ * reçoit la fabrique du motif dont il reçoit la règle. Un motif refusé par la
+ * grammaire (trop d'étoiles) ne sert rien — le hub le dit déjà au démarrage.
+ * Cold path : appelé au premier abonné d'un canal qu'aucun nom exact ni
+ * `createRealtimeChannel` ne produit.
+ *
+ * @param instance - le contrôleur ; ses motifs se lisent sur sa classe.
+ * @param channels - le registre rendu par {@link getRealtimeChannels}.
+ * @param channel - le nom demandé.
+ */
+export declare function patternChannelFactory(instance: object, channels: Readonly<Record<string, RealtimeChannelFactory>> | null, channel: string): RealtimeChannelFactory | null;
 /** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */
 export declare function getRealtimeInbound(instance: object): Record<string, RealtimeInboundHandler> | null;
 /**
- * Lecture (lazy, au handshake) des politiques d'autorisation déclarées
- * (`@RealtimeChannel`/`@RealtimeInbound` avec opts). `null` si aucune → le
- * controller n'enregistre rien au hub (0 alloc). Donnée pure (pas de `bind` :
- * une policy n'est pas une méthode), renvoyée telle quelle pour publication au
- * hub realtime, qui l'expose à `@nodefony/security`.
+ * La classe déclare-t-elle une ACTION (`@RealtimeAction`) sous ce nom ? Sert à refuser un `allow` posé sur une action, que rien n'appliquerait.
+ *
+ * @param ctor - constructeur du contrôleur.
+ * @param name - nom d'action ou de canal.
+ */
+export declare function declaresAction(ctor: object, name: string): boolean;
+/** Ce qu'une classe DÉCLARE sous un nom, par sorte — `null` : elle ne pose pas cette sorte. */
+export interface IDeclaredPolicyKinds {
+    readonly read: IChannelPolicy | null;
+    readonly write: IChannelPolicy | null;
+}
+/**
+ * Politiques déclarées par une classe de contrôleur (ADR-0022 §6, décision 1 quater) : ce qu'elle pose par sorte — que le hub résout ensuite avec les motifs des autres classes — et sa vue seule.
+ */
+export interface IDeclaredChannelPolicies {
+    /** Vue de la classe SEULE, nom → politique de LECTURE (déclarée, sinon son écriture, sinon le défaut fermé d'une action). */
+    readonly read: Record<string, IChannelPolicy>;
+    /** Nom → ce que la classe déclare, sorte par sorte (sans héritage : le hub le calcule, motifs compris). */
+    readonly kinds: Record<string, IDeclaredPolicyKinds>;
+    /** Noms des actions décorées : chacune reçoit le défaut fermé comme REPLI au hub. */
+    readonly actions: readonly string[];
+}
+/**
+ * Politiques déclarées sur une CLASSE de contrôleur, validées et résolues par sorte — lues au démarrage du noyau, jamais par trame.
+ *
+ * Résolution indépendante de l'ordre des méthodes :
+ * - l'écriture d'un nom est celle déclarée (`@RealtimeInbound`, `@RealtimeAction`
+ *   avec politique, `@RealtimePolicy`) ; pour une action SANS politique, le
+ *   défaut fermé, sauf si une lecture est déclarée — l'action en hérite alors ;
+ * - la lecture est celle déclarée (`@RealtimeChannel`, `@RealtimePolicy`),
+ *   sinon l'écriture : une application qui ne garde que l'écriture reste
+ *   protégée en lecture ;
+ * - `kinds` garde ce que la classe déclare, SANS héritage : le hub le fusionne
+ *   avec les motifs de toutes les classes, sorte par sorte.
+ *
+ * @param ctor - constructeur du contrôleur.
+ * @returns les deux tables, ou `null` si la classe ne déclare aucune politique.
+ * @throws BootConfigurationError Une politique est illisible, ou deux
+ *   déclarations d'une même sorte se contredisent : la classe, le canal et le
+ *   défaut sont nommés.
+ */
+export declare function getDeclaredChannelPolicies(ctor: object): IDeclaredChannelPolicies | null;
+/**
+ * Politiques de LECTURE déclarées sur une CLASSE de contrôleur (`@RealtimeChannel`/`@RealtimeInbound`/`@RealtimeAction`/`@RealtimePolicy`), validées — lues au démarrage du noyau, jamais par trame.
+ *
+ * La lecture d'un nom est celle exigée au `subscribe` ; une écriture distincte
+ * se lit par {@link getDeclaredChannelPolicies}.
+ *
+ * @param ctor - constructeur du contrôleur.
+ * @returns nom de canal ou de méthode → politique de lecture, ou `null` si la
+ *   classe n'en déclare aucune.
+ * @throws BootConfigurationError Une politique est illisible ou contredite :
+ *   la classe, le canal et le défaut sont nommés.
+ */
+export declare function getChannelPoliciesOf(ctor: object): Record<string, IChannelPolicy> | null;
+/**
+ * Politiques déclarées sur la classe d'une instance de contrôleur — même lecture que {@link getChannelPoliciesOf}.
+ *
+ * @param instance - contrôleur instancié.
+ * @returns nom → politique, ou `null` si aucune.
  */
 export declare function getRealtimeChannelPolicies(instance: object): Record<string, IChannelPolicy> | null;
 /**
@@ -205,3 +385,4 @@ export declare function getDeclaredBroadcastPrefixes(): string[];
 export declare function applyDeclaredBroadcastPrefixes(hub: {
     markBroadcastChannel(prefix: string): void;
 }): void;
+export {};

package/dist/types/nodefony/interfaces/IBackplane.d.ts

@@ -25,22 +25,9 @@
  *
  * Cf vision « la socket Nodefony » + mémoire `project_cluster_backplane_vision`.
  */
-/**
- * Compteurs de la **file d'envoi** d'un backplane à transport réseau : ce qui est
- * publié mais pas encore acquitté par le bus. Sans borne, cette file (interne au
- * client réseau) grossit sans limite sous rafale — d'où le seuil et ses compteurs,
- * exposés jusqu'à la sonde et Studio. Cf `BackplanePublishQueue`.
- */
-export interface IBackplaneQueueInfo {
-    /** Octets publiés en attente d'acquittement par le transport (instantané). */
-    bytes: number;
-    /** Seuil au-dessus duquel une publication est jetée ; `0` = illimité. */
-    maxBytes: number;
-    /** Publications JETÉES faute de place (monotone). `0` en régime sain. */
-    droppedTotal: number;
-    /** Publications REFUSÉES par le transport (bus coupé…) (monotone). */
-    failedTotal: number;
-}
+import type { IFrameCodec } from "nodefony";
+import type { IBackplaneInfo, IBackplaneQueueInfo } from "nodefony";
+export type { IBackplaneInfo, IBackplaneQueueInfo };
 /**
  * Message transporté entre pairs par le backplane. Sérialisé une fois à l'émission
  * (IPC `structuredClone` / Redis JSON) ; le `payload` doit donc être structurellement
@@ -60,44 +47,32 @@ export interface IBackplaneMessage {
  * condition (mais en fan-out **local only**).
  */
 export type BackplaneHandler = (msg: IBackplaneMessage) => void;
-/**
- * **Carte d'identité** d'un backplane — descripteur de DONNÉE (pas un log) décrivant
- * l'état du fond de panier. Source unique alimentant trois sorties cohérentes : la
- * ligne stdout au boot, le champ `backplane` de la sonde (`/api/health`) et la vue
- * Studio. Réutilisable par les tests / un agent IA sans dupliquer la connaissance
- * « c'est quoi ce backplane ».
- */
-export interface IBackplaneInfo {
-    /** Nom du driver (clé du registre). Ex. `redis`, `cluster`, `loopback`. */
-    driver: string;
-    /** Nature du transport. Ex. `redis-pubsub`, `ipc`, `local`. */
-    kind: string;
-    /** Identité de CE pair (process/pod). Ex. `String(process.pid)`. */
-    originId: string;
-    /** `true` si le fan-out franchit les frontières de pod (multi-host). */
-    crossPod: boolean;
-    /** Canal/topic de transport, si applicable (canal Redis, topic Kafka). */
-    channel?: string;
-    /**
-     * Les messages sont-ils **scellés** (authenticité de l'émetteur vérifiée) ?
-     * Renseigné par les drivers à transport PARTAGÉ, où un tiers peut écrire :
-     * `false` y signale un bus ouvert. Absent quand la question n'a pas de sens
-     * (mono-process, IPC master↔workers — authentifié par construction).
-     */
-    sealed?: boolean;
-    /**
-     * État de la **file d'envoi** vers le bus (octets en vol, seuil, jetés). Renseigné
-     * par les drivers à transport RÉSEAU, dont les publications sont acquittées de
-     * façon asynchrone : c'est là qu'un bus lent fait grossir la mémoire du pod.
-     * `droppedTotal > 0` = du fan-out cross-pod a été sacrifié pour tenir la mémoire.
-     * Absent quand le transport n'a pas de file (mono-process, IPC synchrone).
-     */
-    queue?: IBackplaneQueueInfo;
-}
 /**
  * Contrat d'un backplane realtime. Implémentation **stateless du point de vue métier**
  * (l'état des canaux vit dans le hub) ; le backplane ne porte que le transport vers les
  * pairs + son identité.
+ *
+ * Exigences d'un driver (ADR-0022 §6, décision 4) — aucune ne se voit à la
+ * compilation, toutes se perdent en silence :
+ *
+ *  - **chaque pair reçoit TOUT** : sur un journal partitionné, un groupe de lecteurs
+ *    PAR pair — un groupe partagé répartirait les messages entre serveurs ;
+ *  - **l'ordre par émetteur** est tenu : clé de partition = `originId`, jamais le
+ *    canal (ADR-0021 S5) ;
+ *  - **aucun rejeu au démarrage** : lire à partir du dernier message, jamais depuis le
+ *    début — un ordre de fin rejoué couperait une partie rouverte ;
+ *  - **aucune attente de regroupement** à l'émission : `publish` part tout de suite ;
+ *  - **un ordre de contrôle n'est jamais jeté pour faire place aux publications**
+ *    (`PLATFORM_BUS_CHANNELS.control` : terminer un canal, éjecter un compte) —
+ *    une file d'envoi bornée lui laisse une voie hors quota ; un ordre perdu malgré
+ *    tout (bus injoignable) se compte et s'annonce, jamais en silence ;
+ *  - **le sceau appliqué** dès que le bus quitte la machine (`crossPod`) :
+ *    `sealBackplaneEnvelope` à l'émission, `openBackplaneEnvelope` à la réception ;
+ *  - `start` après `stop` remet la réception en route sans doubler les messages ;
+ *  - la dépendance npm du transport vit dans le driver, jamais au cœur.
+ *
+ * Un driver s'y prouve par la suite de conformité, la même que jouent les drivers
+ * livrés : `runBackplaneConformance` de `@nodefony/realtime/testing`.
  */
 export interface IBackplane {
     /** Identité stable de CE pair (process/pod). Discrimine l'echo. Ex. `String(process.pid)`. */
@@ -117,7 +92,27 @@ export interface IBackplane {
      * Un seul handler à la fois — un appel ultérieur remplace le précédent.
      */
     onMessage(handler: BackplaneHandler): void;
-    /** Arrête le transport et libère les ressources (connexions, listeners). Idempotent. */
+    /**
+     * Arme le transport des **octets** (ADR-0021 S6) : après un `true`, une charge qui
+     * est ou contient un `Uint8Array` traverse {@link publish} intacte jusqu'aux autres
+     * pairs. Appelé par le hub, une fois, quand le serveur a un codec binaire.
+     *
+     * Optionnel : un driver qui ne l'implémente pas — ou qui rend `false` — garde ses
+     * messages texte inchangés, et le hub retient les octets sur ce serveur en
+     * prévenant l'exploitant une fois, plutôt que de les laisser se déformer.
+     *
+     * @param codec - le codec binaire du serveur (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+     * @returns `true` si les octets traverseront le bus intacts.
+     */
+    enableBytes?(codec: IFrameCodec): boolean;
+    /**
+     * Arrête le transport et libère les ressources (connexions, listeners). Idempotent.
+     *
+     * Un transport asynchrone laisse d'abord partir ce qui est déjà émis (la promesse
+     * se résout une fois ces envois acquittés ou refusés) : à l'arrêt du processus,
+     * la preuve de vie finale de la présence part juste avant, et la sortie suit au
+     * tick suivant. L'appelant borne l'attente (`shutdownRealtime`).
+     */
     stop(): void | Promise<void>;
     /**
      * Carte d'identité du backplane (driver, transport, origine, cross-pod, canal).

package/dist/types/nodefony/interfaces/IChannelPolicy.d.ts

@@ -1,28 +1,8 @@
 /**
- * Politique d'autorisation d'un **canal** WebSocket — exigences à satisfaire
- * pour s'y abonner (`subscribe`) ou y pousser (canal inbound full-duplex).
+ * Politique d'autorisation d'un canal — déclaration UNIQUE, au cœur (`nodefony`).
  *
- * Déclarée côté métier via {@link RealtimeChannel}/{@link RealtimeInbound}
- * (`@RealtimeChannel("admin:x", { roles: ["ROLE_ADMIN"] })`), agrégée par le
- * {@link RealtimeHub} et **lue par `@nodefony/security`** (P6) au moment de la
- * frame via le seam `resolveChannelPolicy`. Le module realtime NE décide PAS de
- * l'autorisation (il ne connaît ni la hiérarchie de rôles ni l'identité réelle) :
- * il ne fait que **transporter la déclaration** jusqu'au décideur (le firewall).
- *
- * ⚠️ Cette interface est un **miroir structurel** de `IChannelPolicy` côté
- * `@nodefony/security` (`realtimeContracts.ts`) — les deux modules ne s'importent
- * pas (`package.json` disjoints). Le typage structurel de TS fait le pont à
- * l'exécution. Toute dérive de forme casserait le seam silencieusement.
- *
- * Champs cumulatifs (ET) ; un champ absent = pas de contrainte sur cet axe ;
- * objet entièrement vide = canal libre (équivaut à « pas de politique »).
+ * Réexportée ici pour que `import type { IChannelPolicy } from "@nodefony/realtime"`
+ * continue de compiler. Elle n'est plus recopiée : `@nodefony/security`, qui la
+ * juge, lit la même déclaration — deux copies dérivaient en silence.
  */
-export interface IChannelPolicy {
-    /** Exige une connexion authentifiée (token non anonyme). */
-    readonly authenticated?: boolean | undefined;
-    /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles, côté security). */
-    readonly roles?: readonly string[] | undefined;
-    /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
-    readonly scopes?: readonly string[] | undefined;
-}
-export default IChannelPolicy;
+export type { IChannelPolicy, IChannelPolicy as default } from "nodefony";

package/dist/types/nodefony/interfaces/IRealtimeConnection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Une connexion temps réel servie par CE processus — la poignée qu'un
+ * gestionnaire `@RealtimeInbound` reçoit, et que les gestes du hub sur les
+ * membres d'un canal désignent (`RealtimeHub.subscribeConnection`,
+ * `RealtimeHub.evictConnection`, `RealtimeHub.channelMembers`).
+ *
+ * Elle n'existe que dans la mémoire du processus qui a accepté la socket : elle
+ * ne traverse pas le backplane, et un autre exemplaire (pod, `nodefony cluster
+ * -w N`) ne la connaît pas. Une poignée fermée, ou venue d'ailleurs, fait rendre
+ * `false` aux gestes du hub — jamais un geste muet.
+ */
+export interface IRealtimeConnection {
+    /**
+     * Identifiant du compte connecté (`RealtimeIdentity.id`) — la clé des canaux
+     * personnels et de `RealtimeHub.evictUser`, qui l'atteint sur tous les
+     * exemplaires ; `null` pour l'anonyme (qu'aucun ordre par compte n'atteint),
+     * et pour un authentificateur qui ne produit pas d'identité d'admission.
+     */
+    readonly userId: string | null;
+    /** `false` une fois la socket fermée : la poignée ne désigne plus rien. */
+    readonly open: boolean;
+}