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

package/dist/nodefony/testing/index.js

@@ -1,8 +1,9 @@
+import "../src/server/RealtimeController.js";
 import { isRecord } from "../src/guards.js";
 import { createAdmissionResolver, registerControllerPolicies } from "../src/server/channelPolicyRegistry.js";
 import { getRealtimeHub } from "../src/server/RealtimeHub.js";
 import { BACKPLANE_CONFORMANCE_CASES, runBackplaneConformance } from "./backplaneConformance.js";
-import { RequestContext } from "nodefony";
+import { IDENTITY_DEAD_CLOSE_CODE, ORIGIN_REFUSED_CLOSE_CODE, RequestContext } from "nodefony";
 // nodefony/testing/index.ts
 /**
 * `@nodefony/realtime/testing` — **harnais de test d'un controller temps réel**.
@@ -214,15 +215,28 @@ function createRealtimeHarness(create, options = {}) {
 		closes,
 		notices,
 		async connect() {
-			await feed(null);
-			hub.onPlatformNotice((message) => {
-				notices.push(message);
-			});
-			await waitFor(() => received.some((f) => f.method === "realtime:welcome"), 10);
+			const failures = [];
+			const syslog = controller.syslog;
+			const onLog = (pdu) => {
+				const payload = pdu.payload;
+				if (pdu.severityName === "ERROR" && typeof payload === "string" && payload.startsWith("WS realtime handshake failed")) failures.push(payload);
+			};
+			syslog?.on("onLog", onLog);
+			try {
+				await feed(null);
+				hub.onPlatformNotice((message) => {
+					notices.push(message);
+				});
+				await waitFor(() => received.some((f) => f.method === "realtime:welcome") || failures.length > 0, 10);
+			} finally {
+				syslog?.removeListener("onLog", onLog);
+			}
 			const welcome = received.find((f) => f.method === "realtime:welcome");
 			if (!welcome) {
-				const cause = closes.length > 0 ? `socket fermée (code ${String(closes[0]?.code)})` : "aucune frame émise";
-				throw new Error(`createRealtimeHarness: pas de realtime:welcome — ${cause}. Vérifier l'Origin (seam #4) et l'authenticator (seam #2).`);
+				const code = closes[0]?.code;
+				const cause = closes.length > 0 ? `socket fermée (code ${String(code)})` : "aucune frame émise";
+				const hint = failures.length > 0 ? `le serveur a levé pendant la poignée de main : ${failures[0] ?? ""}` : code === ORIGIN_REFUSED_CLOSE_CODE ? "Origin refusée (option `origin` du harnais)" : code === IDENTITY_DEAD_CLOSE_CODE ? "identité refusée (option `identity` du harnais)" : "vérifier ce que le controller construit à la connexion (services, admissions, base)";
+				throw new Error(`createRealtimeHarness: pas de realtime:welcome — ${cause}. ${hint}.`);
 			}
 			return welcome;
 		},

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

@@ -112,11 +112,16 @@ export { createSyslogUplinkHandler, BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, } from
 export type { SyslogUplinkHandlerOptions, ClientSeverity, } from "./nodefony/src/server/syslogUplink.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, IRedisBytesSubscriber, } from "./nodefony/src/backplane/RedisBackplane.js";
 export type { BackplaneFactory, IBackplaneFactoryContext, } from "./nodefony/src/backplane/backplaneRegistry.js";
-export { sealBackplaneEnvelope, openBackplaneEnvelope, } from "./nodefony/src/backplane/envelope.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/decorators/realtimeDecorators.d.ts

@@ -41,6 +41,18 @@ export declare function isAdmissionClass(allow: ChannelAllow): allow is ChannelA
  * @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
@@ -81,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:`…)
@@ -136,6 +151,10 @@ type PolicyNamesCheck<P, T> = [NamesNotInContract<P, T>] extends [never] ? unkno
  *
  * 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
@@ -153,16 +172,18 @@ 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`
- * (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
+ * 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
@@ -170,8 +191,20 @@ export declare function RealtimePolicy<P extends {
  * 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);
@@ -192,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")
@@ -224,6 +271,21 @@ 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;
 /**
@@ -233,14 +295,53 @@ export declare function getRealtimeInbound(instance: object): Record<string, Rea
  * @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'autorisation déclarées sur une CLASSE de contrôleur (`@RealtimeChannel`/`@RealtimeInbound`/`@RealtimePolicy` avec politique), validées — lues au démarrage du noyau, jamais par trame.
+ * 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, ou `null` si la classe n'en
- *   déclare aucune (0 allocation).
- * @throws BootConfigurationError Une politique est illisible : la classe, le
- *   canal et le défaut sont nommés.
+ * @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;
 /**

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

@@ -62,6 +62,10 @@ export type BackplaneHandler = (msg: IBackplaneMessage) => void;
  *  - **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 ;
@@ -101,7 +105,14 @@ export interface IBackplane {
      * @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. */
