@nodefony/realtime 10.0.0-beta.3 → 10.0.0-beta.4

package/dist/_virtual/{_@oxc-project_runtime@0.153.0 → _@oxc-project_runtime@0.155.0}/helpers/esm/decorate.js

@@ -1,9 +1,8 @@
-//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.155.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-//#endregion
 export { __decorate as default };

package/dist/index.js

@@ -17,10 +17,9 @@ import { ClusterBackplane, processIpcTransport } from "./nodefony/src/backplane/
 import { getBackplaneDriver, listBackplaneDrivers, registerBackplaneDriver } from "./nodefony/src/backplane/backplaneRegistry.js";
 import { ClusterProbeClient, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient } from "./nodefony/src/cluster/ClusterProbeClient.js";
 import { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi } from "./nodefony/src/server/RealtimeAdminApi.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
-import { IDENTITY_CHANGED_EVENT, Kernel, Module, services, withTimeout } from "nodefony";
-//#region index.ts
+import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import { IDENTITY_CHANGED_EVENT, Module, services, withTimeout } from "nodefony";
+// index.ts
 /**
 * @nodefony/realtime — Couche realtime serveur Nodefony.
 *
@@ -219,7 +218,6 @@ let Realtime = class Realtime extends Module {
 		}
 	}
 };
-Realtime = __decorate([services([RealtimeService]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Realtime);
+Realtime = __decorate([services([RealtimeService])], Realtime);
 var realtime_default = Realtime;
-//#endregion
 export { ANONYMOUS_REALTIME_TOKEN, BROWSER_ORIGIN, ClusterBackplane, ClusterProbeClient, LoopbackBackplane, MAX_CLIENT_SEVERITY, REDIS_RT_CHANNEL, RESERVED_SYSTEM_PREFIXES, Realtime, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeController, RealtimeHub, RealtimeInbound, RealtimeService, RedisBackplane, SLOW_CONSUMER_BYTES, ServerRealtimeSocket, WsConnectionTransport, buildOwnHealth, buildRealtimeHealth, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, createRealtimeAdminApi, createRedisServiceTransport, createSyslogUplinkHandler, realtime_default as default, defineRealtimeConfig, getBackplaneDriver, getDeclaredBroadcastPrefixes, getRealtimeHub, isReservedSystemChannel, listBackplaneDrivers, mergeClusterHealth, processIpcTransport, processProbeTransport, realtimeConfigJsonSchema, registerBackplaneDriver, resolveBackplaneOriginId, resolveRedisChannel, serverSocket, setClusterProbeClient };

package/dist/nodefony/config/config.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-//#region nodefony/config/config.ts
+// nodefony/config/config.ts
 /**
 * @nodefony/realtime — CONFIGURATION DU MODULE (schéma Zod = source unique).
 *
@@ -62,5 +62,4 @@ const realtimeConfigSchema = z.strictObject({
 * valides par construction ; passés au `super(..., config)` du Module class.
 */
 const config = realtimeConfigSchema.parse({});
-//#endregion
 export { config as default, realtimeConfigSchema };

package/dist/nodefony/config/configSchema.js

@@ -1,6 +1,6 @@
 import { realtimeConfigSchema } from "./config.js";
 import { z } from "zod";
-//#region nodefony/config/configSchema.ts
+// nodefony/config/configSchema.ts
 /**
 * JSON Schema de la configuration de `@nodefony/realtime` — lu SANS démarrer
 * l'application, par `nodefony env` et la notice `.env.example`, qui y
@@ -15,5 +15,4 @@ import { z } from "zod";
 function configJsonSchema() {
 	return z.toJSONSchema(realtimeConfigSchema);
 }
-//#endregion
 export { configJsonSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -1,7 +1,7 @@
 import { realtimeConfigSchema } from "./config.js";
 import { configJsonSchema } from "./configSchema.js";
 import { parseModuleConfig } from "nodefony";
-//#region nodefony/config/defineModuleConfig.ts
+// nodefony/config/defineModuleConfig.ts
 /**
 * Builder type-safe de la configuration de `@nodefony/realtime`.
 *
@@ -83,5 +83,4 @@ function isRealtimeConfig(value) {
 function realtimeConfigJsonSchema() {
 	return configJsonSchema();
 }
-//#endregion
 export { buildRealtimeConfig, defineRealtimeConfig, isRealtimeConfig, realtimeConfigJsonSchema };

package/dist/nodefony/decorators/realtimeDecorators.js

@@ -1,6 +1,6 @@
 import { isCallable, isRecord } from "../src/guards.js";
 import "reflect-metadata";
-//#region nodefony/decorators/realtimeDecorators.ts
+// nodefony/decorators/realtimeDecorators.ts
 /** Clés de métadonnées posées sur le constructor de la classe controller. */
 const ACTIONS_KEY = "realtime:actions";
 const CHANNELS_KEY = "realtime:channels";
