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

package/dist/nodefony/src/backplane/presenceMessage.js

@@ -0,0 +1,205 @@
+import { isBoundedBusText } from "./controlOrder.js";
+import { ownField } from "nodefony";
+// nodefony/src/backplane/presenceMessage.ts
+/**
+* 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). */
+const MIN_PRESENCE_INTERVAL_MS = 100;
+/** Plus grand intervalle de preuve de vie qu'un pair peut annoncer (ms) — 10 min. */
+const MAX_PRESENCE_INTERVAL_MS = 6e5;
+/**
+* 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 »).
+*/
+const MAX_PRESENCE_MEMBERS = 1e5;
+/** Plafond d'entrées de canal dans un même message (lot, demande ou part de réponse). */
+const MAX_PRESENCE_CHANNELS = 4096;
+/** Plafond de parts d'une réponse d'état (`n`). */
+const MAX_PRESENCE_PARTS = 4096;
+/** Entier sûr ≥ 0. */
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+* Paires à plat `[identité, onglets, …]` recevables : longueur paire, au plus
+* {@link MAX_PRESENCE_MEMBERS} identités, textes bornés, onglets entiers ≥ 1.
+* Un seul parcours, aucune allocation.
+*/
+function isPairs(value) {
+	if (!Array.isArray(value)) return false;
+	const length = value.length;
+	if ((length & 1) !== 0 || length > 2e5) return false;
+	for (let i = 0; i < length; i += 2) {
+		if (!isBoundedBusText(value[i])) return false;
+		const tabs = value[i + 1];
+		if (typeof tabs !== "number" || !Number.isSafeInteger(tabs) || tabs < 1) return false;
+	}
+	return true;
+}
+/** Liste de textes bornés d'au plus `max` éléments. */
+function isTextList(value, max) {
+	if (!Array.isArray(value) || value.length > max) return false;
+	for (let i = 0; i < value.length; i += 1) if (!isBoundedBusText(value[i])) return false;
+	return true;
+}
+/** Numéro de message recevable : entier sûr ≥ 1. */
+function isSeq(value) {
+	return isCount(value) && value >= 1;
+}
+/** Un champ « numéro précédent » (`prev`, `last`) : entier sûr ≥ 0, strictement sous `seq`. */
+function readBefore(payload, key, seq) {
+	const value = ownField(payload, key);
+	return isCount(value) && value < seq ? value : null;
+}
+function readDeltas(value) {
+	if (!Array.isArray(value) || value.length > 4096) return null;
+	const out = new Array(value.length);
+	for (let i = 0; i < value.length; i += 1) {
+		const entry = value[i];
+		const channel = ownField(entry, "channel");
+		const unnamed = ownField(entry, "unnamed");
+		if (!isBoundedBusText(channel) || !isCount(unnamed)) return null;
+		const set = ownField(entry, "set");
+		if (set !== void 0 && set !== null && !isPairs(set)) return null;
+		const gone = ownField(entry, "gone");
+		if (gone !== void 0 && gone !== null && !isTextList(gone, 1e5)) return null;
+		out[i] = {
+			channel,
+			set: set ?? null,
+			gone: gone ?? null,
+			unnamed
+		};
+	}
+	return out;
+}
+function readStates(value) {
+	if (!Array.isArray(value) || value.length > 4096) return null;
+	const out = new Array(value.length);
+	for (let i = 0; i < value.length; i += 1) {
+		const entry = value[i];
+		const channel = ownField(entry, "channel");
+		const unnamed = ownField(entry, "unnamed");
+		const members = ownField(entry, "members");
+		if (!isBoundedBusText(channel) || !isCount(unnamed) || !isPairs(members)) return null;
+		out[i] = {
+			channel,
+			members,
+			unnamed
+		};
+	}
+	return out;
+}
+/** Les types de message que cette version sait lire sur le canal de présence — liste fermée. */
+function isKnownOp(op) {
+	return op === "batch" || op === "request" || op === "state";
+}
+/**
+* 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).
+*/
+function readPresenceMessage(payload) {
+	const op = ownField(payload, "op");
+	if (!isKnownOp(op)) return null;
+	const incarnation = ownField(payload, "incarnation");
+	const seq = ownField(payload, "seq");
+	if (!isCount(incarnation) || !isSeq(seq)) return null;
+	const raw = ownField(payload, "channels");
+	if (op === "batch") {
+		const prev = readBefore(payload, "prev", seq);
+		if (prev === null) return null;
+		const channels = readDeltas(raw);
+		return channels === null ? null : {
+			op,
+			incarnation,
+			seq,
+			prev,
+			channels
+		};
+	}
+	if (op === "request") {
+		if (!isTextList(raw, 4096)) return null;
+		const to = ownField(payload, "to");
+		if (to !== void 0 && to !== null && !isBoundedBusText(to)) return null;
+		return {
+			op,
+			incarnation,
+			seq,
+			channels: raw,
+			to: to ?? null
+		};
+	}
+	const last = readBefore(payload, "last", seq);
+	const i = ownField(payload, "i");
+	const n = ownField(payload, "n");
+	if (last === null || !isCount(n) || n < 1 || n > 4096 || !isCount(i) || i >= n) return null;
+	const channels = readStates(raw);
+	return channels === null ? null : {
+		op,
+		incarnation,
+		seq,
+		last,
+		i,
+		n,
+		channels
+	};
+}
+/**
+* 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).
+*/
+function isUnknownPresenceMessage(payload) {
+	const op = ownField(payload, "op");
+	return isBoundedBusText(op) && !isKnownOp(op);
+}
+/**
+* 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).
+*/
+function readPresenceAlive(payload) {
+	const incarnation = ownField(payload, "incarnation");
+	const seq = ownField(payload, "seq");
+	if (!isCount(incarnation) || !isSeq(seq)) return null;
+	const last = readBefore(payload, "last", seq);
+	const interval = ownField(payload, "interval");
+	const final = ownField(payload, "final");
+	if (last === null || !isCount(interval) || interval < 100 || interval > 6e5 || final !== void 0 && typeof final !== "boolean") return null;
+	return {
+		incarnation,
+		seq,
+		last,
+		interval,
+		final: final === true
+	};
+}
+export { MAX_PRESENCE_CHANNELS, MAX_PRESENCE_INTERVAL_MS, MAX_PRESENCE_MEMBERS, MAX_PRESENCE_PARTS, MIN_PRESENCE_INTERVAL_MS, isUnknownPresenceMessage, readPresenceAlive, readPresenceMessage };