+    /**
+     * 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/src/backplane/RedisBackplane.d.ts

@@ -222,12 +222,20 @@ export declare class RedisBackplane implements IBackplane {
      * L'envoi passe par la **file bornée** : si le bus n'acquitte plus, les
      * publications suivantes sont jetées et comptées plutôt que d'empiler des
      * mégaoctets dans le client Redis (sémantique at-most-once déjà assumée par le
-     * port ; le client realtime re-synchronise).
+     * port ; le client realtime re-synchronise). Un ordre de contrôle, lui, part
+     * toujours (cf {@link BackplanePublishQueue.send}).
      */
     publish(channel: string, payload: unknown): void;
     /** Un seul handler d'ingress ; un appel ultérieur remplace le précédent. */
     onMessage(handler: BackplaneHandler): void;
-    /** Désabonne du canal Redis et détache le handler. Idempotent. */
+    /**
+     * Laisse partir les publications déjà émises (acquittées ou refusées par Redis), puis désabonne du canal et détache le handler. Idempotent.
+     *
+     * Sans l'attente, un arrêt suivi de la sortie du processus perdait ce qui
+     * était encore dans la file — la preuve de vie FINALE de la présence comprise,
+     * et les pairs gardaient alors ce pod jusqu'au délai d'oubli. Un Redis qui ne
+     * répond plus fait attendre : l'appelant borne (l'arrêt du module le fait).
+     */
     stop(): Promise<void>;
     describe(): IBackplaneInfo;
 }

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

@@ -35,6 +35,29 @@ export interface IEvictUserOrder {
 }
 /** Un ordre de contrôle reconnu. */
 export type ControlOrder = ICloseChannelOrder | IEvictUserOrder;
