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

package/dist/nodefony/src/server/RealtimeHub.js

@@ -1,6 +1,12 @@
+import { RealtimeConnection } from "./RealtimeConnection.js";
+import { AdmissionBudget } from "./admissionBudget.js";
+import { dropRetainedVerdicts } from "./frameAdmission.js";
+import { isAdmissionClass } from "../../decorators/realtimeDecorators.js";
 import { LoopbackBackplane } from "../backplane/LoopbackBackplane.js";
+import { readControlOrder } from "../backplane/controlOrder.js";
 import { ANONYMOUS_REALTIME_TOKEN } from "./AnonymousRealtimeToken.js";
-import { IDENTITY_REFRESH_CLOSE_CODE, NODEFONY_CHANNEL_NAMESPACE, REVOCATION_REVALIDATE_MS, RevocationWatch, isPlatformChannel } from "nodefony";
+import { BootConfigurationError, IDENTITY_DEAD_CLOSE_CODE, IDENTITY_REFRESH_CLOSE_CODE, MAX_CHANNEL_PATTERN_WILDCARDS, NODEFONY_CHANNEL_NAMESPACE, PLATFORM_BUS_CHANNELS, REVOCATION_REVALIDATE_MS, RevocationWatch, TOKEN_EXPIRED_CLOSE_CODE, USER_CHANNEL_PREFIX, compileChannelPattern, containsBytes, countWildcards, frameCodecSet, isOwnUserChannel, isPlatformChannel, isRealtimePayload, realtimePayloadError, userChannel } from "nodefony";
+import { frameRateRejectedTotal } from "@nodefony/http";
 // nodefony/src/server/RealtimeHub.ts
 /**
 * Seuil d'alerte slow-consumer (octets de `bufferedAmount`). Au-delà, la connexion
@@ -64,6 +70,132 @@ function channelFamily(channel) {
 	return i === -1 ? "*" : `${channel.slice(0, i + 1)}*`;
 }
 /**
+* Frame d'UNE publication diffusée à plusieurs abonnés, encodée **au plus une fois
+* par codec** (ADR-0022 §2) : un canal suivi par des connexions texte et CBOR paie
+* deux encodages, jamais un par connexion. L'encodage est paresseux — un codec
+* qu'aucun abonné n'utilise ne coûte rien.
+*
+* Deux places suffisent : un hub sert au plus son codec texte et son codec
+* binaire. Un troisième codec reste servi, sans mise en cache.
+*/
+var ChannelFrame = class {
+	message;
+	codecA;
+	dataA;
+	codecB;
+	dataB;
+	claimedA;
+	claimedB;
+	/** @param message - la frame protocolaire, telle que rendue par le {@link ChannelFrameBuilder}. */
+	constructor(message) {
+		this.message = message;
+		this.codecA = null;
+		this.dataA = void 0;
+		this.codecB = null;
+		this.dataB = void 0;
+		this.claimedA = false;
+		this.claimedB = false;
+	}
+	/**
+	* Rend la frame encodée pour un codec, en l'encodant à la première demande.
+	*
+	* @param codec - le codec de la connexion qui va l'écrire.
+	* @returns la trame à écrire telle quelle, ou `undefined` si la frame n'est pas
+	*   encodable : l'abonné qui en {@link ChannelFrame.claimFailure | réclame}
+	*   l'échec reprend son chemin habituel, qui porte le filet (journal).
+	*/
+	encodeFor(codec) {
+		if (codec === this.codecA) return this.dataA;
+		if (codec === this.codecB) return this.dataB;
+		let data;
+		try {
+			data = codec.encode(this.message);
+		} catch {
+			data = void 0;
+		}
+		if (this.codecA === null) {
+			this.codecA = codec;
+			this.dataA = data;
+		} else if (this.codecB === null) {
+			this.codecB = codec;
+			this.dataB = data;
+		}
+		return data;
+	}
+	/**
+	* Réclame l'échec d'encodage de cette frame pour un codec : `true` au PREMIER
+	* abonné qui le demande, `false` ensuite.
+	*
+	* Un seul abonné reprend alors son chemin habituel, dont le filet journalise
+	* l'échec ; les autres sautent la trame, qu'ils ne pourraient pas encoder non
+	* plus. Sans cela, une charge non encodable — un `$bytes` forgé par un client,
+	* une valeur cyclique — coûtait un encodage et une ligne de journal PAR abonné.
+	* Un codec hors des deux places réclame à chaque fois : il n'est pas retenu.
+	*
+	* @param codec - le codec dont {@link ChannelFrame.encodeFor} a rendu `undefined`.
+	* @returns `true` si l'appelant doit dire l'échec.
+	*/
+	claimFailure(codec) {
+		if (codec === this.codecA) {
+			if (this.claimedA) return false;
+			this.claimedA = true;
+			return true;
+		}
+		if (codec === this.codecB) {
+			if (this.claimedB) return false;
+			this.claimedB = true;
+			return true;
+		}
+		return true;
+	}
+};
+/**
+* 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.
+*/
+function admissionRuleOf(name, policy, admission) {
+	const allow = policy.allow;
+	if (allow === void 0) return null;
+	const anonymous = policy.anonymous === true;
+	if (!isAdmissionClass(allow)) return {
+		allow,
+		anonymous
+	};
+	if (!(admission instanceof allow)) throw new BootConfigurationError(`canal temps réel « ${name} » : la classe d'admission ${allow.name} n'a pas été résolue au démarrage du noyau. Son contrôleur doit être déclaré par @controllers dans un module : c'est là que le framework l'inscrit et résout ses dépendances.`);
+	return {
+		allow: admission.allow.bind(admission),
+		anonymous
+	};
+}
+/**
+* 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 :
+* une politique que l'application écrit sur `user:…` (nom exact ou motif)
+* l'emporte, comme toute déclaration explicite.
+*/
+const USER_CHANNEL_POLICY = Object.freeze({
+	policy: Object.freeze({
+		authenticated: true,
+		allow: isOwnUserChannel
+	}),
+	admission: Object.freeze({
+		allow: isOwnUserChannel,
+		anonymous: false
+	})
+});
+/**
+* Fabrique intégrée du canal personnel : il n'a pas de source, seul `publish`
+* l'alimente. Partagée par tous les canaux `user:` — aucune allocation par canal.
+*/
+const USER_CHANNEL_DISPOSE = () => {};
+/**
 * RealtimeHub — broker temps réel **PAR INSTANCE** (1 pod = 1 process = 1 hub local).
 *
 * Élève le realtime serveur du modèle **per-connexion** (chaque connexion son propre
@@ -94,15 +226,22 @@ var RealtimeHub = class RealtimeHub {
 	#channels = null;
 	#publishTotal = 0;
 	#fanoutTotal = 0;
+	#closedBytesSent = 0;
+	#closedMessagesSent = 0;
+	#closedDropped = 0;
+	#closedBinaryDiscarded = 0;
+	#closedMalformedDiscarded = 0;
 	#inboundTotal = 0;
 	#ingressRejectedTotal = 0;
+	#localOnlyTotal = 0;
 	#systemFloorDeniedTotal = 0;
 	#notice = null;
 	#noticed = null;
 	#connections = null;
 	#revocation = new RevocationWatch({
 		isValid: (entry) => entry.token.isValid?.(),
-		revoke: (entry) => entry.close(4001, "session revoked"),
+		status: (entry) => entry.token.status?.(),
+		revoke: (entry, status) => status === "expired" ? entry.close(TOKEN_EXPIRED_CLOSE_CODE, "token expired") : entry.close(IDENTITY_DEAD_CLOSE_CODE, "session revoked"),
 		identityOf: (entry) => entry.token.getUserIdentifier(),
 		refresh: (entry) => entry.close(IDENTITY_REFRESH_CLOSE_CODE, "identity changed")
 	});
@@ -111,8 +250,15 @@ var RealtimeHub = class RealtimeHub {
 	#peerTokens = null;
 	#frameAuthorizer = null;
 	#channelProbe = null;
+	#retainers = null;
 	#channelPolicies = null;
 	/**
+	* Classes de contrôleur dont les politiques sont déjà inscrites — `null`
+	* tant qu'aucune ne l'est. Une poignée de main n'en paie qu'un `has` :
+	* l'inscription elle-même n'a lieu qu'une fois par classe.
+	*/
+	#policyOwners = null;
+	/**
 	* Politiques déclarées par MOTIF de nom (`chat:room:*`), triées du plus
 	* spécifique au plus général, et `null` tant qu'aucune n'est déclarée.
 	*
@@ -133,6 +279,14 @@ var RealtimeHub = class RealtimeHub {
 	#originGuard = null;
 	#maxChannelsPerConnection = 256;
 	#slowConsumerBytes = SLOW_CONSUMER_BYTES;
+	#frameCodecs = frameCodecSet();
+	#busBytes = false;
+	/**
+	* Budget des admissions de l'exemplaire (appels d'`allow` en vol, coupe-circuit,
+	* `allowTimedOutTotal`/`allowSaturatedTotal`) — partagé par les files de toutes
+	* les connexions. Bornes posées par {@link setAdmissionLimits} au boot.
+	*/
+	admissionBudget = new AdmissionBudget();
 	#broadcastPrefixes = null;
 	/**
 	* Abonnement demandé par une **connexion cliente** — même chose que
@@ -148,9 +302,11 @@ var RealtimeHub = class RealtimeHub {
 	* sécurité en pose un, c'est lui qui décide (avec les rôles, ce que le hub ne
 	* sait pas faire) et le plancher s'efface.
 	*
+	* @param member - la connexion qui s'abonne : inscrite au registre du canal,
+	*   elle devient un membre identifiable ({@link channelMembers}).
 	* @returns `true` si abonné, `false` si canal inconnu ou fermé par le plancher.
 	*/