package/dist/nodefony/src/backplane/publishQueue.js

@@ -1,4 +1,47 @@
 import { isThenable } from "../guards.js";
+import { PLATFORM_BUS_CHANNELS, isPriorityBusChannel } from "nodefony";
+// nodefony/src/backplane/publishQueue.ts
+/**
+* **File d'envoi bornée d'un backplane** — protège la mémoire du pod quand le bus
+* n'absorbe pas le débit publié. Mutualisée ici (comme le sceau d'enveloppe) pour
+* qu'un driver à transport réseau — Redis, et tout driver userland : NATS, Kafka,
+* RabbitMQ — hérite de la garantie sans la réécrire.
+*
+* Pourquoi : `IBackplane.publish` est **fire-and-forget** par contrat (il rend
+* `void`). Un client réseau met alors la commande dans SA file tant que la socket
+* n'est pas drainée — file interne, invisible, sans limite. Une rafale y accumule
+* des mégaoctets : 583 MB observés sur le banc multi-pods, pour 152 MB au repos.
+* Aucune fuite (tout redescend), mais rien ne borne le pic → OOM sous rafale plus
+* longue.
+*
+* Doctrine — la MÊME que le transport WS (seuil, compteur de jetés, avertissement),
+* parce que le problème est le même : un pair qui ne draine pas. Deux règles en
+* découlent :
+*  - **on protège la mémoire** : au-delà du seuil, les publications suivantes sont
+*    jetées (sémantique at-most-once déjà assumée par le port — le client realtime
+*    re-synchronise) ;
+*  - **on ne jette jamais en silence** : compteurs exposés dans la carte d'identité
+*    du backplane (donc sonde + Studio) et transitions annoncées.
+*    Cf `project_resilience_no_silent_degradation`.
+*
+* 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.
+*/
+/** Canal des ordres de contrôle, lu une fois au chargement (pas d'accès de propriété par envoi). */
+const CONTROL_CHANNEL = PLATFORM_BUS_CHANNELS.control;
 /**
 * Seuil par défaut d'octets en vol vers le bus : **8 MiB**, aligné sur le seuil de
 * coupure d'un slow-consumer WS. Un bus sain acquitte en quelques millisecondes
@@ -23,6 +66,14 @@ var BackplanePublishQueue = class {
 	#saturated = false;
 	/** Jetés de l'épisode de saturation courant — chiffre annoncé au retour à la normale. */
 	#droppedInEpisode = 0;