@@ -287,5 +287,4 @@ function getDeclaredBroadcastPrefixes() {
 function applyDeclaredBroadcastPrefixes(hub) {
 	for (const prefix of declaredBroadcastPrefixes) hub.markBroadcastChannel(prefix);
 }
-//#endregion
 export { DEFAULT_ACTION_POLICY, RealtimeAction, RealtimeBroadcast, RealtimeChannel, RealtimeInbound, applyDeclaredBroadcastPrefixes, getDeclaredBroadcastPrefixes, getRealtimeActions, getRealtimeChannelPolicies, getRealtimeChannels, getRealtimeInbound };

package/dist/nodefony/interfaces/IRealtimeConnectionState.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,6 +1,6 @@
 import resolveBackplaneOriginId from "./originId.js";
 import { CLUSTER_RT_KIND } from "nodefony";
-//#region nodefony/src/backplane/ClusterBackplane.ts
+// nodefony/src/backplane/ClusterBackplane.ts
 /**
 * Transport de production : `process.send` (émission) + `process.on("message")`
 * (réception). Standalone — utilisable tel quel. En vrai câblage cluster (Phase 3c),
@@ -101,5 +101,4 @@ var ClusterBackplane = class ClusterBackplane {
 		};
 	}
 };
-//#endregion
 export { ClusterBackplane, ClusterBackplane as default, processIpcTransport };

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

@@ -1,5 +1,5 @@
 import resolveBackplaneOriginId from "./originId.js";
-//#region nodefony/src/backplane/LoopbackBackplane.ts
+// nodefony/src/backplane/LoopbackBackplane.ts
 /**
 * Backplane **mono-process no-op** — implémentation de RÉFÉRENCE du port
 * {@link IBackplane} quand il n'existe **aucun pair** (1 process = 1 pod).
@@ -36,5 +36,4 @@ var LoopbackBackplane = class LoopbackBackplane {
 		};
 	}
 };
-//#endregion
 export { LoopbackBackplane, LoopbackBackplane as default };

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

@@ -2,7 +2,7 @@ import { isCallable, isRecord, isThenable } from "../guards.js";
 import resolveBackplaneOriginId from "./originId.js";
 import { openBackplaneEnvelope, sealBackplaneEnvelope } from "./envelope.js";
 import { BackplanePublishQueue } from "./publishQueue.js";
-//#region nodefony/src/backplane/RedisBackplane.ts
+// nodefony/src/backplane/RedisBackplane.ts
 /**
 * BASE du canal Redis **dédié** transportant les enveloppes realtime entre pods.
 * Un seul canal pub/sub par app (les canaux logiques voyagent DANS l'enveloppe,
@@ -189,5 +189,4 @@ var RedisBackplane = class RedisBackplane {
 		};
 	}
 };
-//#endregion
 export { REDIS_RT_CHANNEL, RedisBackplane, RedisBackplane as default, createRedisServiceTransport, isRedisPublisher, isRedisSubscriber, resolveRedisChannel };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/backplane/backplaneRegistry.ts
+// nodefony/src/backplane/backplaneRegistry.ts
 const drivers = /* @__PURE__ */ new Map();
 /**
 * Enregistre (ou remplace) la fabrique d'un driver backplane. Appelé par les
@@ -16,5 +16,4 @@ function getBackplaneDriver(name) {
 function listBackplaneDrivers() {
 	return [...drivers.keys()];
 }
-//#endregion
 export { getBackplaneDriver, listBackplaneDrivers, registerBackplaneDriver };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/backplane/bootNotices.ts
+// nodefony/src/backplane/bootNotices.ts
 /** Le geste qui rend le temps réel partagé entre processus et pods. */
 const REDIS_BACKPLANE_FIX = "use(\"@nodefony/realtime\", { backplane: { driver: \"redis\" } }) + NF_REDIS_URL=redis://…";
 /**
@@ -39,5 +39,4 @@ function realtimeBackplaneDownNotice(driver, reason) {
 		fix: driver === "redis" ? "vérifier NF_REDIS_URL et que Redis répond" : void 0
 	};
 }
-//#endregion
 export { realtimeBackplaneDownNotice, realtimeLocalOnlyNotice };

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

@@ -1,5 +1,5 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
-//#region nodefony/src/backplane/envelope.ts
+// nodefony/src/backplane/envelope.ts
 /**
 * **Sceau d'enveloppe backplane** — authenticité des messages transportés sur un
 * bus **PARTAGÉ** (Redis pub/sub, et tout driver userland cross-host : NATS,
@@ -106,5 +106,4 @@ function openBackplaneEnvelope(raw, secret) {
 	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
 	return msg;
 }
-//#endregion
 export { openBackplaneEnvelope, sealBackplaneEnvelope };

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

@@ -1,6 +1,6 @@
 import { hostname } from "node:os";
 import { randomUUID } from "node:crypto";
-//#region nodefony/src/backplane/originId.ts
+// nodefony/src/backplane/originId.ts
 /**
 * Résout l'identifiant d'origine d'un backplane — l'étiquette que l'anti-écho
 * compare pour jeter les messages qui reviennent à leur émetteur.
@@ -31,5 +31,4 @@ function resolveBackplaneOriginId() {
 	if (!host) return randomUUID();
 	return `${host}:${process.pid}`;
 }
-//#endregion
 export { resolveBackplaneOriginId as default, resolveBackplaneOriginId };

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

@@ -89,5 +89,4 @@ var BackplanePublishQueue = class {
 		};
 	}
 };
-//#endregion
 export { BackplanePublishQueue, BackplanePublishQueue as default, DEFAULT_MAX_QUEUE_BYTES };

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

@@ -1,6 +1,6 @@
 import { isRecord } from "../guards.js";
 import { CLUSTER_PROBE_CTL_KIND, CLUSTER_PROBE_KIND, CLUSTER_PROBE_SNAPSHOT_KIND, RichProcessProbe, isClusterMessage, isClusterProbeEnrich, readOrmRich } from "nodefony";
-//#region nodefony/src/cluster/ClusterProbeClient.ts
+// nodefony/src/cluster/ClusterProbeClient.ts
 /**
 * Vrai si la valeur est une liste de santés d'instance. Le snapshot vient du
 * master du cluster par IPC — un process de la MÊME application, pas le
@@ -291,5 +291,4 @@ function clusterProbeInstance(pid) {
 	if (!health) return null;
 	return health.instances.find((i) => i.process?.pid === pid || i.instanceId === String(pid)) ?? null;
 }
-//#endregion
 export { ClusterProbeClient, ClusterProbeClient as default, clusterProbeHealth, clusterProbeInstance, clusterProbeRequestEnrich, mergeClusterHealth, processProbeTransport, setClusterProbeClient };

package/dist/nodefony/src/guards.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/guards.ts
+// nodefony/src/guards.ts
 /**
 * Gardes de type internes au paquet — elles remplacent une conversion (`as`)
 * par une vérification faite à l'exécution, pour qu'une valeur d'une autre
@@ -37,5 +37,4 @@ function isCallable(value) {
 function isThenable(value) {
 	return isRecord(value) && typeof value.then === "function";
 }
-//#endregion
 export { isCallable, isRecord, isThenable };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/server/AnonymousRealtimeToken.ts
+// nodefony/src/server/AnonymousRealtimeToken.ts
 /**
 * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
 * `IRealtimeAuthenticatorMatcher` ne capture le handshake.
@@ -28,5 +28,4 @@ const ANONYMOUS_REALTIME_TOKEN = Object.freeze({
 	},
 	getAttribute(_key) {}
 });
-//#endregion
 export { ANONYMOUS_REALTIME_TOKEN, ANONYMOUS_REALTIME_TOKEN as default };

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

@@ -2,7 +2,7 @@ import { getRealtimeHub } from "./RealtimeHub.js";
 import { listBackplaneDrivers } from "../backplane/backplaneRegistry.js";
 import { clusterProbeHealth } from "../cluster/ClusterProbeClient.js";
 import { Nodefony, ProcessProbe, readOrmHealth } from "nodefony";
-//#region nodefony/src/server/RealtimeAdminApi.ts
+// nodefony/src/server/RealtimeAdminApi.ts
 const processProbe = new ProcessProbe();
 /**
 * Producteur `IAdminApi` de la **socket Nodefony** — exposé sous
@@ -83,5 +83,4 @@ function createRealtimeAdminApi() {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { buildOwnHealth, buildRealtimeHealth, createRealtimeAdminApi };

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

@@ -5,11 +5,12 @@ import { DEFAULT_ACTION_POLICY, getRealtimeActions, getRealtimeChannelPolicies,
 import { createSyslogUplinkHandler } from "./syslogUplink.js";
 import { WsConnectionTransport } from "../transport/WsConnectionTransport.js";
 import { welcomeEnv } from "./welcomeEnv.js";
+import { subscribedAckFrame } from "./subscribedAck.js";
 import { deniedDetail } from "./deniedDetail.js";
 import { BootConfigurationError, JsonRpcError, JsonRpcPeer, JsonRpcServerError, PLATFORM_INBOUND, RequestContext, RpcEnvelope, RpcError, Scope, identityHint, isJsonRpcId, isPromise, jsonRpcFailure } from "nodefony";
-import { readBackpressureOptions } from "@nodefony/http";
-import { Controller, buildContextParamArgs, getParamArgsMeta } from "@nodefony/framework";
-//#region nodefony/src/server/RealtimeController.ts
+import { isWebsocketContext, readBackpressureOptions, toValidationFields } from "@nodefony/http";
+import { Controller, buildContextParamArgs, getParamArgsMeta, isFrameworkRouter } from "@nodefony/framework";
+// nodefony/src/server/RealtimeController.ts
 /**
 * Une action RPC n'a ni variables de route ni URL : `@Param` et `@Query` y
 * lisent cet objet vide.
@@ -32,6 +33,7 @@ function httpStatusOfFrameError(e) {
 		if (typeof status === "number") return status;
 		return e.code === JsonRpcError.INVALID_PARAMS ? 400 : null;
 	}
+	if (e instanceof Error && toValidationFields(e) !== null) return 422;
 	const code = isRecord(e) ? e.code : void 0;
 	return typeof code === "number" && code >= 400 && code <= 599 ? code : null;
 }
@@ -55,6 +57,10 @@ function toFrameRpcError(e, status, requestId) {
 	if (status !== null) {
 		const data = { status };
 		if (requestId) data.requestId = requestId;
+		if (status === 422 && e instanceof Error) {
+			const fields = toValidationFields(e);
+			if (fields !== null) data.fields = fields;
+		}
 		return new RpcError(e instanceof Error ? e.message : String(e), JsonRpcServerError.DEFAULT, data);
 	}
 	return e;
@@ -125,8 +131,20 @@ var RealtimeController = class extends Controller {
 	constructor(name, context) {
 		new.target.assertScope();
 		super(name, context);
+		this.#connection = isWebsocketContext(context) ? context : null;
 	}
 	/**
+	* La connexion WebSocket que sert CETTE instance — rétrécie UNE fois, ici,
+	* plutôt qu'à chaque frame.
+	*
+	* Sûr parce que l'instance est liée à sa connexion pour toute sa vie : la
+	* portée `singleton` est refusée au constructeur, et le contexte n'est posé
+	* qu'à la construction. `null` si la classe sert aussi une route HTTP et que
+	* cette instance en est issue. Le chemin de chaque frame lit ce champ au lieu
+	* de l'accesseur `context` : une lecture de champ, sans appel.
+	*/
+	#connection;
+	/**
 	* Map des factories de canaux EXACT, lue depuis les décorateurs `@RealtimeChannel`
 	* au handshake (cold-path) et mémoïsée par instance. `null` = pas de décorateur
 	* sur cette classe → la base court-circuite la lecture metadata par frame.
@@ -207,8 +225,8 @@ var RealtimeController = class extends Controller {
 	* écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
 	*/
 	handleRealtime(message) {
-		const ctx = this.context;
-		if (!ctx) return;
+		const ctx = this.#connection;
+		if (ctx === null) throw this.outsideWebsocketError();
 		if (message == null) {
 			this.onHandshake(ctx).catch((e) => {
 				this.log(`WS realtime handshake failed: ${e instanceof Error ? e.message : String(e)}`, "ERROR");
@@ -216,7 +234,28 @@ var RealtimeController = class extends Controller {
 			});
 			return;
 		}
-		ctx.__nfRealtime?.transport.feed(message.toString());
+		const state = ctx.__nfRealtime;
+		if (typeof message === "string") {
+			state?.transport.feed(message);
+			return;
+		}
+		if (state !== void 0) this.receiveBinary(state.transport, message);
+	}
+	/**
+	* Faute de câblage : `handleRealtime` reçu par une instance qui ne sert pas
+	* une connexion WebSocket — route sans `methods: ["WEBSOCKET"]`, ou faux
+	* contexte de test sans `type`. Levée plutôt que passée sous silence : le
+	* client attendrait un welcome qui ne vient jamais. Chemin froid.
+	*/
+	outsideWebsocketError() {
+		return /* @__PURE__ */ new TypeError(`${this.constructor.name}.handleRealtime : cette instance ne sert pas une connexion WebSocket (contexte de type « ${String(this.context?.type)} »). La route doit déclarer requirements: { methods: ["WEBSOCKET"] } ; un faux contexte de test déclare type: "websocket".`);
+	}
+	receiveBinary(transport, data) {
+		if (this.onRealtimeBinary !== void 0) {
+			this.onRealtimeBinary(data);
+			return;
+		}
+		if (transport.discard("binary") === 1) this.log("WS realtime : trame binaire reçue et écartée — le protocole est du JSON-RPC texte ; pour la lire, surcharger onRealtimeBinary()", "WARNING");
 	}
 	/**
 	* **L1 — duplex serveur→client.** Émet une REQUÊTE vers le client de CETTE
@@ -234,9 +273,9 @@ var RealtimeController = class extends Controller {
 	* @throws (rejet) si le handshake n'est pas terminé (aucun peer encore).
 	*/
 	requestClient(method, params, timeoutMs) {
-		const state = this.context.__nfRealtime;
+		const state = this.coldConnState();
 		if (!state) return Promise.reject(/* @__PURE__ */ new Error("requestClient: connexion realtime non établie (welcome non émis)"));
-		return state.peer.request(method, params, timeoutMs);
+		return state.peer.requestAs(method, params, timeoutMs);
 	}
 	/**
 	* Notification CIBLÉE serveur→client (sans réponse) vers CETTE connexion, hors
@@ -245,7 +284,27 @@ var RealtimeController = class extends Controller {
 	* handshake n'est pas terminé.
 	*/
 	notifyClient(method, params) {
-		this.context.__nfRealtime?.peer.notify(method, params);
+		this.#connection?.__nfRealtime?.peer.notify(method, params);
+	}
+	/**
+	* Émet une trame BINAIRE vers CETTE connexion, sans la sérialiser — pendant
+	* sortant de {@link onRealtimeBinary}, et de `NodefonySocket.sendBinary` côté
+	* client. Même contre-pression que les frames JSON-RPC.
+	*
+	* @param data - les octets à émettre (`Uint8Array`, donc un `Buffer` aussi).
+	* @returns `false` si le handshake n'est pas terminé, la connexion fermée ou
+	*   la trame jetée par la contre-pression.
+	*/
+	sendBinaryToClient(data) {
+		return this.coldConnState()?.transport.sendBinary(data) ?? false;
+	}
+	/**
+	* État realtime de CETTE connexion, `undefined` avant le welcome — pour les
+	* chemins FROIDS (requête sortante, binaire). `notifyClient` et la réception
+	* gardent leur lecture en ligne : ils sont sur le chemin de chaque frame.
+	*/
+	coldConnState() {
+		return this.#connection?.__nfRealtime;
 	}
 	/**
 	* Handshake : seams sécurité #4 (Origin RFC 6455 §10.2) + #2 (authenticator
@@ -263,8 +322,7 @@ var RealtimeController = class extends Controller {
 	*  - `authenticate` throw → code 4001 (`unauthorized`).
 	*/
 	async onHandshake(ctx) {
-		const holder = ctx;
-		if (holder.__nfRealtime?.welcomed) return;
+		if (ctx.__nfRealtime?.welcomed) return;
 		const conn = ctx.connection;
 		if (!conn) return;
 		const hub = getRealtimeHub();
@@ -331,6 +389,7 @@ var RealtimeController = class extends Controller {
 			try {
 				parsed = JSON.parse(raw);
 			} catch {
+				if (transport.discard("malformed") === 1) this.log("WS realtime : trame texte illisible (pas du JSON) reçue et écartée", "WARNING");
 				return;
 			}
 			peer.receive(parsed);
@@ -391,7 +450,7 @@ var RealtimeController = class extends Controller {
 			channels: /* @__PURE__ */ new Map(),
 			inbound
 		};
-		holder.__nfRealtime = state;
+		ctx.__nfRealtime = state;
 		ctx.once("onFinish", () => {
 			const liveHub = getRealtimeHub();
 			for (const [channel, sink] of state.channels) liveHub.unsubscribe(channel, sink);
@@ -409,6 +468,7 @@ var RealtimeController = class extends Controller {
 			protocol: "jsonrpc-2.0",
 			channels: announcedChannels,
 			methods: peer.methods,
+			subscriptionAcks: true,
 			...welcomeEnv(env),
 			identity: {
 				type: token.type,
@@ -441,11 +501,25 @@ var RealtimeController = class extends Controller {
 			handler(params, (payload) => state.peer.notify(method, payload));
 		}
 	}
+	/**
+	* Acquitte un abonnement ACCEPTÉ (`realtime:subscribed`) — le seul signal
+	* qui dise au client à partir de quand le flux du canal lui est livré.
+	*
+	* Un refus n'y passe jamais : il a `realtime:denied`. Cold path (1×/canal et
+	* par connexion).
+	*/
+	acknowledgeSubscription(state, channel) {
+		state.transport.send(subscribedAckFrame(channel));
+	}
 	/** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
 	startChannel(ctx, channel) {
 		if (!channel) return;
 		const state = ctx.__nfRealtime;
-		if (!state || state.channels.has(channel)) return;
+		if (!state) return;
+		if (state.channels.has(channel)) {
+			this.acknowledgeSubscription(state, channel);
+			return;
+		}
 		const cap = getRealtimeHub().maxChannelsPerConnection;
 		if (cap !== null && state.channels.size >= cap) {
 			const denied = {
@@ -472,6 +546,7 @@ var RealtimeController = class extends Controller {
 		}, (payload) => JSON.stringify(JsonRpcPeer.buildNotification(channel, payload)))) {
 			state.channels.set(channel, sink);
 			if (isServedByPattern()) getRealtimeHub().noticeUnguardedDynamicChannel(channel);
+			this.acknowledgeSubscription(state, channel);
 			this.log(`WS subscribe → ${channel}`, "DEBUG");
 			return;
 		}
@@ -552,52 +627,21 @@ var RealtimeController = class extends Controller {
 		const method = typeof p?.method === "string" ? p.method.toUpperCase() : "GET";
 		if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") throw new RpcError(`api.request: méthode ${method} non supportée`, JsonRpcError.INVALID_PARAMS);
 		const router = ctx.router;
-		if (!router) throw new RpcError("api.request: router indisponible", JsonRpcServerError.DEFAULT, { status: 500 });
+		if (!isFrameworkRouter(router)) throw new RpcError("api.request: router indisponible", JsonRpcServerError.DEFAULT, { status: 500 });
 		const qIdx = path.indexOf("?");
 		const pathname = qIdx === -1 ? path : path.slice(0, qIdx);
 		const frame = ctx.beginFrame(method, path);
+		let store = null;
 		try {
-			frame?.phaseStart("resolve");
-			let resolver;
-			try {
-				resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
-			} finally {
-				frame?.phaseEnd("resolve");
-			}
-			if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, JsonRpcServerError.DEFAULT, { status: 404 });
-			if (frame) frame.resolver = resolver;
-			if (qIdx !== -1 && qIdx < path.length - 1) {
-				const sp = new URLSearchParams(path.slice(qIdx + 1));
-				const query = {};
-				for (const [k, v] of sp) {
-					const prev = query[k];
-					if (prev === void 0) query[k] = v;
-					else if (Array.isArray(prev)) prev.push(v);
-					else query[k] = [prev, v];
-				}
-				resolver.queryOverride = query;
-			}
 			const token = getRealtimeHub().getTokenForPeer(peer);
-			if (token.isValid) {
-				let valid;
-				frame?.phaseStart("identity");
-				try {
-					valid = await token.isValid();
-				} catch {
-					valid = false;
-				} finally {
-					frame?.phaseEnd("identity");
-				}
-				if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
-			}
 			const renderSink = {};
-			const store = {
-				requestId: ctx.requestId,
+			const frameStore = {
+				requestId: frame?.requestId ?? ctx.requestId,
 				scheme: ctx.scheme,
 				token,
 				user: token.getAttribute("user"),
 				context: ctx,
-				resolver,
+				resolver: void 0,
 				scope: ctx.container instanceof Scope ? ctx.container : void 0,
 				body: p?.body,
 				idempotencyKey: typeof p?.idempotencyKey === "string" ? p.idempotencyKey : void 0,
@@ -605,39 +649,69 @@ var RealtimeController = class extends Controller {
 				invocation: frame ?? void 0,
 				queries: frame?.profilerQueries ?? void 0
 			};
-			let result;
-			try {
-				result = await RequestContext.run(store, async () => {
-					frame?.phaseStart("action");
+			store = frameStore;
+			const result = await RequestContext.run(frameStore, async () => {
+				frame?.phaseStart("resolve");
+				let resolver;
+				try {
+					resolver = router.resolve(ctx, pathname, method === "GET" ? void 0 : method);
+				} finally {
+					frame?.phaseEnd("resolve");
+				}
+				if (!resolver.resolve) throw new RpcError(`api.request: not found ${pathname}`, JsonRpcServerError.DEFAULT, { status: 404 });
+				if (frame) frame.resolver = resolver;
+				frameStore.resolver = resolver;
+				if (qIdx !== -1 && qIdx < path.length - 1) {
+					const sp = new URLSearchParams(path.slice(qIdx + 1));
+					const query = {};
+					for (const [k, v] of sp) {
+						const prev = query[k];
+						if (prev === void 0) query[k] = v;
+						else if (Array.isArray(prev)) prev.push(v);
+						else query[k] = [prev, v];
+					}
+					resolver.queryOverride = query;
+				}
+				if (token.isValid) {
+					let valid;
+					frame?.phaseStart("identity");
 					try {
-						const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
-						const raw = await Promise.resolve(actionResult);
-						if (renderSink.body !== void 0) {
-							const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
-							let body;
-							try {
-								body = JSON.parse(text);
-							} catch {
-								body = text;
-							}
-							const status = renderSink.status;
-							if (status !== void 0 && status >= 400) {
-								const error = isRecord(body) ? body.error : void 0;
-								throw new RpcError(typeof error === "string" ? error : `api.request: HTTP ${status}`, JsonRpcServerError.DEFAULT, {
-									status,
-									body
-								});
-							}
-							return body;
-						}
-						return raw;
+						valid = await token.isValid();
+						if (valid && token.confirmAccount) valid = await token.confirmAccount();
+					} catch {
+						valid = false;
 					} finally {
-						frame?.phaseEnd("action");
+						frame?.phaseEnd("identity");
 					}
-				});
-			} finally {
-				RequestContext.release(store);
-			}
+					if (!valid) throw new RpcError("api.request: identité de session expirée ou invalide", JsonRpcServerError.DEFAULT, { status: 401 });
+				}
+				frame?.phaseStart("action");
+				try {
+					const { result: actionResult } = await resolver.executeActionGuarded(void 0, true);
+					const raw = await Promise.resolve(actionResult);
+					if (renderSink.body !== void 0) {
+						const text = Buffer.isBuffer(renderSink.body) ? renderSink.body.toString("utf8") : renderSink.body;
+						let body;
+						try {
+							body = JSON.parse(text);
+						} catch {
+							body = text;
+						}
+						const status = renderSink.status;
+						if (status !== void 0 && status >= 400) {
+							const error = isRecord(body) ? body.error : void 0;
+							throw new RpcError(typeof error === "string" ? error : `api.request: HTTP ${status}`, JsonRpcServerError.DEFAULT, {
+								status,
+								body
+							});
+						}
+						return body;
+					}
+					return raw;
+				} finally {
+					frame?.phaseEnd("action");
+				}
+			});
 			frame?.finish(200);
 			return frame ? new RpcEnvelope(result, { requestId: frame.requestId }) : result;
 		} catch (e) {
@@ -645,6 +719,7 @@ var RealtimeController = class extends Controller {
 			frame?.finish(status ?? 500, e);
 			throw toFrameRpcError(e, status, frame?.requestId);
 		} finally {
+			if (store !== null) RequestContext.release(store);
 			ctx.collectFrame(frame);
 		}
 	}
@@ -709,5 +784,4 @@ function handshakePath(ctx) {
 		return raw.charCodeAt(0) === 47 ? raw : "/";
 	}
 }
-//#endregion
 export { RealtimeController, RealtimeController as default };