+/**
+ * Un texte venu du bus est-il recevable — chaîne non vide d'au plus {@link MAX_CONTROL_FIELD_LENGTH} caractères ?
+ *
+ * Seule borne des textes du bus (nom de canal, identifiant de compte), lue par
+ * les ordres de contrôle ET par les messages de présence (ADR-0025 P2).
+ *
+ * @param value - champ reçu (forme inconnue).
+ */
+export declare function isBoundedBusText(value: unknown): value is string;
+/**
+ * La charge est-elle un ordre d'un TYPE que cette version ne connaît pas — `op` lisible, mais hors de la liste fermée ?
+ *
+ * C'est ce qu'émet un serveur d'une version plus récente pendant un
+ * déploiement progressif (ADR-0025, « Règle de lecture du bus ») : l'ordre
+ * n'est pas appliqué, mais il ne se compte pas comme une injection. Rien
+ * d'autre que `op` n'est lu — ses autres champs appartiennent à une version
+ * qui n'est pas celle-ci. Une charge sans `op` textuel, ou d'un type CONNU de
+ * forme fausse, n'est pas « inconnue » : elle est invalide.
+ *
+ * @param payload - la charge du message reçu (forme inconnue).
+ * @returns `true` si le type d'ordre est inconnu de cette version.
+ */
+export declare function isUnknownControlOrder(payload: unknown): boolean;
 /**
  * Lit un ordre de contrôle dans une charge venue du bus — `null` si la forme n'est pas celle d'un ordre connu.
  *

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

@@ -20,6 +20,10 @@ export declare function sealBackplaneEnvelope(msg: IBackplaneMessage, secret?: s
  * `sig`. Sans secret, l'enveloppe nue est acceptée (compat ; l'alerte de boot qui
  * signale ce mode non authentifié est portée par le wiring du driver).
  *
+ * Le sceau se vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+ * forme qu'écrit {@link sealBackplaneEnvelope} — aucune re-sérialisation ; une
+ * autre forme retombe sur la re-sérialisation de la charge lue.
+ *
  * @param raw - message brut lu sur le bus.
  * @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
  * @returns le message vérifié, ou `null` s'il doit être ignoré (malformé, non
@@ -32,9 +36,10 @@ export declare function openBackplaneEnvelope(raw: string, secret?: string | nul
  * binaire du serveur, octets natifs dans `payload`, scellée si un secret est
  * fourni.
  *
- * Scellée, la charge est encodée deux fois — une pour le sceau, une dans
- * l'enveloppe : le codec générique ne permet pas d'assembler l'enveloppe à
- * partir de fragments déjà encodés, comme le fait la voie texte.
+ * Scellée, la charge est encodée UNE fois : le sceau se calcule sur ses octets,
+ * et l'enveloppe s'assemble autour d'eux. Un codec qui n'écrit pas le CBOR le plus
+ * court (constaté, cf {@link framesAsCbor}) encode l'enveloppe entière une seconde
+ * fois — correct pour tout format, plus coûteux.
  *
  * @param msg - message à transporter (canal, charge, origine).
  * @param codec - le codec binaire du serveur (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
@@ -48,10 +53,10 @@ export declare function sealBackplaneEnvelopeBytes(msg: IBackplaneMessage, codec
  * règle que {@link openBackplaneEnvelope} : fail-closed strict sous un secret,
  * aucun downgrade en retirant `sig`.
  *
- * Le sceau se recalcule sur le RÉ-ENCODAGE de la charge décodée, comme la voie
- * texte le fait sur sa re-sérialisation : le codec CBOR du cœur rend la forme la
- * plus courte de chaque valeur, donc émetteur et récepteur signent les mêmes
- * octets.
+ * Le sceau se vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+ * forme qu'assemble l'émetteur — aucun ré-encodage ; une autre forme retombe sur
+ * le ré-encodage de la charge décodée (le codec CBOR du cœur rend la forme la plus
+ * courte de chaque valeur, donc émetteur et récepteur signent les mêmes octets).
  *
  * @param raw - octets lus sur le sujet binaire.
  * @param codec - le codec binaire du serveur.
@@ -59,3 +64,41 @@ export declare function sealBackplaneEnvelopeBytes(msg: IBackplaneMessage, codec
  * @returns le message vérifié, ou `null` s'il doit être ignoré.
  */
 export declare function openBackplaneEnvelopeBytes(raw: Uint8Array, codec: IFrameCodec, secret?: string | null): IBackplaneMessage | null;