-	subscribeClient(channel, sink, factory, serialize) {
+	subscribeClient(channel, sink, factory, buildFrame, member) {
 		if (channel.includes("*")) {
 			this.#notifyOnce("wildcard-channel", `abonnement REFUSÉ au canal "${channel}" : le caractère « * » est réservé aux MOTIFS de politique et n'a pas de sens dans un nom de canal servi. Un motif garde une famille, il ne se souscrit pas.`);
 			return false;
@@ -160,7 +316,12 @@ var RealtimeHub = class RealtimeHub {
 			this.#notifyOnce("system-floor", `canal de plateforme "${channel}" REFUSÉ : aucun module de sécurité n'est chargé, donc aucune identité ne peut être vérifiée. Les namespaces réservés (${RESERVED_SYSTEM_PREFIXES.join(" ")}) sont fermés à toutes les connexions. Deux causes possibles : la sécurité n'est pas installée (charger @nodefony/security et déclarer une zone protégée), ou ce canal applicatif porte par erreur un préfixe réservé — dans ce cas, le renommer suffit.`);
 			return false;
 		}
-		return this.subscribe(channel, sink, factory, serialize);
+		if (!this.subscribe(channel, sink, factory, buildFrame)) return false;
+		if (member !== void 0) {
+			const st = this.#channels?.get(channel);
+			if (st !== void 0) (st.members ??= /* @__PURE__ */ new Map()).set(sink, member);
+		}
+		return true;
 	}
 	/**
 	* Abonne un consommateur qui **répond du canal** : il apporte la `factory`, donc
@@ -175,13 +336,13 @@ var RealtimeHub = class RealtimeHub {
 	*
 	* @returns `true` si abonné, `false` si canal inconnu (`factory` a renvoyé `null`).
 	*/
-	subscribe(channel, sink, factory, serialize) {
+	subscribe(channel, sink, factory, buildFrame) {
 		const channels = this.#channels ??= /* @__PURE__ */ new Map();
 		let st = channels.get(channel);
 		if (st) {
 			if (st.owned) {
 				st.sinks.add(sink);
-				if (st.serialize === null && serialize !== void 0) st.serialize = serialize;
+				if (st.buildFrame === null && buildFrame !== void 0) st.buildFrame = buildFrame;
 				return true;
 			}
 			st.sinks.add(sink);
@@ -192,14 +353,15 @@ var RealtimeHub = class RealtimeHub {
 			}
 			st.dispose = dispose;
 			st.owned = true;
-			if (serialize !== void 0) st.serialize = serialize;
+			if (buildFrame !== void 0) st.buildFrame = buildFrame;
 			return true;
 		}
 		st = {
 			dispose: null,
 			owned: false,
 			sinks: /* @__PURE__ */ new Set([sink]),
-			serialize: serialize ?? null,
+			members: null,
+			buildFrame: buildFrame ?? null,
 			messages: 0,
 			forward: this.#isBroadcast(channel)
 		};
@@ -238,7 +400,8 @@ var RealtimeHub = class RealtimeHub {
 			dispose: null,
 			owned: false,
 			sinks: /* @__PURE__ */ new Set([sink]),
-			serialize: null,
+			members: null,
+			buildFrame: null,
 			messages: 0,
 			forward: this.#isBroadcast(channel)
 		});
@@ -259,7 +422,8 @@ var RealtimeHub = class RealtimeHub {
 		const dispose = factory(channel, publishFn);
 		if (dispose !== null) return dispose;
 		const sys = this.#systemChannelFactories?.get(channel);
-		return sys ? sys(channel, publishFn) : null;
+		if (sys) return sys(channel, publishFn);
+		return channel.startsWith(USER_CHANNEL_PREFIX) ? USER_CHANNEL_DISPOSE : null;
 	}
 	/**
 	* Désabonne une connexion d'un canal. Au **dernier** abonné, `dispose()` le provider
@@ -270,6 +434,7 @@ var RealtimeHub = class RealtimeHub {
 		const st = channels?.get(channel);
 		if (!channels || !st) return;
 		st.sinks.delete(sink);
+		st.members?.delete(sink);
 		if (st.sinks.size === 0) {
 			try {
 				st.dispose?.();
@@ -278,6 +443,167 @@ var RealtimeHub = class RealtimeHub {
 		}
 	}
 	/**
+	* Les connexions abonnées à un canal par un client — **local à ce pod** : les membres servis par un autre exemplaire n'y figurent pas.
+	*
+	* Les écouteurs et services du serveur (`listen`, `subscribe`) ne sont pas
+	* des membres. Chemin froid : une copie à chaque appel.
+	*
+	* @param channel - nom exact du canal.
+	* @returns les membres de ce pod, vide si le canal n'en a aucun ici.
+	*/
+	channelMembers(channel) {
+		const members = this.#channels?.get(channel)?.members;
+		return members == null ? [] : Array.from(members.values());
+	}
+	/**
+	* Abonne d'office une connexion à un canal — **local à ce pod** : seule une connexion acceptée par ce processus peut l'être.
+	*
+	* Même porte qu'un `subscribe` du client (ADR-0022 §6 décision 2) : la
+	* politique fixe du canal (rôles, scopes, plancher de plateforme), puis sa
+	* règle `allow` s'il en déclare une. Un refus n'abonne pas, et seul
+	* l'appelant l'apprend ; jamais un abonnement qui contourne `allow` — le
+	* client rejoue ses abonnements à chaque reconnexion, et ce rejeu passe par
+	* `allow` : l'application écrit donc l'appartenance là où `allow` la lit.
+	*
+	* Le client est notifié par `realtime:subscribed { channel, imposed: true }`
+	* et inscrit le canal dans ses abonnements ; il peut le quitter.
+	*
+	* Plusieurs exemplaires : la requête qui décide doit atteindre le processus
+	* qui tient la socket — la passer par la socket elle-même (`@RealtimeInbound`,
+	* qui reçoit la connexion), ou faire autoriser l'entrée par `allow` (registre
+	* partagé) et laisser le navigateur s'abonner.
+	*
+	* @param channel - nom exact du canal.
+	* @param connection - la connexion à abonner (reçue par un gestionnaire `@RealtimeInbound`, ou lue dans {@link channelMembers}).
+	* @returns `true` une fois l'abonnement acquitté ; `false` si refusé, si la
+	*   connexion est fermée ou inconnue de ce processus, ou si le client s'en
+	*   désabonne avant le verdict.
+	*/
+	subscribeConnection(channel, connection) {
+		if (!(connection instanceof RealtimeConnection)) return Promise.resolve(false);
+		return connection.impose(channel);
+	}
+	/**
+	* Retire une connexion d'un canal — **local à ce pod** ; elle reçoit `realtime:closed { reason: "evicted" }`.
+	*
+	* ⚠️ **Éjecter coupe la connexion du canal, seul `allow` exclut**
+	* (ADR-0022 §6 décision 3). Le client ne rejoue pas un canal dont il a été
+	* éjecté, mais c'est une politesse : une page rechargée refait `subscribe`.
+	* Sur un canal à `allow`, l'éjecté revient si l'application n'a pas retiré
+	* l'appartenance là où `allow` la lit ; sur un canal sans `allow`, sa
+	* politique fixe le laisse rentrer.
+	*
+	* @param channel - nom exact du canal.
+	* @param connection - la connexion à retirer.
+	* @returns `false` si la connexion n'est pas membre du canal, est fermée, ou
+	*   inconnue de ce processus — jamais un geste muet.
+	*/
+	evictConnection(channel, connection) {
+		return connection instanceof RealtimeConnection && connection.end(channel, "evicted");
+	}
+	/**
+	* Termine un canal pour tous ses membres, **sur tous les serveurs** : chacun reçoit `realtime:closed { reason: "ended" }`, et le producteur est libéré.
+	*
+	* **Traverse les pods** : avec un backplane branché, l'ordre part sur le bus
+	* (`PLATFORM_BUS_CHANNELS.control`, scellé comme toute publication) et chaque
+	* serveur l'applique à SES membres. Livraison « au plus une fois » du bus :
+	* un pod qui manque l'ordre, ou qui démarre après, est rattrapé par la
+	* fabrique, qui rend `null` pour une instance terminée. Un canal de la
+	* plateforme (`nodefony:`) reste local — il décrit un pod, pas une partie.
+	*
+	* Les écouteurs du serveur (`listen`) restent inscrits, sur un canal redevenu
+	* PASSIF : le prochain `subscribe` d'un client rejoue la fabrique, et c'est
+	* elle qui tranche. **Seule la fabrique clôt un canal** (ADR-0021 S4) — le
+	* hub ne garde aucune marque « fermé » : une fabrique qui rend encore un
+	* producteur pour ce nom le rouvre. D'où la règle d'écriture d'un canal à
+	* durée de vie : son nom porte l'identifiant de l'instance
+	* (`room:42:<partie>`), et la fabrique rend `null` pour une instance terminée.
+	*
+	* @param channel - nom exact du canal.
+	* @returns le nombre de membres de CE pod à qui la fin a été notifiée — les
+	*   autres serveurs l'appliquent sans compte rendu.
+	*/
+	closeChannel(channel) {
+		this.#sendControl({
+			op: "close",
+			channel
+		});
+		return this.#closeLocal(channel);
+	}
+	/**
+	* Éjecte un compte d'un canal, **sur tous les serveurs** : chacune de ses connexions membres reçoit `realtime:closed { reason: "evicted" }`.
+	*
+	* Tous les onglets du compte sont visés, où qu'ils soient servis ; l'ordre
+	* traverse les pods comme {@link closeChannel}. ⚠️ **Éjecter coupe, seul
+	* `allow` exclut** (ADR-0022 §6 décision 3) : pour que le compte ne revienne
+	* pas, l'application retire l'appartenance là où `allow` la lit.
+	*
+	* ⚠️ Sur un bus PARTAGÉ, un tiers qui y écrit peut rejouer un ordre capté :
+	* sur un canal durable, il recouperait le compte à chaque réadmission (risque
+	* accepté et borné, ADR-0022 §6 d4) — bus privé exigé ; changer le secret du
+	* bus rend caducs les ordres déjà captés.
+	*
+	* @param channel - nom exact du canal.
+	* @param user - identifiant du compte (`IRealtimeConnection.userId`).
+	* @returns le nombre de connexions de CE pod éjectées. Un nom vide ou de plus
+	*   de 1 024 caractères n'éjecte rien et ne part pas sur le bus.
+	*/
+	evictUser(channel, user) {
+		if (!this.#sendControl({
+			op: "evictUser",
+			channel,
+			user
+		})) return 0;
+		return this.#evictUserLocal(channel, user);
+	}
+	/**
+	* Publie un ordre de contrôle aux autres serveurs — s'il y a un bus et que l'ordre a une forme que ses pairs acceptent.
+	*
+	* @returns `false` si l'ordre est mal formé (rien n'est appliqué nulle part).
+	*/
+	#sendControl(order) {
+		if (readControlOrder(order) === null) return false;
+		if (this.#backplane !== null && !isReservedSystemChannel(order.channel)) this.#backplane.publish(PLATFORM_BUS_CHANNELS.control, order);
+		return true;
+	}
+	/** Applique un ordre reçu du bus : forme vérifiée, canal de la plateforme refusé, sinon compté en rejet. */
+	#applyControl(payload) {
+		const order = readControlOrder(payload);
+		if (order === null || isReservedSystemChannel(order.channel)) {
+			this.#ingressRejectedTotal += 1;
+			return;
+		}
+		if (order.op === "close") this.#closeLocal(order.channel);
+		else this.#evictUserLocal(order.channel, order.user);
+	}
+	/** Éjecte de `channel` les connexions de CE pod dont le compte est `user`. */
+	#evictUserLocal(channel, user) {
+		const members = this.#channels?.get(channel)?.members;
+		if (members == null) return 0;
+		let evicted = 0;
+		for (const member of members.values()) if (member.userId === user && member.end(channel, "evicted")) evicted += 1;
+		return evicted;
+	}
+	/** Termine `channel` pour les membres de CE pod et libère son producteur. */
+	#closeLocal(channel) {
+		const st = this.#channels?.get(channel);
+		if (st === void 0) return 0;
+		let ended = 0;
+		const members = st.members;
+		if (members !== null) {
+			for (const member of members.values()) if (member.end(channel, "ended")) ended += 1;
+		}
+		const rest = this.#channels?.get(channel);
+		if (rest?.owned === true) {
+			try {
+				rest.dispose?.();
+			} catch {}
+			rest.dispose = null;
+			rest.owned = false;
+		}
+		return ended;
+	}
+	/**
 	* Publie une charge sur un canal : **fan-out local** **+** propagation conditionnelle
 	* au {@link IBackplane} (autres workers/pods). C'est le point d'entrée des providers
 	* locaux (tickers, listeners) ET de tout code serveur.
@@ -290,12 +616,65 @@ var RealtimeHub = class RealtimeHub {
 	*
 	* Anti-boucle : un message **reçu** du backplane ne repasse PAS par ici (il appelle
 	* `publishLocal` directement) → aucune ré-émission cross-process, pas de tempête.
+	*
+	* @param payload - objet, tableau ou octets ; omise = signal sans charge.
+	* @throws TypeError si la charge est un scalaire ou `null` ({@link isRealtimePayload},
+	*   ADR-0021 S1) — un scalaire se publie dans un objet (`{ value }`).
 	*/
 	publish(channel, payload) {
+		if (!isRealtimePayload(payload)) throw realtimePayloadError(channel, payload);
 		const st = this.#channels?.get(channel);
 		if (st !== void 0) this.#fanout(st, payload);
 		if (this.#backplane === null) return;
-		if (st !== void 0 ? st.forward : this.#isBroadcast(channel)) this.#backplane.publish(channel, payload);
+		if (!(st !== void 0 ? st.forward : this.#isBroadcast(channel))) {
+			this.#localOnlyTotal += 1;
+			return;
+		}
+		if (this.#busRefuses(payload)) {
+			this.#notifyOnce("backplane:binary", this.#busBytes ? `realtime: le canal « ${channel} » publie des octets hors \`Uint8Array\` — le bus entre serveurs ne porte que des \`Uint8Array\` : seuls les abonnés de ce serveur les reçoivent` : `realtime: le canal « ${channel} » publie des octets — sans codec binaire côté serveur (\`codec: "cbor"\`) ou sans backplane qui les porte, ils ne traversent pas le bus entre serveurs (ils y seraient déformés) : seuls les abonnés de ce serveur les reçoivent`);
+			return;
+		}
+		this.#backplane.publish(channel, payload);
+	}
+	/**
+	* Le bus refuse-t-il cette charge ? Un `Uint8Array` voyage quand le bus porte
+	* les octets ({@link #busBytes}) ; toute autre vue binaire, jamais.
+	*
+	* Sans bus binaire, le parcours en profondeur n'est payé que si un codec
+	* binaire est posé — seul cas où une charge à octets est légitime ; sans codec,
+	* seule la charge de premier niveau est examinée, comme avant le codec.
+	*/
+	#busRefuses(payload) {
+		const topLevel = ArrayBuffer.isView(payload) || payload instanceof ArrayBuffer;
+		if (this.#busBytes) return topLevel && !(payload instanceof Uint8Array);
+		if (this.#frameCodecs.binary !== null) return topLevel || containsBytes(payload);
+		return topLevel;
+	}
+	/** Arme les octets sur le bus quand codec binaire ET backplane sont posés, dans n'importe quel ordre. */
+	#armBusBytes() {
+		const codec = this.#frameCodecs.binary;
+		this.#busBytes = codec !== null && this.#backplane !== null && this.#backplane.enableBytes?.(codec) === true;
+	}
+	/**
+	* Livre une charge à UNE identité — tous ses onglets, tous les serveurs, et personne d'autre (ADR-0022 §6, D1).
+	*
+	* Publie sur son canal personnel `user:<userId>` : seuls les onglets de cette
+	* identité ont pu s'y abonner (politique intégrée, admission par égalité de
+	* chaîne), et le préfixe traverse le bus dès qu'un bus est branché. Rien à
+	* déclarer côté application. Personne n'écoute ? La charge est perdue, sans
+	* erreur : c'est une diffusion, pas une boîte aux lettres.
+	*
+	* @param userId - l'`id` STABLE du compte (`RealtimeIdentity.id`), jamais le
+	*   login.
+	* @param payload - objet, tableau ou octets ; omise = signal sans charge.
+	* @throws TypeError si la charge est un scalaire ou `null` (cf {@link publish}).
+	*/
+	publishToUser(userId, payload) {
+		this.publish(userChannel(userId), payload);
+	}
+	/** Préfixes déclarés diffusables entre serveurs, dans l'ordre de déclaration — lu par la ligne de démarrage. */
+	broadcastPrefixes() {
+		return this.#broadcastPrefixes ?? [];
 	}
 	/**
 	* Fan-out d'une charge aux **seuls abonnés locaux** d'un canal (process courant).
@@ -313,14 +692,14 @@ var RealtimeHub = class RealtimeHub {
 		this.#publishTotal += 1;
 		st.messages += 1;
 		this.#fanoutTotal += st.sinks.size;
-		let raw;
-		if (st.serialize !== null && st.sinks.size > 1) try {
-			raw = st.serialize(payload);
+		let frame;
+		if (st.buildFrame !== null && st.sinks.size > 1) try {
+			frame = new ChannelFrame(st.buildFrame(payload));
 		} catch {
-			raw = void 0;
+			frame = void 0;
 		}
 		for (const sink of st.sinks) try {
-			sink(payload, raw);
+			sink(payload, frame);
 		} catch {}
 	}
 	/**
@@ -365,7 +744,9 @@ var RealtimeHub = class RealtimeHub {
 	*/
 	setBackplane(backplane) {
 		this.#backplane = backplane;
+		this.markBroadcastChannel(USER_CHANNEL_PREFIX);
 		backplane.onMessage((msg) => this.#admitFromBackplane(msg));
+		this.#armBusBytes();
 		const started = backplane.start();
 		if (started instanceof Promise) started.catch((err) => {
 			if (this.#notice === null) throw err instanceof Error ? err : new Error(String(err));
@@ -390,8 +771,16 @@ var RealtimeHub = class RealtimeHub {
 	* nominale : un pair légitime n'émet que des canaux broadcast (`publish` filtre à
 	* la source), et un canal ne peut avoir d'abonné local que si l'endpoint qui le
 	* sert a été handshaké — donc ses préfixes déjà déclarés.
+	*
+	* Seule exception, AVANT ce contrôle : le canal de contrôle
+	* (`PLATFORM_BUS_CHANNELS.control`), jamais diffusé aux abonnés — ses ordres,
+	* en liste fermée, sont appliqués aux connexions de ce pod ou comptés en rejet.
 	*/
 	#admitFromBackplane(msg) {
+		if (msg.channel === PLATFORM_BUS_CHANNELS.control) {
+			this.#applyControl(msg.payload);
+			return;
+		}
 		if (!this.#isBroadcast(msg.channel)) {
 			this.#ingressRejectedTotal += 1;
 			return;
@@ -414,9 +803,18 @@ var RealtimeHub = class RealtimeHub {
 	registerConnection(conn) {
 		(this.#connections ??= /* @__PURE__ */ new Set()).add(conn);
 	}
-	/** Retire une connexion du registre de la sonde (au close). No-op si absente. */
+	/**
+	* Retire une connexion du registre de la sonde (au close) et verse ses cumuls à
+	* ceux des connexions fermées : les totaux de {@link probe} restent monotones.
+	* No-op si absente — une double sortie ne compte pas deux fois.
+	*/
 	unregisterConnection(conn) {
-		this.#connections?.delete(conn);
+		if (this.#connections?.delete(conn) !== true) return;
+		this.#closedBytesSent += conn.bytesSent;
+		this.#closedMessagesSent += conn.messagesSent;
+		this.#closedDropped += conn.dropped;
+		this.#closedBinaryDiscarded += conn.binaryDiscarded ?? 0;
+		this.#closedMalformedDiscarded += conn.malformedDiscarded ?? 0;
 	}
 	/**
 	* Inscrit une connexion à identité RÉVOCABLE au registre de
@@ -479,22 +877,32 @@ var RealtimeHub = class RealtimeHub {
 			messages: st.messages
 		});
 		let connectionCount = 0;
-		let bytesSentTotal = 0;
-		let messagesSentTotal = 0;
+		let bytesSentTotal = this.#closedBytesSent;
+		let messagesSentTotal = this.#closedMessagesSent;
 		let maxBufferedAmount = 0;
 		let totalBufferedAmount = 0;
 		let slowConsumers = 0;
-		let drops = 0;
+		let drops = this.#closedDropped;
+		let binaryDiscardedTotal = this.#closedBinaryDiscarded;
+		let malformedDiscardedTotal = this.#closedMalformedDiscarded;
 		if (this.#connections) for (const c of this.#connections) {
 			connectionCount += 1;
 			bytesSentTotal += c.bytesSent;
 			messagesSentTotal += c.messagesSent;
 			drops += c.dropped;
+			binaryDiscardedTotal += c.binaryDiscarded ?? 0;
+			malformedDiscardedTotal += c.malformedDiscarded ?? 0;
 			const buf = c.bufferedAmount;
 			if (buf > maxBufferedAmount) maxBufferedAmount = buf;
 			totalBufferedAmount += buf;
 			if (buf >= this.#slowConsumerBytes) slowConsumers += 1;
 		}
+		const backplane = this.#backplane?.describe() ?? {
+			driver: LoopbackBackplane.driver,
+			kind: "local",
+			originId: String(process.pid),
+			crossPod: false
+		};
 		return {
 			ts: Date.now(),
 			channels,
@@ -503,7 +911,15 @@ var RealtimeHub = class RealtimeHub {
 			fanoutTotal: this.#fanoutTotal,
 			inboundTotal: this.#inboundTotal,
 			ingressRejectedTotal: this.#ingressRejectedTotal,
+			localOnlyTotal: this.#localOnlyTotal,
 			systemFloorDeniedTotal: this.#systemFloorDeniedTotal,
+			sealRejectedTotal: backplane.sealRejectedTotal ?? 0,
+			frameRateRejectedTotal: frameRateRejectedTotal(),
+			allowTimedOutTotal: this.admissionBudget.timedOutTotal,
+			allowSaturatedTotal: this.admissionBudget.saturatedTotal,
+			authenticateTimedOutTotal: this.admissionBudget.authenticateTimedOutTotal,
+			binaryDiscardedTotal,
+			malformedDiscardedTotal,
 			connectionCount,
 			bytesSentTotal,
 			messagesSentTotal,
@@ -513,12 +929,7 @@ var RealtimeHub = class RealtimeHub {
 				slowConsumers,
 				drops
 			},
-			backplane: this.#backplane?.describe() ?? {
-				driver: LoopbackBackplane.driver,
-				kind: "local",
-				originId: String(process.pid),
-				crossPod: false
-			}
+			backplane
 		};
 	}
 	/** Canaux actifs (≥ 1 abonné). Lecture seule. */
@@ -593,6 +1004,39 @@ var RealtimeHub = class RealtimeHub {
 		this.#slowConsumerBytes = bytes;
 	}
 	/**
+	* Les codecs de frame du serveur (ADR-0022 §2) : le texte, et le codec binaire
+	* accordé aux clients qui l'offrent — `null` tant que la configuration n'en
+	* active aucun. Lu une fois par connexion, au handshake, jamais par trame.
+	*/
+	get frameCodecs() {
+		return this.#frameCodecs;
+	}
+	/**
+	* Pose le codec binaire du serveur — 1× au boot par `RealtimeService.init()`,
+	* depuis la clé `codec` de la configuration. Sans argument : texte seul.
+	*
+	* @param codec - le codec activé (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+	*/
+	setFrameCodec(codec) {
+		this.#frameCodecs = frameCodecSet(codec);
+		this.#armBusBytes();
+	}
+	/**
+	* Le codec des connexions texte — celui qu'emprunte aussi le REST du plan
+	* d'administration, pour qu'une valeur lue par `GET` soit celle que la socket
+	* livre (#618 D9). Avec un codec binaire activé, c'est le JSON à convention
+	* d'octets ; sinon le JSON natif.
+	*/
+	get textFrameCodec() {
+		return this.#frameCodecs.text;
+	}
+	/**
+	* Pose les bornes des admissions (`authenticateTimeoutMs`, `allowTimeoutMs`, `maxPendingAllowsPerConnection`, `maxPendingAllowsTotal`) — 1× au boot par `RealtimeService.init()`.
+	*/
+	setAdmissionLimits(limits) {
+		this.admissionBudget.configure(limits);
+	}
+	/**
 	* Associe un token au peer (posé par `RealtimeController.onHandshake()` après
 	* succès `authenticator.authenticate()` ou fallback anonyme). Lazy alloc de
 	* la `WeakMap` au 1ᵉʳ appel (0 coût si aucun authenticator enregistré).
@@ -615,6 +1059,7 @@ var RealtimeHub = class RealtimeHub {
 	*/
 	setFrameAuthorizer(authorizer, options) {
 		this.#frameAuthorizer = authorizer;
+		this.#dropRetainedVerdicts();
 		this.#channelProbe = options?.silentProbe ?? null;
 	}
 	/**
@@ -697,15 +1142,29 @@ var RealtimeHub = class RealtimeHub {
 	*
 	* @param name   - nom exact du canal (subscribe), de la méthode inbound, ou
 	*   MOTIF de famille s'il contient `*`.
+	* Une politique à `allow` porte sa règle d'admission : une flèche est
+	* retenue telle quelle ; une classe exige son instance, résolue au démarrage
+	* par l'injecteur, dont la méthode est liée ICI, une fois — le `subscribe`
+	* n'appelle qu'une fonction prête.
+	*
 	* @param policy - exigences ({@link IChannelPolicy}) lues par security.
+	* @param admission - instance de la classe d'admission quand `policy.allow`
+	*   en est une ; ignorée sinon.
+	* @throws BootConfigurationError La politique désigne une classe d'admission
+	*   et aucune instance de CETTE classe n'est fournie.
 	*/
-	registerChannelPolicy(name, policy) {
+	registerChannelPolicy(name, policy, admission) {
+		const entry = {
+			policy,
+			admission: admissionRuleOf(name, policy, admission)
+		};
+		this.#dropRetainedVerdicts();
 		if (isReservedSystemChannel(name)) this.#notifyOnce("reserved-policy", `le canal "${name}" est déclaré dans un namespace RÉSERVÉ à la plateforme (${RESERVED_SYSTEM_PREFIXES.join(" ")}) : le plancher système s'y applique et exigera un rôle d'administration, quelle que soit la politique déclarée ici. Renommer le canal avec un préfixe applicatif si ce n'est pas voulu.`);
 		if (name.includes("*")) {
-			this.#registerChannelPolicyPattern(name, policy);
+			this.#registerChannelPolicyPattern(name, entry);
 			return;
 		}
-		(this.#channelPolicies ??= /* @__PURE__ */ new Map()).set(name, policy);
+		(this.#channelPolicies ??= /* @__PURE__ */ new Map()).set(name, entry);
 	}
 	/**
 	* Nombre maximum de `*` dans un motif.
@@ -717,7 +1176,7 @@ var RealtimeHub = class RealtimeHub {
 	* de déclaration, et on le DIT plutôt que d'exposer un chemin coûteux à ce
 	* qu'un client peut nommer.
 	*/
-	static MAX_PATTERN_WILDCARDS = 3;
+	static MAX_PATTERN_WILDCARDS = MAX_CHANNEL_PATTERN_WILDCARDS;
 	/**
 	* Compile un motif et l'insère à son rang de spécificité.
 	*
@@ -726,14 +1185,12 @@ var RealtimeHub = class RealtimeHub {
 	* `.` reste un point, un `(` reste une parenthèse — sans quoi une déclaration
 	* anodine deviendrait une expression, avec ce que cela ouvre.
 	*/
-	#registerChannelPolicyPattern(source, policy) {
-		const etoiles = source.split("*").length - 1;
-		if (etoiles > RealtimeHub.MAX_PATTERN_WILDCARDS) {
-			this.#notifyOnce(`pattern-too-broad:${source}`, `le motif de politique "${source}" porte ${etoiles} caractères « * » (maximum ${RealtimeHub.MAX_PATTERN_WILDCARDS}) : il est IGNORÉ. Un motif de canal en demande un, deux au pire — au-delà, la mise en correspondance coûte cher sur des noms que le client choisit.`);
+	#registerChannelPolicyPattern(source, entry) {
+		const re = compileChannelPattern(source);
+		if (re === null) {
+			this.#notifyOnce(`pattern-too-broad:${source}`, `le motif de politique "${source}" porte ${countWildcards(source)} caractères « * » (maximum ${RealtimeHub.MAX_PATTERN_WILDCARDS}) : il est IGNORÉ. Un motif de canal en demande un, deux au pire — au-delà, la mise en correspondance coûte cher sur des noms que le client choisit.`);
 			return;
 		}
-		const echappe = source.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-		const re = new RegExp(`^${echappe.split("\\*").join(".*")}$`, "u");
 		const weight = source.split("*").join("").length;
 		const policies = this.#channelPolicyPatterns ??= [];
 		const existing = policies.findIndex((p) => p.source === source);
@@ -741,15 +1198,15 @@ var RealtimeHub = class RealtimeHub {
 			source,
 			re,
 			weight,
-			policy
+			...entry
 		};
 		if (existing >= 0) {
 			policies[existing] = policyEntry;
 			return;
 		}
-		const rang = policies.findIndex((p) => p.weight < weight);
-		if (rang < 0) policies.push(policyEntry);
-		else policies.splice(rang, 0, policyEntry);
+		const rank = policies.findIndex((p) => p.weight < weight);
+		if (rank < 0) policies.push(policyEntry);
+		else policies.splice(rank, 0, policyEntry);
 	}
 	/**
 	* Politique déclarée pour ce canal/méthode, ou `null` si aucune. Lu par
@@ -757,12 +1214,50 @@ var RealtimeHub = class RealtimeHub {
 	* la frame `subscribe`/inbound. O(1), 0 alloc quand le registre est vide.
 	*/
 	resolveChannelPolicy(name) {
+		return this.#resolvePolicyEntry(name)?.policy ?? null;
+	}
+	/**
+	* Règle d'admission prête à appeler pour ce canal — `null` s'il ne déclare pas `allow`. Lue au `subscribe`, jamais par trame.
+	*
+	* Même résolution que {@link resolveChannelPolicy} (nom exact, puis motif le
+	* plus spécifique) : la règle suit TOUJOURS la politique qui s'applique.
+	*/
+	resolveChannelAdmission(name) {
+		return this.#resolvePolicyEntry(name)?.admission ?? null;
+	}
+	/**
+	* Les politiques de cette classe de contrôleur sont-elles déjà inscrites ? Une poignée de main n'en paie que ce `has`.
+	*
+	* @param owner - le constructeur du contrôleur.
+	*/
+	hasPolicyOwner(owner) {
+		return this.#policyOwners?.has(owner) === true;
+	}
+	/**
+	* Marque les politiques de cette classe comme inscrites — APRÈS l'inscription réussie, jamais avant : une politique refusée doit l'être de nouveau à la poignée de main suivante, pas laisser le canal ouvert.
+	*
+	* @param owner - le constructeur du contrôleur.
+	*/
+	addPolicyOwner(owner) {
+		(this.#policyOwners ??= /* @__PURE__ */ new WeakSet()).add(owner);
+	}
+	/** Entrée du registre qui s'applique à ce nom — exact d'abord, puis motif. */
+	#resolvePolicyEntry(name) {
 		const exact = this.#channelPolicies?.get(name);
 		if (exact !== void 0) return exact;
 		const patterns = this.#channelPolicyPatterns;
-		if (patterns === null) return null;
-		for (const pattern of patterns) if (pattern.re.test(name)) return pattern.policy;
-		return null;
+		if (patterns !== null) {
+			for (const pattern of patterns) if (pattern.re.test(name)) return pattern;
+		}
+		return name.startsWith(USER_CHANNEL_PREFIX) ? USER_CHANNEL_POLICY : null;
+	}
+	/**
+	* Une politique est-elle déclarée sous ce nom EXACT — motifs ignorés ? C'est la question du défaut fermé des actions.
+	*
+	* @param name - nom d'action ou de canal.
+	*/
+	hasExactChannelPolicy(name) {
+		return this.#channelPolicies?.has(name) === true;
 	}
 	/** Des politiques de canal sont-elles déclarées (au moins une) ? */
 	hasChannelPolicies() {
@@ -773,14 +1268,14 @@ var RealtimeHub = class RealtimeHub {
 	* DYNAMIQUE n'est couvert par aucune politique déclarée, alors que d'autres
 	* canaux du module en portent une.
 	*
-	* Le registre des politiques est indexé par nom **EXACT** : `@RealtimeChannel`
-	* déclare `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence,
-	* forage, suffixe) est servi par la fabrique dynamique et **ne matche pas**.
-	* L'auteur croit alors son canal gardé ; il ne l'est pas, et rien ne le lui
-	* dit. C'est ce silence qu'on ferme ici — et depuis qu'une politique peut se
-	* déclarer par MOTIF (`chat:room:*`), cet avertissement ne parle plus que des
-	* canaux qu'aucun motif ne couvre : il désigne un vrai trou, pas une limite
-	* de l'outil.
+	* Le registre des politiques lit le nom **EXACT**, puis les **MOTIFS**
+	* déclarés ({@link resolveChannelPolicy}) : `@RealtimeChannel` déclare
+	* `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence, forage,
+	* suffixe) servi par la fabrique dynamique ne matche ce nom que si un motif
+	* (`chat:room:*`) le couvre. Sans motif, l'auteur croit son canal gardé ; il
+	* ne l'est pas, et rien ne le lui dit. C'est ce silence qu'on ferme ici :
+	* l'avertissement ne parle que des canaux qu'aucun motif ne couvre — un vrai
+	* trou, pas une limite de l'outil.
 	*
 	* Appelé par le contrôleur, seul à savoir par quelle voie le canal a été
 	* servi. Muet si aucune politique n'est déclarée (module aux canaux libres :
@@ -832,8 +1327,39 @@ var RealtimeHub = class RealtimeHub {
 		return this.#clientLogs;
 	}
 	runAuthorizer(frame, peer) {
-		if (this.#frameAuthorizer === null) return true;
-		return this.#frameAuthorizer(frame, this.getTokenForPeer(peer));
+		const authorizer = this.#frameAuthorizer;
+		if (authorizer === null) return true;
+		try {
+			return authorizer(frame, this.getTokenForPeer(peer)) === true;
+		} catch (e) {
+			this.#notifyOnce("frame-authorizer-threw", "le verrou des trames a levé une exception — trame refusée : " + (e instanceof Error ? e.message : String(e)));
+			return false;
+		}
+	}
+	/**
+	* Inscrit une connexion qui vient de retenir son premier « oui » du verrou.
+	*
+	* Appelé par `gateFrame`, jamais par trame chaude ; à équilibrer par
+	* {@link untrackRetainedVerdicts} à la fermeture.
+	*
+	* @param state - état de la connexion.
+	*/
+	trackRetainedVerdicts(state) {
+		(this.#retainers ??= /* @__PURE__ */ new Set()).add(state);
+	}
+	/**
+	* Retire une connexion fermée du registre des verdicts retenus.
+	*
+	* @param state - état de la connexion.
+	*/
+	untrackRetainedVerdicts(state) {
+		this.#retainers?.delete(state);
+	}
+	#dropRetainedVerdicts() {
+		const retainers = this.#retainers;
+		if (retainers === null) return;
+		for (const state of retainers) dropRetainedVerdicts(state);
+		this.#retainers = null;
 	}
 	/**
 	* Ce peer pourrait-il s'abonner à ce canal ? — même décision que `subscribe`,
@@ -849,11 +1375,17 @@ var RealtimeHub = class RealtimeHub {
 	* @returns `true` si un `subscribe` sur ce canal serait accepté.
 	*/
 	probeChannel(channel, peer) {
-		if (this.#channelProbe === null) return true;
-		return this.#channelProbe({
-			method: "subscribe",
-			params: { channel }
-		}, this.getTokenForPeer(peer));
+		const probe = this.#channelProbe;
+		if (probe === null) return true;
+		try {
+			return probe({
+				method: "subscribe",
+				params: { channel }
+			}, this.getTokenForPeer(peer));
+		} catch (e) {
+			this.#notifyOnce("channel-probe-threw", "la sonde des canaux annoncés a levé une exception — canal annoncé : " + (e instanceof Error ? e.message : String(e)));
+			return true;
+		}
 	}
 	/** Authenticators enregistrés (debug / tests). Lecture seule. */
 	get registeredAuthenticators() {
@@ -875,16 +1407,28 @@ var RealtimeHub = class RealtimeHub {
 		this.#authenticators = null;
 		this.#peerTokens = null;
 		this.#frameAuthorizer = null;
+		this.#channelProbe = null;
+		this.#dropRetainedVerdicts();
 		this.#channelPolicies?.clear();
 		this.#channelPolicies = null;
 		this.#channelPolicyPatterns = null;
+		this.#policyOwners = null;
 		this.#originGuard = null;
 		this.#backplane = null;
+		this.#busBytes = false;
 		this.#publishTotal = 0;
 		this.#fanoutTotal = 0;
+		this.#closedBytesSent = 0;
+		this.#closedMessagesSent = 0;
+		this.#closedDropped = 0;
+		this.#closedBinaryDiscarded = 0;
+		this.#closedMalformedDiscarded = 0;
 		this.#inboundTotal = 0;
 		this.#ingressRejectedTotal = 0;
+		this.#localOnlyTotal = 0;
 		this.#systemFloorDeniedTotal = 0;
+		this.admissionBudget.reset();
+		this.#frameCodecs = frameCodecSet();
 		this.#noticed = null;
 		this.#notice = null;
 	}
@@ -918,8 +1462,7 @@ function compileMatcher(m) {
 	};
 }
 let _hub = null;
-/** Renvoie le hub realtime du process (singleton lazy). */
 function getRealtimeHub() {
 	return _hub ??= new RealtimeHub();
 }
-export { RESERVED_SYSTEM_PREFIXES, REVOCATION_REVALIDATE_MS, RealtimeHub, RealtimeHub as default, SLOW_CONSUMER_BYTES, channelFamily, getRealtimeHub, isReservedSystemChannel };
+export { ChannelFrame, RESERVED_SYSTEM_PREFIXES, REVOCATION_REVALIDATE_MS, RealtimeHub, RealtimeHub as default, SLOW_CONSUMER_BYTES, channelFamily, getRealtimeHub, isReservedSystemChannel };