+	/** Ordres de contrôle refusés par le transport (monotone). */
+	#controlLostTotal = 0;
+	/** Ordres perdus de l'épisode courant ; `> 0` = épisode ouvert (1 log par épisode). */
+	#controlLostInEpisode = 0;
+	/** Publications réseau en vol (un entier : le compte, pas les octets — un message vide compte). */
+	#inFlight = 0;
+	/** Attentes de {@link BackplanePublishQueue.settled} ; `null` tant que personne n'attend (arrêt seulement). */
+	#idle = null;
 	/**
 	* @param maxBytes - seuil d'octets en vol ; `0` (ou négatif) = illimité.
 	* @param notice - annonce des transitions ; omis = silencieux (tests unitaires).
@@ -39,13 +90,18 @@ var BackplanePublishQueue = class {
 	* (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, emit) {
-		if (this.#maxBytes > 0 && this.#bytes >= this.#maxBytes) {
+	send(channel, bytes, emit) {
+		if (this.#maxBytes > 0 && this.#bytes >= this.#maxBytes && !isPriorityBusChannel(channel)) {
 			this.#droppedTotal += 1;
 			this.#droppedInEpisode += 1;
 			if (!this.#saturated) {
@@ -57,10 +113,18 @@ var BackplanePublishQueue = class {
 		const result = emit();
 		if (!isThenable(result)) return true;
 		this.#bytes += bytes;
+		this.#inFlight += 1;
 		const settle = (failed) => {
 			this.#bytes -= bytes;
 			if (failed) this.#failedTotal += 1;
+			if ((failed || this.#controlLostInEpisode > 0) && channel === CONTROL_CHANNEL) this.#controlSettled(failed);
 			this.#drain();
+			this.#inFlight -= 1;
+			if (this.#inFlight === 0 && this.#idle !== null) {
+				const waiting = this.#idle;
+				this.#idle = null;
+				for (const resolve of waiting) resolve();
+			}
 		};
 		result.then(() => settle(false), () => settle(true));
 		return true;
@@ -79,13 +143,43 @@ var BackplanePublishQueue = class {
 		this.#droppedInEpisode = 0;
 		this.#notice?.(`backplane : file d'envoi drainée (${this.#bytes} octets en vol) — ${lost} publication(s) perdue(s) pendant la saturation.`, "INFO");
 	}
+	/**
+	* Suit l'acquittement d'un ordre de contrôle : un refus ouvre un épisode,
+	* annoncé une fois ; le premier ordre de nouveau acquitté le ferme, avec le
+	* bilan des pertes.
+	*/
+	#controlSettled(failed) {
+		if (failed) {
+			this.#controlLostTotal += 1;
+			this.#controlLostInEpisode += 1;
+			if (this.#controlLostInEpisode === 1) this.#notice?.("backplane : un ordre de contrôle (terminer un canal, éjecter un compte) a été REFUSÉ par le bus — les autres serveurs ne l'appliqueront pas. Cause : bus injoignable. Compteur : controlLostTotal.", "WARNING");
+			return;
+		}
+		if (this.#controlLostInEpisode === 0) return;
+		const lost = this.#controlLostInEpisode;
+		this.#controlLostInEpisode = 0;
+		this.#notice?.(`backplane : ordres de contrôle de nouveau acquittés — ${lost} ordre(s) perdu(s) pendant la coupure.`, "INFO");
+	}
+	/**
+	* 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() {
+		if (this.#inFlight === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			(this.#idle ??= []).push(resolve);
+		});
+	}
 	/** Compteurs pour la carte d'identité du backplane (sonde + Studio). */
 	describe() {
 		return {
 			bytes: this.#bytes,
 			maxBytes: this.#maxBytes,
 			droppedTotal: this.#droppedTotal,
-			failedTotal: this.#failedTotal
+			failedTotal: this.#failedTotal,
+			controlLostTotal: this.#controlLostTotal
 		};
 	}
 };

