nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/colors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Façade couleur ANSI **chainable** et **isomorphe** — remplace la dépendance
+ * `cli-color` (retirée) en s'appuyant sur `util.styleText` natif (Node 22.13+).
+ *
+ * - **Node** : `clc.red("x")`, `clc.cyan.bgBlue("x")`, `clc.blueBright.bold("x")`
+ *   rendent via `util.styleText` (les styles s'accumulent par accès de propriété,
+ *   appliqués au moment de l'appel). `validateStream: false` → on émet toujours
+ *   les codes ; le gate TTY/`NO_COLOR` est géré en amont (cf {@link setLogColor}
+ *   dans `syslog/logColor.ts`), comme le faisait `cli-color`.
+ * - **Navigateur** : `node:util` est aliasé vers le shim (`client/shim/util.ts`)
+ *   dont le `styleText` est l'identité → jamais d'ANSI (parité ancien shim
+ *   `cli-color` identity Proxy).
+ *
+ * `clc.reset` est la **chaîne brute** `\x1b[0m` (et non une fonction), pour la
+ * parité avec `cli-color` (ex. `process.stdout.write(clc.reset)`).
+ */
+/** Noms de style reconnus (sous-ensemble `util.styleText` utilisé par Nodefony). */
+type StyleName = "reset" | "bold" | "dim" | "italic" | "underline" | "inverse" | "strikethrough" | "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright" | "bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "bgWhite" | "bgGray";
+/**
+ * Fonction de coloration chainable : appelable (`fn(text)`) et indexable
+ * (`fn.bold`, `fn.bgBlue`…), chaque accès renvoyant une nouvelle `ColorFn` aux
+ * styles accumulés.
+ */
+export type ColorFn = ((s: string | number) => string) & {
+    [K in StyleName]: ColorFn;
+};
+/** Racine `clc` : une {@link ColorFn} + la constante brute `reset`. */
+export type Clc = ColorFn & {
+    readonly reset: string;
+};
+declare const clc: Clc;
+export default clc;

package/dist/client/types/src/config/infra.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Résolution de l'INFRA DÉCLARÉE depuis l'environnement (modèle « infra déclarée »).
+ *
+ * L'utilisateur ne configure pas chaque brique : il déclare son infra via des
+ * URLs (pattern Rails/Django/Symfony) :
+ * - `NF_DATABASE_URL` (alias plateforme `DATABASE_URL`) → infra `database` (durable)
+ * - `NF_REDIS_URL` (alias plateforme `REDIS_URL`) → infra `cache` (éphémère partagé)
+ * - `NF_LOKI_URL` / `NF_OPENSEARCH_URL` → infra `logs` (relecture backplane)
+ *
+ * Les briques dont le store vaut `"auto"` sont résolues par l'infra déclarée
+ * ({@link resolveAutoStore}) ; une valeur explicite gagne toujours (moindre
+ * surprise, 12-factor). Aucune cascade runtime implicite : charger un module
+ * ne déplace jamais une brique — seule la déclaration d'infra le fait.
+ */
+/** Dialecte SQL déduit du scheme de l'URL du infra `database`. */
+export type InfraSqlDialect = "sqlite" | "postgres" | "mysql";
+/** Famille du infra `database` — pilote le choix de l'adapter (drizzle/mongoose). */
+export type DatabaseFamily = "sql" | "mongo";
+/** Infra `database` résolu depuis `NF_DATABASE_URL`/`DATABASE_URL`. */
+export interface IInfraDatabase {
+    /** URL déclarée telle quelle (peut porter des credentials — ne jamais logger brute). */
+    url: string;
+    /** Scheme normalisé en minuscules, sans `:` (ex. `postgres`, `sqlite`, `mongodb`). */
+    scheme: string;
+    family: DatabaseFamily;
+    /** Dialecte SQL (famille `sql`) — `null` pour la famille `mongo`. */
+    dialect: InfraSqlDialect | null;
+}
+/** Infra `cache` résolu depuis `NF_REDIS_URL`/`REDIS_URL`. */
+export interface IInfraCache {
+    /** URL redis déclarée (peut porter des credentials — ne jamais logger brute). */
+    url: string;
+}
+/** Infra `logs` (relecture backplane) — les DEUX URLs peuvent être présentes. */
+export interface IInfraLogs {
+    lokiUrl?: string;
+    opensearchUrl?: string;
+}
+/** L'infra déclarée — `null` = non déclarée. */
+export interface IInfra {
+    database: IInfraDatabase | null;
+    cache: IInfraCache | null;
+    logs: IInfraLogs | null;
+    /**
+     * Override GLOBAL de sélection de store (`NF_STORE`) — force TOUTE brique `auto`
+     * vers ce backend, en amont de toute préférence d'infra. Cas d'usage : `memory`
+     * pour un banc de CHARGE (mesurer le framework sans le goulot sqlite/disque), sans
+     * toucher aux configs par brique. `undefined`/`null` = pas d'override. N'affecte
+     * JAMAIS un store configuré EXPLICITEMENT (celui-ci ne passe pas par `auto`).
+     */
+    forceStore?: string | null;
+}
+/** Source d'environnement (forme de `process.env`) — injectable pour les tests. */
+export type InfraEnvSource = Record<string, string | undefined>;
+/**
+ * Parse l'URL du infra `database` : scheme → famille + dialecte.
+ *
+ * @throws Error si le scheme n'est pas supporté — fail-loud au boot : une URL
+ *   de base inconnue ne doit JAMAIS retomber silencieusement sur sqlite.
+ */
+export declare function parseDatabaseUrl(url: string): IInfraDatabase;
+/**
+ * Fichier SQLite d'une URL `sqlite:` du infra `database`.
+ * Formes acceptées : `sqlite::memory:`, `sqlite:./relatif.db`, `sqlite:/abs.db`,
+ * `sqlite:///abs.db`. URL vide après le scheme → `:memory:`.
+ */
+export declare function sqliteFilenameFromUrl(url: string): string;
+/**
+ * Résout les 3 infra déclarée depuis l'environnement. Fonction PURE
+ * (aucun kernel) : consommée par le Kernel (1 fois, mémoïsé), par le contexte
+ * `defineConfig` (`ctx.infra`) et par les builders de config des modules
+ * adapters (drizzle/mongoose/redis) dans leur couche env.
+ *
+ * @param env - source d'environnement (défaut `process.env`).
+ * @throws Error si l'URL du infra `database` a un scheme non supporté.
+ */
+export declare function resolveInfra(env?: InfraEnvSource): IInfra;
+/** Sentinelle des champs `store` : « laisser le framework choisir selon l'infra déclarée ». */
+export declare const AUTO_STORE = "auto";
+/** Infra vide (rien de déclaré) — fallback sûr quand le kernel est absent (tests). */
+export declare const EMPTY_INFRA: IInfra;
+/**
+ * Nature de la donnée d'une brique — pilote l'ordre de préférence des backends :
+ * - `durable` (tokens, passkeys, audit, webhooks, user) → infra database.
+ * - `ephemeral` (idempotence) → infra cache, sinon database.
+ * - `session` → cache, sinon database, sinon fallback fichier.
+ */
+export type StoreKind = "durable" | "ephemeral" | "session";
+/** Choix d'un backend pour `"auto"` + provenance lisible (log de boot, Studio). */
+export interface IAutoStoreResolution {
+    store: string;
+    reason: string;
+}
+/** Catégorie de provenance d'un store résolu (dérivée de la valeur configurée). */
+export type StoreProvenance = "infra" | "explicit";
+/**
+ * Résolution EFFECTIVE d'une brique de persistance, capturée au boot par le
+ * consommateur (au moment exact où il pose son store au container) et retenue
+ * dans le registre du Kernel ({@link IKernel.registerStoreResolution}). C'est la
+ * VÉRITÉ vécue — y compris les replis annoncés du lot 4 (session → `"files"` en
+ * dev) — pas une re-dérivation à la volée. Alimente l'écran Studio « Stores ».
+ */
+export interface IStoreResolution {
+    /** Identifiant de la brique (ex. `"tokens"`, `"session"`, `"audit"`). */
+    brick: string;
+    /** Nature de la donnée — pilote la durabilité affichée ({@link StoreKind}). */
+    nature: StoreKind;
+    /** Valeur configurée telle quelle : `"auto"` (sentinelle) ou un backend explicite. */
+    configured: string;
+    /** Backend effectivement résolu et posé au runtime. */
+    resolved: string;
+    /**
+     * Backends RÉELLEMENT enregistrés pour cette brique (`listXStores()`), capturés
+     * par le consommateur — évite à l'endpoint d'importer les registres (le cœur
+     * `@nodefony/framework` ne peut pas dépendre de `@nodefony/security`/`http`).
+     */
+    available: readonly string[];
+    /**
+     * Provenance : `"infra"` (résolu depuis l'infra déclarée, `configured === "auto"`)
+     * ou `"explicit"` (backend nommé dans la config/env de l'app).
+     */
+    provenance: StoreProvenance;
+    /** Raison lisible (FR) de la résolution — de `resolveAutoStore` ou construite. */
+    reason: string;
+    /** Chemin du champ de config (ex. `"security.tokenStore.store"`) — croise la provenance de champ Studio. */
+    configPath?: string;
+    /**
+     * Emplacement PHYSIQUE lisible du store, lu depuis l'instance au boot
+     * ({@link readStoreLocation}) — base SQLite pour `drizzle`. `undefined`
+     * pour un store `memory` (volatil) ou un backend réseau (l'emplacement = l'infra
+     * déclarée, déjà surfacée à part). Répond à « où sont écrites mes données ? » dans Studio.
+     */
+    location?: string;
+}
+/**
+ * Résout la sentinelle `"auto"` d'une brique en nom de backend, borné aux
+ * backends RÉELLEMENT enregistrés (`available` = `listXStores()` du registre —
+ * reflète l'auto-register des adapters chargés). Couverture partielle d'une infra
+ * (ex. audit sans impl mongoose) → repli `fallback` avec raison ANNONCÉE,
+ * jamais d'échec : le principe « fallback annoncé, pas de dégradation
+ * silencieuse » vit dans la raison retournée, que l'appelant DOIT logger.
+ *
+ * @param kind - nature de la donnée ({@link StoreKind}).
+ * @param infra - infra résolue ({@link resolveInfra}).
+ * @param available - backends enregistrés dans le registre de la brique.
+ * @param fallback - backend de repli (défaut `"memory"` — c'est aussi ce que passe
+ *   le service de session : aucun appelant ne demande un autre repli).
+ */
+export declare function resolveAutoStore(kind: StoreKind, infra: IInfra, available: readonly string[], fallback?: string): IAutoStoreResolution;
+/**
+ * Déduit le nom court du backend d'un store à partir de la classe concrète de
+ * son instance (convention de nommage `<Backend>XxxStore` → `drizzle`, `mongoose`,
+ * `redis`, `memory`, `file`). Sert à retrouver le backend RÉEL d'un adapter posé
+ * au container quand la brique a été résolue en `"auto"` (l'adapter court-circuite
+ * la fabrique nommée). Classe non reconnue → nom de classe brut (honnête).
+ *
+ * @param store - instance de store (lue défensivement — seul `constructor.name`).
+ * @returns nom court du backend, ou `"inconnu"` si l'instance n'expose pas de classe.
+ */
+export declare function deriveStoreBackend(store: unknown): string;
+/**
+ * Lit l'emplacement PHYSIQUE d'un store depuis son instance (getter public
+ * `location`), pour l'écran Studio « Stores » — répond à « où mes données sont-elles
+ * écrites ? ». Un store fichier (passkeys, TOTP, sessions) expose le chemin de son
+ * fichier/dossier ; un store `memory` ou un backend réseau (drizzle/redis/mongoose)
+ * n'expose rien → `undefined` (l'UI dérive « en mémoire » ou renvoie à l'infra).
+ *
+ * @param store - instance de store (lue défensivement — seul un getter `location` string).
+ * @returns chemin lisible, ou `undefined` si le store n'expose pas d'emplacement.
+ */
+export declare function readStoreLocation(store: unknown): string | undefined;

package/dist/client/types/src/kernel/bootReport.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Rapport de boot — **vérité unique** sur le résultat du démarrage du Kernel,
+ * calculé une fois à `onPostReady` et consommé par N canaux (rendu écran dev via
+ * `BootReporter`, log structuré prod, code de sortie pour l'orchestrateur/superviseur,
+ * canal RPC dev, futur endpoint Studio `/nodefony/kernel/api/boot`).
+ *
+ * Objectif : **plus aucun boot qui meurt en silence**. Un profil serveur qui finit
+ * sans aucun serveur en écoute est un échec VISIBLE (`healthy=false`), pas un
+ * « arrêt propre (code 0) » trompeur.
+ */
+/**
+ * Un module ignoré ou en échec **non fatal** pendant le boot (fail-soft). Agrégé
+ * par le Kernel pour expliquer, en une ligne par module, pourquoi le boot est
+ * dégradé — au lieu de N WARNING enterrés dans le JSONL.
+ */
+export interface IBootFailure {
+    /** Nom du module/service en échec (tag `owner`, ou nom d'entrée du manifeste). */
+    module: string;
+    /** Message d'erreur condensé (1ʳᵉ ligne). */
+    reason: string;
+    /**
+     * Étape du boot où l'échec s'est produit :
+     * - `load` — `import()` du module (manifeste) a throw (ex. « Cannot find package »).
+     * - `lifecycle` — un hook `onKernelRegister`/`Boot`/`Ready` a throw/timeout.
+     * - `init` — l'`initialize()` d'un service/module a throw/timeout.
+     */
+    phase: "load" | "lifecycle" | "init";
+    /** `true` si l'échec est un dépassement du timeout de boot. */
+    timedOut?: boolean;
+}
+/**
+ * Un module du manifeste **volontairement NON chargé** par le gating
+ * `policy`/`when` de `config.modules`. Ce n'est PAS un échec (cf {@link IBootFailure})
+ * — mais un gating silencieux se lit comme un module perdu : le bilan de boot
+ * l'affiche AVEC sa raison pour que le dev sache pourquoi son module manque.
+ */
+export interface IBootModuleGated {
+    /** Nom d'entrée du manifeste (`config.modules`). */
+    module: string;
+    /** Raison lisible du non-chargement (ex. `policy "dev" — runtime production`). */
+    reason: string;
+}
+/** Un serveur réseau réellement en écoute à la fin du boot. */
+export interface IBootServerInfo {
+    /** Nom de service interne (`http` | `https` | `websocket` | `websocket-secure`). */
+    type: string;
+    /** Scheme d'URL court et conventionnel (`http` | `https` | `ws` | `wss`). */
+    scheme: string;
+    /** Port d'écoute effectif. */
+    port: number;
+    /** Adresse de bind (`127.0.0.1`, `0.0.0.0`…), si connue. */
+    address?: string;
+    /** URL complète d'accès (`scheme://host:port`) — cliquable au terminal. */
+    url: string;
+}
+/**
+ * Verdict agrégé du dernier boot. `healthy=false` ⇒ le boot est raté ou dégradé de
+ * façon bloquante (typiquement : profil serveur attendu mais 0 serveur en écoute).
+ */
+export interface IBootReport {
+    /** Durée approximative du boot (ms). */
+    durationMs: number;
+    /** Modules effectivement chargés et enregistrés. */
+    modulesLoaded: string[];
+    /**
+     * Nombre d'entrées DÉCLARÉES au manifeste `config.modules`, avant tout gating.
+     *
+     * Distinct de `modulesLoaded` (ce qui a été chargé), de `modulesSkipped` (ce qui
+     * a échoué) et de `modulesGated` (ce qui a été écarté à dessein) : c'est ce que
+     * la configuration LUE demandait. Un manifeste à `0` alors que le profil attend
+     * des serveurs est un état muet — aucune de ces trois listes ne le contient, et
+     * rien n'a été tenté. Vécu : une application dont le manifeste résolu était vide
+     * bootait avec son seul module local puis échouait sur « aucun serveur en
+     * écoute », un diagnostic qui ne menait nulle part.
+     */
+    manifestEntries: number;
+    /** Modules ignorés/échoués en fail-soft (avec la raison). */
+    modulesSkipped: IBootFailure[];
+    /** Modules volontairement non chargés (gating `policy`/`when`) — pas des échecs. */
+    modulesGated: IBootModuleGated[];
+    /**
+     * Logs `WARNING` émis pendant le boot (comptés dans le ring buffer syslog ;
+     * figés à `onPostReady`, comptage à la volée tant que le boot est en cours).
+     */
+    warnings: number;
+    /** Logs `ERROR` et pire (`CRITIC`/`ALERT`/`EMERGENCY`) émis pendant le boot. */
+    errors: number;
+    /**
+     * Les PREMIERS de ces messages, condensés — `null` quand il n'y en a aucun.
+     *
+     * `errors: 1` sans un mot était le cas le plus frustrant du bilan : le
+     * lecteur savait qu'il s'était passé quelque chose, pas quoi. Alloué
+     * seulement s'il y a matière.
+     */
+    criticals: string[] | null;
+    /** `true` si le profil d'exécution attendait des serveurs réseau. */
+    serversExpected: boolean;
+    /** Serveurs réellement en écoute. */
+    serversListening: IBootServerInfo[];
+    /**
+     * Verdict global : `false` si un profil serveur a fini sans aucun serveur en
+     * écoute (garde-fou 0-serveur). Les modules ignorés seuls ne rendent PAS le boot
+     * `unhealthy` (dégradé mais vivant) — seul le 0-serveur attendu est bloquant.
+     */
+    healthy: boolean;
+    /**
+     * Action corrective suggérée d'après les raisons d'échec (ex. « dist périmé ⇒
+     * npm run clean && npm run build » quand un `import()` échoue). `undefined` si
+     * aucune heuristique ne matche. Source unique partagée par le log et l'écran.
+     */
+    remediation?: string;
+}

package/dist/client/types/src/kernel/readinessRegistry.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Registre de disponibilité — ce qui RETIENT la mise en service d'un processus.
+ *
+ * Un pod qui écoute n'est pas un pod qui peut servir : son schéma de base peut
+ * être en retard, un cache peut n'être pas chaud, un service tiers peut n'avoir
+ * pas encore répondu. Ce registre donne à ces composants le seul mot qui leur
+ * manquait — « pas encore » — et l'orchestrateur en tire la conséquence : il
+ * n'envoie pas de trafic, l'ancien exemplaire continue de servir.
+ *
+ * ## La forme est imposée par le chemin sur lequel elle est lue
+ *
+ * La sonde `/readyz` est interrogée toutes les 2 à 10 secondes par le kubelet et
+ * court-circuite TOUT le pipeline (pas de contexte, pas de portée d'injection,
+ * réponses pré-allouées). Le registre stocke donc un **verdict déjà calculé** :
+ * un booléen posé par le contributeur, jamais une fonction que la sonde
+ * attendrait. Lire la disponibilité coûte une comparaison d'entier — zéro
+ * `await`, zéro allocation, zéro appel système.
+ *
+ * Conséquence directe, et c'est la propriété qui fait tout l'intérêt du
+ * mécanisme : **une sonde qui interroge une base tombe avec elle.** Ici elle ne
+ * peut pas : elle lit ce que le contributeur a déjà décidé, à son propre rythme.
+ * Et dès que la cause extérieure est levée — le travail de migration appliqué,
+ * par exemple —, le contributeur repose son verdict et le processus redevient
+ * disponible **tout seul**, sans redéploiement.
+ *
+ * Ce registre n'est pas alloué tant que personne ne s'inscrit : le Kernel le
+ * garde à `null` et le libère quand le dernier contributeur se retire (cf
+ * {@link Kernel.setReadiness}).
+ *
+ * @remarks
+ * À ne pas confondre avec `checks/readiness.ts`, qui regarde une tout autre
+ * question — ce qui empêchera l'application de DÉMARRER sur cette machine
+ * (variable absente, module non installé), constaté par la commande `check`
+ * avant tout démarrage. Ici il s'agit d'un processus DÉJÀ démarré, et de savoir
+ * s'il peut recevoir du trafic maintenant.
+ */
+/** Un contributeur et son verdict, tels qu'un diagnostic les restitue. */
+export interface IReadinessContributor {
+    /** Nom du contributeur — celui qui apparaît au journal et au diagnostic. */
+    readonly name: string;
+    /** Verdict déjà calculé : `false` retient la mise en service. */
+    readonly ready: boolean;
+    /** Ce qui retient, en clair — absent quand le contributeur est prêt. */
+    readonly reason?: string;
+    /**
+     * Ce verdict retient-il le trafic ? `false` = l'état est PUBLIÉ sans être
+     * opposable — le processus sert quand même.
+     *
+     * Cette distinction existe parce que « ce composant va mal » et « n'envoyez
+     * plus de trafic » sont deux affirmations différentes, et que les confondre
+     * a un coût : le noyau garde vivant un exemplaire dont la mise en service est
+     * retenue (il ne sert personne, le tuer ne répare rien et rend inatteignable
+     * la commande qui lèverait la cause). Un composant réglé pour ne PAS retenir
+     * perdait donc, du même geste, cette protection — sans que personne puisse
+     * le deviner.
+     */
+    readonly blocking?: boolean;
+}
+/**
+ * Les contributeurs et le compte de ceux qui retiennent la mise en service.
+ *
+ * Objet nu (`Object.create(null)`) plutôt que `Map` : quelques entrées, accès
+ * ponctuel, aucun héritage de prototype à craindre sur un nom venu d'un module.
+ * Le compte des non-prêts est tenu À L'ÉCRITURE — il n'est jamais recalculé par
+ * parcours, puisque c'est la lecture qui doit rester gratuite.
+ */
+export declare class ReadinessRegistry {
+    private entries;
+    private notReady;
+    private tracked;
+    /** Nombre de contributeurs qui retiennent la mise en service (0 = disponible). */
+    get blocked(): number;
+    /** Nombre de contributeurs inscrits, prêts ou non. */
+    get size(): number;
+    /**
+     * Inscrit ou met à jour un contributeur nommé. Idempotent par nom : un même
+     * nom réenregistré remplace son verdict, il n'ajoute jamais une seconde voix.
+     *
+     * @param name - nom du contributeur (`"drizzle:schema"`, `"cache"`…)
+     * @param ready - verdict DÉJÀ calculé ; `false` retient la mise en service
+     * @param reason - ce qui retient, en clair — ignoré quand `ready` est vrai
+     * @param blocking - `false` pour PUBLIER l'état sans retenir le trafic ; le
+     *   contributeur apparaît alors au diagnostic (et le noyau sait qu'un état
+     *   externe est en cours), mais `/readyz` continue de répondre 200.
+     * @returns `true` si le verdict AGRÉGÉ a basculé (retenu ⇄ disponible)
+     */
+    set(name: string, ready: boolean, reason?: string, blocking?: boolean): boolean;
+    /**
+     * Retire un contributeur — sa voix ne compte plus, ni pour retenir ni pour
+     * libérer. C'est le geste d'un module qui s'arrête.
+     *
+     * @param name - nom du contributeur
+     * @returns `true` si le verdict AGRÉGÉ a basculé (retenu ⇄ disponible)
+     */
+    clear(name: string): boolean;
+    /**
+     * Restitue les contributeurs pour un diagnostic (journal, `status`, console
+     * d'administration) — hors du chemin de la sonde, qui ne lit que
+     * {@link ReadinessRegistry.blocked}.
+     *
+     * @returns un contributeur par entrée, triés par nom (ordre stable)
+     */
+    report(): IReadinessContributor[];
+}

package/dist/client/types/src/realtime/IRealtimeSocket.d.ts

@@ -0,0 +1,142 @@
+/**
+ * IRealtimeSocket — « la socket Nodefony » : la prise temps réel **ISOMORPHE** client↔back.
+ *
+ * C'est LA brique du realtime Nodefony (cf vision « la socket Nodefony ») : un seul lien,
+ * qui a une **existence identique côté back et côté front** (fusionnel), dont le **plan de
+ * contrôle parle JSON-RPC 2.0** ({@link IRealtimePeer}) et qui **multiplexe N canaux** par
+ * souscription. Un consommateur — page front OU service back — tient **UN handle**
+ * (`subscribe / on / publish / request`) : c'est SA socket. Il ignore quel transport porte
+ * les octets, si le pair est local ou distant, et comment chaque canal est servi.
+ *
+ * Vocabulaire : la **socket** est la prise (ce qu'on tient) ; derrière elle, côté serveur,
+ * un **hub** ({@link RealtimeHub}) aiguille entre les N sockets des clients et, à terme,
+ * entre les pods (backplane Redis). La socket multiplexe des canaux ; le hub aiguille entre
+ * les sockets. La couche octets, elle, est le {@link IRealtimeTransport} (≠ « socket » ici).
+ *
+ * ── Un canal = un sous-flux nommé DUPLEX ──
+ *  Chaque canal est un tuyau bidirectionnel multiplexé sur la socket. Son **backing est
+ *  pluggable côté serveur**, transparent pour le consommateur :
+ *   - **pub/sub** (défaut) : notifications JSON-RPC (ex. `nodefony:dashboard`).
+ *   - **encapsulation de protocole** : le canal transporte un AUTRE langage tunnelé dans la
+ *     socket (ex. **SIP** sur `sip:line1`).
+ *   - **bridge** : le canal est câblé vers une autre couche de transport (**TCP/UDP**).
+ *   - **proxy** : le canal relaie vers un autre service.
+ *  Le **backplane Redis** (fan-out cross-pod cloud-native) n'est qu'UN backing parmi ceux-là.
+ *
+ * ── Sémantique des verbes (identique des deux côtés, cible différente) ──
+ *  - `publish(channel, payload)` : émet sur un canal (duplex). Côté **client** → vers le
+ *    serveur (1 pair) ; côté **serveur** → fan-out aux abonnés via le hub (+ backplane).
+ *  - `subscribe` / `unsubscribe` : DEMANDE / arrête un flux (ref-compté).
+ *  - `on` / `off` : REÇOIT (`on` ≠ `subscribe` : l'un branche le handler local, l'autre
+ *    demande au pair de pousser).
+ *  - `request(method, params?)` : RPC corrélé (`Promise` du `result`).
+ *  - `channel(name)` : renvoie un {@link IRealtimeChannel} (objet par canal) — forme
+ *    naturelle des canaux à état (SIP, bridge) et point d'accroche des futures couches
+ *    (codec, cadence AIMD, politique drop/coalesce/batch par canal).
+ *
+ * Impl de référence : {@link RealtimeClient} (navigateur). Côté serveur, le hub à canaux
+ * partagés ({@link RealtimeHub}, fan-out + backings) et une façade consommateur dériveront
+ * de ce même contrat.
+ *
+ * @see {@link IRealtimePeer} — la couche protocole (JSON-RPC 2.0) en dessous.
+ * @see {@link IRealtimeTransport} — la couche octets (le seul maillon client/serveur).
+ */
+import type { ActionsMap, DefaultActionsMap, DefaultEventsMap, EventNames, EventPayload, EventsMap, ContractParams, ContractResult } from "./RealtimeEventMap.js";
+/** Handler d'un canal pub/sub — reçoit le `params` de la notification (ou `(method, params)` sur `"*"`). */
+export type RealtimeHandler = (...args: unknown[]) => void;
+/**
+ * Compteurs d'un canal — **génériques**, calculés au point d'arrivée des frames donc
+ * fiables et réutilisables par toute app. (`RealtimeClient.MessageStats` en est l'alias.)
+ */
+export interface IChannelStats {
+    /** Méthode JSON-RPC == nom du canal pub/sub. */
+    method: string;
+    /** Total de notifications reçues sur ce canal. */
+    msgCount: number;
+    /** Timestamp (ms) de la dernière notification, `null` si aucune. */
+    lastMessage: number | null;
+    /** Débit instantané (msg/s), échantillonné 1×/s. */
+    rate: number;
+    /** Historique du débit (VU-mètre) — fenêtre glissante. */
+    series: number[];
+}
+/**
+ * Handle d'UN canal — vue par-canal d'un sous-flux duplex multiplexé sur la
+ * {@link IRealtimeSocket}. Forme naturelle des canaux à état (un appel SIP, une connexion
+ * bridgée) : il porte son nom, sa nature et son cycle de vie. C'est le **point d'accroche**
+ * des couches à venir (codec de protocole, cadence AIMD, politique `drop|coalesce|batch`) —
+ * elles enrichiront ce handle SANS retoucher la socket.
+ *
+ * N'introduit AUCUN protocole nouveau : fine liaison au-dessus des primitives de la socket
+ * (`subscribe`/`on`/`publish`).
+ */
+export interface IRealtimeChannel {
+    /** Nom du canal (clé de multiplexage == method JSON-RPC des notifications). */
+    readonly name: string;
+    /**
+     * Nature du backing serveur (`pubsub` | `protocol` | `bridge` | `proxy` | …), annoncée
+     * par le serveur. `undefined` tant qu'inconnue (ex. côté client avant découverte).
+     */
+    readonly kind?: string;
+    /** Branche un handler de réception sur ce canal. Renvoie un `dispose`. */
+    on(handler: RealtimeHandler): () => void;
+    /** Émet sur ce canal (duplex, one-way). */
+    send(payload?: unknown): void;
+    /** Ouvre le flux : `subscribe` ref-compté (demande au pair de pousser). */
+    open(): void;
+    /** Ferme : `unsubscribe` ref-compté + retire les handlers branchés via ce handle. */
+    close(): void;
+}
+/**
+ * Contrat de « la socket Nodefony » — voir le bloc de tête du fichier. Implémenté par
+ * {@link RealtimeClient} (front) et, à terme, par une façade serveur au-dessus du hub.
+ *
+ * @typeParam Emit    — canaux pub/sub SORTANTS (typage de `publish`).
+ * @typeParam Listen  — canaux pub/sub RÉCEPTIONNÉS (typage de `subscribe`/`on`/`off`).
+ * @typeParam Actions — contrat RPC bidirectionnel (typage de `request`).
+ *
+ * Défauts permissifs sur les 3 → rétro-compat 100% pour le code non paramétré.
+ *
+ * **Pattern « type conditionnel inline »** : chaque méthode a UNE signature unique
+ * paramétrée par un `K extends string`. Si `K` matche la map (`EventNames<Listen>`,
+ * `EventNames<Emit>`, `ActionNames<Actions>`) → typage strict ; sinon → fallback
+ * permissif (`unknown`/`RealtimeHandler`). Permet les noms système (`__notice__`,
+ * `*`, `subscribe`/`unsubscribe` internes) à côté du contrat applicatif typé sans
+ * 2 overloads incompatibles en variance.
+ */
+export interface IRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> {
+    /**
+     * S'abonne à un canal (ref-compté) : émet la demande au pair UNIQUEMENT au 1ᵉʳ
+     * consommateur ; ré-émise automatiquement à chaque (re)connexion. Ne REÇOIT pas —
+     * brancher {@link IRealtimeSocket.on} pour ça.
+     */
+    subscribe(channel: EventNames<Listen> | (string & {})): void;
+    /** Désabonne un consommateur (ref-compté) : coupe le flux réseau au DERNIER. No-op si non suivi. */
+    unsubscribe(channel: EventNames<Listen> | (string & {})): void;
+    /**
+     * Branche un handler sur un canal (réception). Renvoie un `dispose` (désabonnement
+     * local). Plusieurs handlers par canal autorisés.
+     */
+    on<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void;
+    /** Retire un handler d'un canal. */
+    off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void;
+    /**
+     * Émet sur un canal (one-way, pas de réponse). Côté client → notification au serveur ;
+     * côté serveur → fan-out aux abonnés via le hub (+ backplane). No-op si non connecté.
+     */
+    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    /** RPC corrélé — `Promise` résolue avec le `result` (rejette sur `error`/timeout). */
+    request<K extends string, T = unknown>(method: K, params?: ContractParams<Actions, K>, timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
+    /**
+     * Vue par-canal — voir {@link IRealtimeChannel}. Fine liaison sur les primitives
+     * ci-dessus ; forme cible pour SIP/bridge/proxy et les concerns par-canal.
+     */
+    channel(name: string): IRealtimeChannel;
+    /** Snapshot des compteurs par canal (refs internes — à LIRE, pas à muter). */
+    getStats(): IChannelStats[];
+    /** Compteurs d'un canal précis (== method JSON-RPC) ou `undefined`. */
+    getChannelStats(channel: string): IChannelStats | undefined;
+    /** Canaux actuellement abonnés (≥ 1 consommateur). Lecture seule. */
+    readonly subscribedChannels: string[];
+}
+export default IRealtimeSocket;

package/dist/client/types/src/realtime/IRealtimeTransport.d.ts

@@ -0,0 +1,50 @@
+/**
+ * IRealtimeTransport — le SEUL maillon qui diffère client/serveur.
+ *
+ * Le protocole ({@link JsonRpcPeer}) et les « smarts » (stats, pub/sub) sont
+ * isomorphes ; seule la façon dont les **octets** entrent et sortent change. On
+ * isole donc le transport derrière cette interface : un même endpoint compose
+ * N transports.
+ *
+ * Implémentations :
+ *  - `BrowserWsTransport` (navigateur, `WebSocket` + reconnect géré au-dessus)
+ *  - `WsConnectionTransport` (serveur, wrap d'une connexion `ws` — P… RealtimeController)
+ *  - futurs P13 : `Tcp`/`Udp`/`Redis`/`SipTransport` (RealtimeService / IRealtimeHub)
+ *
+ * Les états suivent les constantes `WebSocket` (0..3) pour rester universels —
+ * voir {@link TransportState}.
+ *
+ * ── Sens des flux ──
+ *  Sortant : `send` (frame brute déjà sérialisée), `close`.
+ *  Entrant : le owner branche `onMessage` (chaque frame reçue) ; `onOpen`/`onClose`/
+ *  `onError` pilotent le cycle de vie (l'orchestration reconnect/heartbeat vit
+ *  AU-DESSUS, dans l'endpoint — le transport reste « bête »).
+ */
+/** États d'un transport — alignés sur les constantes `WebSocket`. */
+export declare const TransportState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+export type TransportStateValue = (typeof TransportState)[keyof typeof TransportState];
+export interface IRealtimeTransport {
+    /** Ouvre le transport (asynchrone — l'ouverture effective est signalée par `onOpen`). */
+    connect(): void;
+    /** Envoie une frame brute (déjà sérialisée). No-op si non ouvert. */
+    send(raw: string): void;
+    /** Ferme le transport (déclenche `onClose`). */
+    close(code?: number, reason?: string): void;
+    /** État courant (0..3, cf {@link TransportState}). */
+    readonly readyState: number;
+    /** Branche le handler d'ouverture (le owner relance subscribe/heartbeat). */
+    onOpen(cb: () => void): void;
+    /** Branche le pump entrant : appelé pour chaque frame brute reçue. */
+    onMessage(cb: (raw: string) => void): void;
+    /** Branche la fermeture (le owner relance le backoff ou nettoie). */
+    onClose(cb: (code: number, reason: string) => void): void;
+    /** Branche les erreurs transport (la fermeture qui suit gère le reconnect). */
+    onError(cb: (err: unknown) => void): void;
+}
+/** Fabrique d'un transport pour une URL — injectable (tests, transports alternatifs). */
+export type RealtimeTransportFactory = (url: string) => IRealtimeTransport;