+/**
+ * Reconnaît l'**écho** d'un pod — ce que le bus lui renvoie de ses propres
+ * publications — à la FIN du message, sans le décoder (ADR-0021 S6, ADR-0025).
+ *
+ * Un bus pub/sub comme Redis rend à l'émetteur chacune de ses publications : sur un
+ * pod chargé, c'est un message reçu sur deux, et la présence répartie en fait un
+ * signal (le bus est vivant tant que l'écho revient). Le reconnaître coûte, sous un
+ * secret, UN HMAC sur la tranche de la charge : ni `JSON.parse`, ni décodage CBOR.
+ *
+ * Sous un secret, l'écho est VÉRIFIÉ avant d'être compté : un tiers qui forgerait
+ * l'origine de ce pod pour simuler un bus vivant échoue au sceau. Sans secret, rien
+ * ne peut l'être — le bus est ouvert, et le wiring l'annonce au démarrage.
+ *
+ * Un message que ce lecteur ne reconnaît pas (forme tierce, sceau faux) n'est PAS
+ * jeté : il suit la voie ordinaire, qui le vérifie en entier.
+ */
+export declare class BackplaneEcho {
+    #private;
+    /**
+     * @param originId - identité de CE pod sur le bus.
+     * @param secret - secret partagé, ou `null` sur un bus non scellé.
+     */
+    constructor(originId: string, secret: string | null);
+    /**
+     * Ce message texte est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+     *
+     * @param raw - message brut lu sur le sujet texte.
+     */
+    text(raw: string): boolean;
+    /**
+     * Ce message binaire est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+     *
+     * @param raw - octets lus sur le sujet binaire.
+     * @param codec - le codec binaire du serveur ; un codec qui n'écrit pas le CBOR
+     *   attendu (cf {@link framesAsCbor}) laisse tout message à la voie ordinaire.
+     */
+    bytes(raw: Uint8Array, codec: IFrameCodec): boolean;
+}

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

@@ -0,0 +1,48 @@
+import type { IFrameCodec } from "nodefony";
+import type { IBackplaneMessage } from "../../interfaces/IBackplane.js";
+import type { BackplaneNotice } from "./publishQueue.js";
+/**
+ * **Entrée d'un bus partagé** — le tri de ce qu'un pilote reçoit, mutualisé pour
+ * que tout pilote à transport réseau (Redis aujourd'hui ; Kafka, NATS, RabbitMQ…
+ * demain) l'hérite sans le réécrire : écho de ce pod reconnu et compté, sceau
+ * vérifié, refus comptés et annoncés.
+ *
+ * Le pilote ne garde que son transport : il passe chaque message reçu à
+ * {@link text} ou {@link bytes} et remet au hub ce qui en sort.
+ *
+ * Ordre du tri, du moins cher au plus cher :
+ *  1. l'ÉCHO de ce pod se reconnaît à la fin du message, sans le décoder — un HMAC
+ *     sous un secret (cf {@link BackplaneEcho}) ;
+ *  2. sinon, l'enveloppe est ouverte et son sceau vérifié sur la tranche reçue ;
+ *  3. un message ouvert qui porte l'origine de ce pod sous une autre forme est
+ *     encore un écho — compté, jamais réinjecté (anti-boucle).
+ */
+export declare class BackplaneIngress {
+    #private;
+    /**
+     * @param originId - identité de CE pod sur le bus.
+     * @param secret - secret partagé, ou `null` sur un bus non scellé.
+     * @param notice - annonce des sceaux refusés ; omis = silencieux (tests).
+     */
+    constructor(originId: string, secret: string | null, notice?: BackplaneNotice | null);
+    /**
+     * Trie un message reçu sur le sujet TEXTE du bus.
+     *
+     * @param raw - message brut tel que lu sur le transport.
+     * @returns le message à remettre au hub, ou `null` s'il est jeté (écho de ce
+     *   pod, malformé, sceau refusé — chacun compté).
+     */
+    text(raw: string): IBackplaneMessage | null;
+    /**
+     * Trie un message reçu sur le sujet BINAIRE du bus (ADR-0021 S6).
+     *
+     * @param raw - octets tels que lus sur le transport.
+     * @param codec - le codec binaire du serveur.
+     * @returns le message à remettre au hub, ou `null` s'il est jeté.
+     */
+    bytes(raw: Uint8Array, codec: IFrameCodec): IBackplaneMessage | null;
+    /** Échos de ce pod reçus du bus (monotone) — le bus rend ce qu'on y publie. */
+    get echoTotal(): number;
+    /** Messages jetés au sceau refusé, sous un secret (monotone). */
+    get sealRejectedTotal(): number;
+}