package/dist/nodefony/src/cluster/ClusterProbeClient.js

@@ -34,6 +34,7 @@ function mergeClusterHealth(instances, ts = Date.now()) {
 		fanoutTotal: 0,
 		inboundTotal: 0,
 		ingressRejectedTotal: 0,
+		localOnlyTotal: 0,
 		connectionCount: 0,
 		bytesSentTotal: 0,
 		messagesSentTotal: 0,
@@ -52,6 +53,7 @@ function mergeClusterHealth(instances, ts = Date.now()) {
 		totals.fanoutTotal += h.fanoutTotal;
 		totals.inboundTotal += h.inboundTotal;
 		totals.ingressRejectedTotal += h.ingressRejectedTotal;
+		totals.localOnlyTotal += h.localOnlyTotal;
 		totals.connectionCount += h.connectionCount;
 		totals.bytesSentTotal += h.bytesSentTotal;
 		totals.messagesSentTotal += h.messagesSentTotal;

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

@@ -1,5 +1,23 @@
 // nodefony/src/server/AnonymousRealtimeToken.ts
 /**
+* Identité d'admission de l'ANONYME — gelée et partagée par toutes les connexions non authentifiées (0 allocation par connexion).
+*
+* Porte l'invariant de l'ADR-0021 §S10 : anonyme ⇔ `authenticated === false`,
+* `id === null` et `issuer === null`. Un canal qui déclare `allow` refuse
+* cette identité d'office, sauf option explicite `anonymous: true` — ce qui
+* garantit que `user:${who.id}` ne vaut jamais `"user:null"`.
+*/
+const ANONYMOUS_SUBSCRIBER_IDENTITY = Object.freeze({
+	type: "anonymous",
+	authenticated: false,
+	id: null,
+	userIdentifier: "anonymous",
+	roles: Object.freeze(["ROLE_ANONYMOUS"]),
+	scopes: Object.freeze([]),
+	issuer: null,
+	account: false
+});
+/**
 * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
 * `IRealtimeAuthenticatorMatcher` ne capture le handshake.
 *
@@ -26,6 +44,9 @@ const ANONYMOUS_REALTIME_TOKEN = Object.freeze({
 	getScopes() {
 		return [];
 	},
-	getAttribute(_key) {}
+	getAttribute(_key) {},
+	getIdentity() {
+		return ANONYMOUS_SUBSCRIBER_IDENTITY;
+	}
 });
-export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_REALTIME_TOKEN as default };
+export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_REALTIME_TOKEN as default, ANONYMOUS_SUBSCRIBER_IDENTITY };

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

@@ -0,0 +1,75 @@
+import { RealtimeController } from "./RealtimeController.js";
+// nodefony/src/server/ContractRealtimeController.ts
+/**
+* Socle commun des deux formes de {@link ContractRealtimeController} : l'étiquette
+* de contrat et les canaux annoncés. Les actions y gardent le défaut de la base
+* (`{}`) — un contrat SANS `serverMethods` n'a rien à écrire.
+*
+* Ne s'étend pas directement : on étend {@link ContractRealtimeController}, qui
+* choisit cette forme ou la forme stricte selon le contrat.
+*
+* @typeParam C - le contrat de l'application.
+*/
+var ContractRealtimeControllerBase = class extends RealtimeController {
+	/** Canaux annoncés au handshake, contraints aux noms de `serverToClient`. */
+	realtimeChannels() {
+		return [];
+	}
+};
+/**
+* Forme stricte de {@link ContractRealtimeController}, retenue quand le contrat
+* déclare des `serverMethods` : `realtimeActions()` y devient ABSTRAITE et typée
+* par le contrat — la seule construction qui fait d'une méthode OUBLIÉE une
+* erreur de compilation (un décorateur ne voit jamais la classe entière).
+*
+* Ne s'étend pas directement : on étend {@link ContractRealtimeController}.
+*
+* @typeParam C - le contrat de l'application.
+*/
+var ContractRealtimeControllerStrict = class extends ContractRealtimeControllerBase {};
+/**
+* Base d'un contrôleur qui IMPLÉMENTE un contrat temps réel — la porte du
+* serveur. Le contrat s'écrit UNE fois, sur `extends` ; la direction du serveur
+* en est dérivée (il émet `serverToClient`, écoute `clientToServer`, appelle
+* `clientMethods`) et il DOIT servir chaque méthode de `serverMethods`.
+*
+* Quand le contrat déclare des `serverMethods`, `realtimeActions()` est
+* abstraite et typée par lui : une méthode OUBLIÉE ne compile pas. Un contrat
+* SANS `serverMethods` (tableau de bord, chat qui ne fait que diffuser) n'a rien
+* à écrire. Les entrées client (`realtimeInbound()`) restent facultatives canal
+* par canal : accepter une entrée est une permission, pas une promesse. Les
+* politiques d'accès se posent sur la classe par `@RealtimePolicy`, qui lit le
+* contrat sur cette classe.
+*
+* Le fichier du contrat, fait de types seuls, est partagé avec le navigateur, qui
+* entre par `NodefonySocket.fromContract<C>()`.
+*
+* Un contrat qui déclare des `serverRoutes` (routes du pont, typées côté client
+* par le schéma que la route valide) se double d'une table statique de VALEURS,
+* `static readonly serverRoutes = { … } satisfies ContractRouteSchemas<C>` : le
+* compilateur y exige chaque route du contrat avec son schéma, et le démarrage
+* vérifie que chacune est montée, servie par la socket et valide LE MÊME schéma
+* (`BootConfigurationError` sinon). Sans cette table, aucun contrôle.
+*
+* @typeParam C - le contrat de l'application.
+*
+* @example
+* ```ts
+* @RealtimePolicy({ "chat:send": { roles: ["ROLE_USER"] } })
+* class ChatRt extends ContractRealtimeController<ChatContract> {
+*   protected realtimeActions() {
+*     return { "chat:send": (p: { text: string }) => ({ id: this.store(p.text) }) };
+*   }
+* }
+*
+* class DashRt extends ContractRealtimeController<DashContract> {} // sans serverMethods
+*
+* class ChatRoutesRt extends ContractRealtimeController<ChatContract> {
+*   static readonly serverRoutes = {
+*     "POST /chat/send": { body: SendBody }, // le schéma de la route, pas une copie
+*   } satisfies ContractRouteSchemas<ChatContract>;
+* }
+* ```
+*/
+const ContractRealtimeController = ContractRealtimeControllerStrict;
+export { ContractRealtimeController, ContractRealtimeControllerBase, ContractRealtimeControllerStrict };

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

@@ -0,0 +1,135 @@
+// nodefony/src/server/RealtimeConnection.ts
+/**
+* Poignée d'une connexion temps réel servie par ce processus — implémente {@link IRealtimeConnection}.
+*
+* Créée paresseusement par le contrôleur, au premier abonnement ou à la
+* première trame entrante de la connexion (jamais au welcome : une connexion
+* qui ne fait ni l'un ni l'autre n'en paie aucune). Fermée au `onFinish` de la
+* socket : les gestes du hub rendent alors `false`, et les abonnements imposés
+* en attente se soldent par un refus.
+*
+* @internal Le type public est {@link IRealtimeConnection} ; seuls le hub et le
+* contrôleur appellent les méthodes de cette classe.
+*/
+var RealtimeConnection = class {
+	#host;
+	#identify;
+	#userId = null;
+	#account = false;
+	#open = true;
+	#imposing = null;
+	/**
+	* @param host - le contrôleur qui sert la connexion.
+	* @param identify - lit l'identité d'admission, figée au handshake ; appelé
+	*   au plus une fois.
+	*/
+	constructor(host, identify) {
+		this.#host = host;
+		this.#identify = identify;
+	}
+	/** Lit l'identité au premier besoin, une fois. */
+	#resolveIdentity() {
+		const identify = this.#identify;
+		if (identify === null) return;
+		this.#identify = null;
+		const identity = identify();
+		this.#userId = identity?.id ?? null;
+		this.#account = identity?.account === true;
+	}
+	/** Identifiant du compte connecté ; `null` pour l'anonyme. */
+	get userId() {
+		this.#resolveIdentity();
+		return this.#userId;
+	}
+	/**
+	* `userId` désigne-t-il un compte LOCAL ? `false` pour l'anonyme et l'appelant
+	* machine sans compte (`<émetteur>#<sujet>`) — ceux que la présence compte sans
+	* les nommer (ADR-0025 P3).
+	*/
+	get account() {
+		this.#resolveIdentity();
+		return this.#account;
+	}
+	/**
+	* Écrit une trame PARTAGÉE (encodée une fois par codec) sur cette connexion — rien si la socket est fermée.
+	*
+	* Voie des notifications du protocole qui visent les membres d'un canal (la
+	* présence) : elles ne passent pas par le sink du canal, qui les livrerait
+	* sous le nom du canal.
+	*/
+	deliver(frame) {
+		if (this.#open) this.#host.send(frame);
+	}
+	/** `false` une fois la socket fermée. */
+	get open() {
+		return this.#open;
+	}
+	/**
+	* Impose l'abonnement à `channel` — même politique, même `allow` qu'un `subscribe` du client.
+	*
+	* @returns une promesse résolue à `true` une fois l'abonnement acquitté, à
+	*   `false` s'il est refusé, si la connexion se ferme avant, ou si le client
+	*   s'en désabonne pendant l'attente.
+	*/
+	impose(channel) {
+		if (!this.#open) return Promise.resolve(false);
+		const imposing = this.#imposing ??= /* @__PURE__ */ new Map();
+		const pending = imposing.get(channel);
+		if (pending !== void 0) return new Promise((resolve) => {
+			pending.settle.push(resolve);
+		});
+		const entry = {
+			settle: [],
+			clientAsked: false
+		};
+		const verdict = new Promise((resolve) => {
+			entry.settle.push(resolve);
+		});
+		imposing.set(channel, entry);
+		this.#host.impose(channel);
+		return verdict;
+	}
+	/**
+	* Met fin à l'abonnement de cette connexion à `channel`.
+	*
+	* @returns `false` si la connexion est fermée ou n'est pas abonnée au canal.
+	*/
+	end(channel, reason) {
+		return this.#open && this.#host.end(channel, reason);
+	}
+	/** Un abonnement imposé à `channel` attend-il son verdict ? */
+	isImposing(channel) {
+		return this.#imposing?.has(channel) === true;
+	}
+	/** Le client demande `channel` pendant l'attente de son imposition : un refus lui sera dû. */
+	markClientAsked(channel) {
+		const entry = this.#imposing?.get(channel);
+		if (entry !== void 0) entry.clientAsked = true;
+	}
+	/**
+	* Solde l'abonnement imposé à `channel`, s'il y en a un.
+	*
+	* @returns `true` si le refus doit AUSSI être rendu au client (il avait
+	*   demandé ce canal) ou s'il n'y avait pas d'imposition en cours — dans les
+	*   deux cas l'appelant suit son chemin habituel ; `false` si le refus
+	*   n'appartient qu'à l'appelant serveur.
+	*/
+	settleImposed(channel, subscribed) {
+		const imposing = this.#imposing;
+		const entry = imposing?.get(channel);
+		if (imposing === null || entry === void 0) return true;
+		imposing.delete(channel);
+		if (imposing.size === 0) this.#imposing = null;
+		for (const settle of entry.settle) settle(subscribed);
+		return entry.clientAsked;
+	}
+	/** Fermeture de la socket : la poignée ne désigne plus rien, les impositions en attente échouent. */
+	close() {
+		this.#open = false;
+		const imposing = this.#imposing;
+		if (imposing === null) return;
+		this.#imposing = null;
+		for (const entry of imposing.values()) for (const settle of entry.settle) settle(false);
+	}
+};
+export { RealtimeConnection };