nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/syslog/drivers/ILogDriver.d.ts

@@ -0,0 +1,177 @@
+import type { FlowStepId } from "./pduFlow.js";
+/**
+ * Contrat du **Log Backplane** (axe DESTINATION queryable, LB.0).
+ *
+ * À NE PAS confondre avec {@link ILogSink} (LB.W) : `ILogSink` écrit la **ligne
+ * texte** déjà coalescée (`writeOut(s: string)`) vers stdout/fichier/null et ne
+ * voit jamais les Pdu structurés → incapable de relire/filtrer. `ILogDriver`, lui,
+ * est la **destination des Pdu structurés** : il sait les **stocker** (write) ET
+ * les **relire** (query). Les deux sont liés dans le même driver (cohérence
+ * « j'écris dans Elastic → je relis dans Elastic »).
+ *
+ * - `memory` (défaut dev) : le ring buffer `Syslog` EST le stockage → `query`
+ *   = {@link filterPdus} sur `syslog.ringStack`. Aucun write dédié (le ring est
+ *   alimenté par `Syslog.pushStack`).
+ * - `file` (JSONL, LB.2), `elastic`/`loki` (LB.4) : write = persistance des Pdu,
+ *   query = scan / API externe. Drivers Node-only enregistrés à part.
+ *
+ * Le driver actif est sélectionné par {@link logDriverRegistry} (config/env, ou
+ * action de contrôle dev-only). Le **bus temps réel** (`nodefony:syslog`) reste
+ * indépendant : il diffuse les Pdu live quel que soit le driver (même non-queryable).
+ */
+export interface ILogDriver {
+    /** Nom unique du driver (`"memory"` | `"file"` | `"elastic"` | custom). */
+    readonly name: string;
+    /** Ce que le driver sait faire (pilote l'UI Studio + le contrat data-plane). */
+    readonly capabilities: ILogDriverCapabilities;
+    /**
+     * Interroge la destination — chemin **FROID** (admin/debug), `async`, **JAMAIS**
+     * dans le pipeline requête. Absent si `capabilities.query === false` (ex. `console`).
+     *
+     * @param criteria - critères de filtrage (tous optionnels, combinés en AND).
+     * @returns enregistrements (récents d'abord) + total avant pagination.
+     */
+    query?(criteria: ILogQueryCriteria): Promise<ILogQueryResult>;
+    /**
+     * Sonde de SANTÉ de la destination (chemin FROID, admin) — « est-ce que la cible
+     * répond, en combien de temps, et quelques infos utiles ? ». Présent surtout sur
+     * les drivers DISTANTS (loki/opensearch) où la joignabilité n'est pas acquise ;
+     * absent sur les drivers locaux triviaux (memory). Ne `throw` JAMAIS : un échec se
+     * traduit par `{ ok:false, detail }` (l'admin doit voir la panne, pas un crash).
+     *
+     * @returns joignabilité + latence + infos (version, statut, nb d'entrées…).
+     */
+    probe?(): Promise<ILogDriverProbe>;
+}
+/**
+ * Résultat d'une {@link ILogDriver.probe} — santé d'une destination de logs.
+ * Affiché par Studio (badge joignable/latence + infos) ; jamais de credential.
+ */
+export interface ILogDriverProbe {
+    /** `true` si la destination répond correctement. */
+    ok: boolean;
+    /** Latence aller-retour de la sonde (ms). */
+    latencyMs: number;
+    /** Message d'erreur si `ok === false` (jamais de secret). */
+    detail?: string;
+    /** Infos utiles à afficher (version, statut cluster, nb d'entrées, endpoint…). */
+    info?: Record<string, string | number>;
+}
+/** Capacités déclarées d'un driver (introspection Studio + garde-fous endpoint). */
+export interface ILogDriverCapabilities {
+    /** Le driver persiste les Pdu (≠ ring volatile). `memory` = false (volatile). */
+    readonly write: boolean;
+    /** Le driver expose `query()` (relecture filtrée). `console` = false. */
+    readonly query: boolean;
+    /** Le driver peut alimenter un flux temps réel (tap `onLog`). */
+    readonly stream: boolean;
+}
+/**
+ * Critères de requête — tous optionnels, combinés en **AND**. Vide = tout (borné
+ * par `limit`). Les comparaisons string sont insensibles à la casse. `requestId`
+ * matche **exactement** (trace full-stack ciblée d'UNE requête) ; `module`/`msgid`/
+ * `text` matchent par **inclusion**.
+ */
+export interface ILogQueryCriteria {
+    /** Corrélation log↔requête (ALS) — match EXACT. La clé de la trace full-stack. */
+    requestId?: string;
+    /** Nom(s) de sévérité RFC 5424 (`"ERROR"` ou `["ERROR","CRITIC"]`). Insensible casse. */
+    severity?: string | string[];
+    /** Nom de module/service — inclusion insensible à la casse. */
+    module?: string;
+    /** Catégorie de message (msgid) — inclusion insensible à la casse. */
+    msgid?: string;
+    /** Borne basse du `timeStamp` (epoch ms, inclus). */
+    from?: number;
+    /** Borne haute du `timeStamp` (epoch ms, inclus). */
+    to?: number;
+    /** Recherche plein-texte (payload string + msg + module + msgid). Insensible casse. */
+    text?: string;
+    /**
+     * Protocole d'origine du log :
+     *  - `"ws"` : logs émis dans un contexte WebSocket (`msgid === "WEBSOCKET CONTEXT"`) ;
+     *  - `"http"` : tout le reste du pipeline (requête HTTP, router, firewall, applicatif).
+     *
+     * Absent = les deux protocoles. Classification PURE, cf `pduProtocol`.
+     */
+    protocol?: "ws" | "http";
+    /**
+     * Étape(s) du cycle de vie d'une requête/connexion — classification STRUCTURÉE
+     * (cf `pduFlowStep`), pas une recherche texte. Ex. `"ws-open"` ou
+     * `["request-in","route-matched"]`. Tableau = OU entre étapes ; combiné en AND
+     * avec les autres critères. Absent = toutes les étapes.
+     */
+    flow?: FlowStepId | FlowStepId[];
+    /** Nombre max d'enregistrements renvoyés (le driver borne à un plafond sûr). */
+    limit?: number;
+    /** Décalage de pagination (depuis le plus récent). */
+    offset?: number;
+    /**
+     * Ordre chronologique des `rows` :
+     *  - `"desc"` (DÉFAUT) : du plus RÉCENT au plus ancien (entrée naturelle d'un viewer) ;
+     *  - `"asc"` : du plus ANCIEN au plus récent (lecture chronologique d'une trace).
+     *
+     * L'ordre s'appuie sur l'`uid` du Pdu (compteur monotone d'émission) → garantit
+     * la **chronologie exacte même à `timeStamp` égal** (plusieurs logs dans la même ms).
+     */
+    order?: "asc" | "desc";
+}
+/**
+ * Forme **wire** d'un Pdu (isomorphe) — sérialisation stable partagée par TOUTES
+ * les façades (endpoint data-plane, canal `nodefony:syslog`, drivers). Le front
+ * réhydrate via `Object.assign(new Pdu(""), record)` → une seule logique de rendu.
+ * Produite par {@link pduToRecord}.
+ */
+export interface ILogRecord {
+    uid: number;
+    severity: number;
+    severityName: string;
+    moduleName: string;
+    msgid: string;
+    msg: string;
+    timeStamp: number;
+    /** PID émetteur (procid RFC 5424) — groupe par worker en cluster. */
+    pid: number;
+    /** Corrélation requête (ALS) si présent. `undefined` ignoré par `JSON.stringify`. */
+    requestId?: string;
+    /** Contenu brut (string/Error/objet). Narrower côté lecteur. */
+    payload: unknown;
+}
+/** Résultat d'une requête : enregistrements (récents d'abord) + méta de pagination. */
+export interface ILogQueryResult {
+    /** Enregistrements du plus RÉCENT au plus ancien, après `offset`/`limit`. */
+    rows: ILogRecord[];
+    /** Nombre total d'enregistrements qui matchent les critères (avant pagination). */
+    total: number;
+    /** `true` s'il reste des résultats au-delà de la fenêtre renvoyée. */
+    truncated: boolean;
+}
+/**
+ * Sous-ensemble des champs d'un `Pdu` lus par {@link filterPdus} et
+ * {@link pduToRecord}. Permet de filtrer/projeter SANS instancier un `Pdu` — son
+ * constructeur incrémente un compteur d'`uid` et lit le `requestIdProvider`, donc
+ * effets de bord à proscrire lors d'une simple RELECTURE. Un `Pdu` le satisfait
+ * structurellement ; un enregistrement relu d'un fichier JSONL (driver `file`,
+ * LB.2) aussi → une SEULE logique de filtrage pour memory, file et le futur CLI.
+ */
+export interface IPduLike {
+    uid: number;
+    severity: number;
+    severityName: string;
+    moduleName: string;
+    msgid: string;
+    msg: string;
+    timeStamp: number;
+    pid: number;
+    payload: unknown;
+    requestId?: string;
+}
+/**
+ * Sérialise un Pdu en {@link ILogRecord} (forme wire). Source unique de la
+ * projection Pdu→wire : réutilisée par {@link filterPdus} (driver memory) ET par
+ * le producteur data-plane `syslog` (framework) — pas de shape dupliqué qui dérive.
+ *
+ * @param pdu - Pdu (instance ou objet structurellement compatible — {@link IPduLike}).
+ * @returns enregistrement plat sérialisable. `requestId` omis si absent.
+ */
+export declare function pduToRecord(pdu: IPduLike): ILogRecord;

package/dist/types/syslog/drivers/LokiLogDriver.d.ts

@@ -0,0 +1,44 @@
+import type { ILogDriver } from "./ILogDriver.js";
+import type { FetchLike } from "../httpFetch.js";
+export interface LokiLogDriverOptions {
+    /** Base URL de Loki, ex. `http://127.0.0.1:3100`. */
+    url: string;
+    /** Labels de sélecteur de base (mêmes que le transport). Défaut `{ app: "nodefony" }`. */
+    labels?: Record<string, string>;
+    /** Tenant multi-tenancy → header `X-Scope-OrgID`. */
+    tenantId?: string;
+    /** Headers HTTP additionnels. */
+    headers?: Record<string, string>;
+    /**
+     * Budget de scan : nombre max de lignes RAPATRIÉES de Loki avant filtrage local
+     * (chemin admin FROID, anti-OOM). Défaut 1000. La pagination fine (`limit`/`offset`)
+     * est appliquée APRÈS par {@link filterPdus} sur ce sous-ensemble.
+     */
+    maxScanLines?: number;
+    /**
+     * Fenêtre temporelle par défaut quand `from`/`to` sont absents (ms avant `now`).
+     * Loki EXIGE un intervalle borné. Défaut 24 h.
+     */
+    defaultLookbackMs?: number;
+    /** Timeout de la query (ms). Défaut 8000. */
+    timeoutMs?: number;
+    /** Implémentation `fetch` (tests / proxy). Défaut : `fetch` global. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Driver `loki` du Log Backplane (LB.4) — relit les logs dans **Grafana Loki** via
+ * LogQL (`GET /loki/api/v1/query_range`). **Adaptateur, pas moteur** : Loki BORNE le
+ * rapatriement (sélecteur de labels + fenêtre temporelle + grep + budget de lignes),
+ * puis {@link filterPdus} est l'**autorité finale** sur le sous-ensemble rapatrié →
+ * sémantique EXACTEMENT identique aux drivers `memory`/`file` (inclusion insensible à
+ * la casse, ordering `uid`, pagination). Une logique, N façades.
+ *
+ * Chaque ligne Loki est le record wire JSON écrit par {@link LokiTransport} → `JSON.parse`
+ * + {@link coerceRecord} (lignes corrompues ignorées). Chemin **FROID** (admin/debug),
+ * jamais dans le pipeline requête. Loki injoignable / requête invalide → `throw` explicite
+ * (≠ `file` absent : une infra de logs prod en panne DOIT être visible, pas masquée).
+ *
+ * @param options - URL Loki + labels + budgets.
+ * @returns un `ILogDriver` `loki` queryable (Node-only).
+ */
+export declare function createLokiLogDriver(options: LokiLogDriverOptions): ILogDriver;

package/dist/types/syslog/drivers/MemoryLogDriver.d.ts

@@ -0,0 +1,20 @@
+import type { ILogDriver, IPduLike } from "./ILogDriver.js";
+/**
+ * Driver `memory` (LB.1) — le **ring buffer du Syslog EST le stockage**. Aucun
+ * write dédié : le ring est alimenté par `Syslog.pushStack` sur le hot path. Le
+ * driver n'ajoute que la **relecture** (`query`) = {@link filterPdus} sur un
+ * snapshot du ring.
+ *
+ * Défaut en développement : volatile (perdu au restart), borné (`maxStack`), mais
+ * **0 dépendance, isomorphe** (pas de `node:*` → utilisable côté navigateur plus
+ * tard pour un Log Backplane front). Pour persister/agréger en prod → drivers
+ * `file` (LB.2) / `elastic`-`loki` (LB.4).
+ *
+ * La **source** est injectée (provider `() => IPduLike[]`, comme `Pdu.requestIdProvider`)
+ * → le driver ne dépend pas de `Syslog` ni du `Kernel` (le wiring fournit
+ * `() => kernel.syslog.ringStack`). Découplé + testable avec un tableau en dur.
+ *
+ * @param source - fournit le snapshot courant des Pdu (ex. `() => syslog.ringStack`).
+ * @returns un `ILogDriver` `memory` queryable.
+ */
+export declare function createMemoryLogDriver(source: () => IPduLike[]): ILogDriver;

package/dist/types/syslog/drivers/OpenSearchLogDriver.d.ts

@@ -0,0 +1,40 @@
+import type { ILogDriver } from "./ILogDriver.js";
+import type { FetchLike } from "../httpFetch.js";
+export interface OpenSearchLogDriverOptions {
+    /** Base URL d'OpenSearch, ex. `http://127.0.0.1:9200`. */
+    url: string;
+    /** Index interrogé (défaut `nodefony-logs`). Doit matcher le transport. */
+    index?: string;
+    /** Utilisateur (auth basic) — prod avec plugin sécurité activé. */
+    username?: string;
+    /** Mot de passe (auth basic). */
+    password?: string;
+    /** Headers HTTP additionnels. */
+    headers?: Record<string, string>;
+    /**
+     * Budget de scan : nombre max de documents RAPATRIÉS (`size`) avant filtrage local
+     * (chemin admin FROID, anti-OOM). Défaut 1000. La pagination fine est ensuite
+     * appliquée par {@link filterPdus}.
+     */
+    maxHits?: number;
+    /** Timeout de la query (ms). Défaut 8000. */
+    timeoutMs?: number;
+    /** Implémentation `fetch` (tests / proxy). Défaut : `fetch` global. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Driver `opensearch` du Log Backplane (LB.4) — relit les logs dans **OpenSearch**
+ * via `POST /{index}/_search` (Query DSL). **Adaptateur, pas moteur** : OpenSearch
+ * borne le rapatriement (range sur `timeStamp` + `sort` desc + budget `size`), puis
+ * {@link filterPdus} est l'**autorité finale** sur le sous-ensemble → sémantique
+ * identique aux drivers `memory`/`file`. Une logique, N façades.
+ *
+ * Chaque `_source` est le record wire indexé par {@link OpenSearchTransport} →
+ * {@link coerceRecord} (documents non conformes ignorés). Chemin **FROID** (admin/debug).
+ * Index encore absent (404 `index_not_found`) → résultat VIDE (normal : aucun log
+ * indexé). Vraie panne (réseau, 5xx) → `throw` explicite (infra de logs prod visible).
+ *
+ * @param options - URL OpenSearch + index + budget.
+ * @returns un `ILogDriver` `opensearch` queryable (Node-only).
+ */
+export declare function createOpenSearchLogDriver(options: OpenSearchLogDriverOptions): ILogDriver;

package/dist/types/syslog/drivers/builtinLogDrivers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Résout le driver de relecture EFFECTIF depuis la valeur demandée, le mode de
+ * lancement et les destinations distantes déclarées. La sentinelle `"auto"`
+ * (défaut du framework) S'ADAPTE :
+ * 1. une destination distante déclarée (URL loki/opensearch — infra logs) impose
+ *    son driver : l'URL ⇒ le driver, un seul knob. Les DEUX déclarées sans choix
+ *    explicite = throw (fail-loud : pas d'arbitrage silencieux entre deux
+ *    destinations de relecture) ;
+ * 2. sinon un worker de cluster (process forké) relit via `cluster-file` — vue
+ *    UNIFIÉE agrégeant les JSONL de tous les workers — là où `memory` (ring
+ *    per-worker) ne montrerait qu'un worker ; un mono-process reste sur
+ *    `memory` (0 I/O).
+ *
+ * On n'intervient QUE sur le défaut : toute valeur EXPLICITE (`memory`, `file`,
+ * `loki`, …) est une surcharge de l'opérateur → respectée telle quelle, jamais
+ * réécrite (principe de moindre surprise, 12-factor).
+ *
+ * @param requested - `log.queryDriver` résolu (config app/env) ; `undefined` ou
+ *   `"auto"` = laisser le framework décider.
+ * @param isWorker - process forké d'un cluster (`cluster.isWorker`).
+ * @param urls - URLs des destinations distantes déclarées (config `log.loki`/
+ *   `log.opensearch`, montées depuis l'infra logs).
+ * @returns nom du driver de relecture à activer + monter.
+ * @throws Error si les deux URLs sont déclarées sans `queryDriver` explicite.
+ */
+export declare function resolveQueryDriver(requested: string | undefined, isWorker: boolean, urls?: {
+    loki?: string;
+    opensearch?: string;
+}): string;
+/**
+ * Enregistre les fabriques des drivers NATIFS du Log Backplane dans le
+ * {@link registerLogDriverFactory registre de fabriques}. Idempotent (appelé à chaque
+ * `initializeLog`, court-circuité après la 1ʳᵉ fois). C'est ICI — pas dans le Kernel —
+ * que vit la connaissance « nom → comment construire ce driver ». Le Kernel ne fait que
+ * résoudre + brancher, sans aucun `if (name === …)`.
+ *
+ * - `memory` : relit le ring buffer (aucun transport — alimenté par `Syslog`).
+ * - `file` / `cluster-file` : relisent un/des JSONL ; écrivent via un `FileTransport`
+ *   partagé (même `writeKey` = chemin → branché 1× même si les deux sont montés).
+ * - `loki` / `opensearch` : push HTTP batché (transport) + relecture via leur API
+ *   (driver) ; `null` si l'URL n'est pas configurée (→ fallback `memory` côté Kernel).
+ */
+export declare function registerBuiltinLogDrivers(): void;

package/dist/types/syslog/drivers/filterPdus.d.ts

@@ -0,0 +1,21 @@
+import { type ILogQueryCriteria, type ILogQueryResult, type IPduLike } from "./ILogDriver.js";
+/**
+ * Filtre PUR d'un tableau de Pdu selon des critères — **0 I/O, 0 état, testable
+ * sans serveur**. C'est LA logique de filtrage du Log Backplane, réutilisée par le
+ * driver `memory` (sur `syslog.ringStack`), le futur driver `file` (sur les lignes
+ * relues) et la future commande CLI `syslog:filter`. Une logique, trois façades.
+ *
+ * Critères combinés en **AND** (cf {@link ILogQueryCriteria}). Résultat trié du
+ * plus **RÉCENT** au plus ancien (l'entrée naturelle d'un viewer de logs), puis
+ * `offset`/`limit` appliqués. `total` = nombre de matchs AVANT pagination.
+ *
+ * Perf : scan linéaire O(N) sur un ring borné (≤ `maxStack`, ~100-1000). Chemin
+ * FROID (admin/debug) → jamais dans le pipeline requête. La sérialisation
+ * (Pdu→{@link ILogRecord}) n'est faite que sur la **fenêtre renvoyée**, pas sur
+ * tous les matchs.
+ *
+ * @param pdus - snapshot de Pdu (ex. `syslog.ringStack`, ordre FIFO oldest→newest).
+ * @param criteria - critères de filtrage (tous optionnels).
+ * @returns enregistrements récents d'abord + total + flag de troncature.
+ */
+export declare function filterPdus(pdus: IPduLike[], criteria?: ILogQueryCriteria): ILogQueryResult;

package/dist/types/syslog/drivers/logDriverRegistry.d.ts

@@ -0,0 +1,100 @@
+import type { ILogDriver, IPduLike } from "./ILogDriver.js";
+import type { ITransport } from "../../types/ITransport.js";
+/**
+ * Enregistre (ou remplace) un driver par son nom. Si aucun driver actif n'est
+ * encore défini, le premier enregistré devient actif (défaut sain).
+ *
+ * @param driver - instance `ILogDriver` (porte son propre `name`).
+ */
+export declare function registerLogDriver(driver: ILogDriver): void;
+/**
+ * Sélectionne le driver actif par nom (relecture des logs).
+ *
+ * @param name - nom d'un driver enregistré.
+ * @returns le driver activé.
+ * @throws si le nom est inconnu (jamais activer un driver fantôme silencieusement).
+ */
+export declare function setActiveLogDriver(name: string): ILogDriver;
+/** Driver actif (relecture), ou `null` si aucun n'est encore enregistré/câblé. */
+export declare function getActiveLogDriver(): ILogDriver | null;
+/**
+ * Récupère un driver ENREGISTRÉ par son nom SANS l'activer — pour le sonder
+ * (`probe`) ou l'introspecter avant un switch. `undefined` si non enregistré.
+ */
+export declare function getLogDriver(name: string): ILogDriver | undefined;
+/** Liste des drivers enregistrés (introspection Studio / tests / data-plane). */
+export declare function listLogDrivers(): {
+    name: string;
+    capabilities: ILogDriver["capabilities"];
+}[];
+/**
+ * Sous-ensemble de `config.log` lu par les fabriques — évite une dépendance des
+ * drivers au type complet du Kernel (qui, lui, importe les drivers).
+ */
+export interface ILogConfigLike {
+    queryFile?: {
+        path?: string;
+        maxScanBytes?: number;
+    };
+    loki?: {
+        url: string;
+        labels?: Record<string, string>;
+        tenantId?: string;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        maxQueue?: number;
+        maxScanLines?: number;
+    };
+    opensearch?: {
+        url: string;
+        index?: string;
+        username?: string;
+        password?: string;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        maxQueue?: number;
+        maxHits?: number;
+    };
+}
+/** Contexte passé à une fabrique de driver (tout ce qu'il faut pour se construire). */
+export interface ILogDriverContext {
+    /** Config `log` de l'app (sous-ensemble lu par les fabriques). */
+    logCfg: ILogConfigLike | undefined;
+    /** Environnement courant (`development` | `production` | …). */
+    environment: string;
+    /** Répertoire ABSOLU des fichiers de log. */
+    logDir: string;
+    /** PID du process courant (nom de fichier par worker). */
+    pid: number;
+    /** Fournit le ring buffer courant à la demande (driver `memory`, lazy). */
+    getRingStack: () => IPduLike[];
+}
+/**
+ * Ce qu'une fabrique retourne : le driver de RELECTURE + (optionnel) le transport
+ * d'ÉCRITURE à brancher. `writeKey` déduplique le transport quand plusieurs drivers
+ * partagent la même destination d'écriture (ex. `file` ↔ `cluster-file` = même JSONL).
+ */
+export interface ILogDriverMount {
+    driver: ILogDriver;
+    transport?: ITransport;
+    writeKey?: string;
+}
+/** Fabrique d'un driver. Retourne `null` si la config est insuffisante (ex. URL absente). */
+export type ILogDriverFactory = (ctx: ILogDriverContext) => ILogDriverMount | null;
+/**
+ * Enregistre (ou remplace) la fabrique d'un driver par son nom.
+ *
+ * @param name - nom du driver (`"loki"`, `"opensearch"`, ou custom userland).
+ * @param factory - construit le driver + son transport à partir du contexte.
+ */
+export declare function registerLogDriverFactory(name: string, factory: ILogDriverFactory): void;
+/** Récupère la fabrique d'un driver, ou `undefined` si non enregistrée. */
+export declare function getLogDriverFactory(name: string): ILogDriverFactory | undefined;
+/** Liste les noms de drivers ayant une fabrique (introspection Studio / CLI). */
+export declare function listLogDriverFactories(): string[];
+/**
+ * Réinitialise le registre (tests uniquement — isole l'état module-level entre
+ * cas). Hors tests, le registre vit pour la durée du process. Les FABRIQUES ne sont
+ * PAS effacées (elles sont enregistrées 1× au boot, idempotent).
+ */
+export declare function _resetLogDriverRegistry(): void;

package/dist/types/syslog/drivers/opensearchShared.d.ts

@@ -0,0 +1,11 @@
+/** Index OpenSearch par défaut des logs Nodefony (write transport ↔ read driver). */
+export declare const DEFAULT_OPENSEARCH_INDEX = "nodefony-logs";
+/**
+ * Construit l'en-tête `Authorization: Basic …` si un utilisateur est fourni — sinon
+ * objet vide (dev = plugin sécurité désactivé, HTTP sans auth). Node-only (`Buffer`).
+ *
+ * @param username - utilisateur (absent → pas d'auth).
+ * @param password - mot de passe.
+ * @returns en-tête prêt à étaler, ou `{}`.
+ */
+export declare function basicAuthHeader(username?: string, password?: string): Record<string, string>;

package/dist/types/syslog/drivers/pduFlow.d.ts

@@ -0,0 +1,53 @@
+import type { IPduLike } from "./ILogDriver.js";
+import type { LogProtocol } from "./pduProtocol.js";
+/**
+ * **Étape logique du cycle de vie d'une requête / connexion** — identifiant
+ * STABLE (clé de filtre côté back ET clé de mapping libellé/couleur côté front).
+ *
+ * Les logs DEBUG du pipeline portent des noms d'events bruts (`onRequest`,
+ * `onRequestEnd`, `onSend`…) peu parlants, et dont l'ordre d'apparition n'est pas
+ * l'ordre intuitif (`onRequestEnd` = corps reçu, donc TÔT pour un GET malgré le
+ * mot « End »). Chaque event est ici mappé vers une étape nommée — la base d'un
+ * filtre fiable (≠ recherche texte, qui matchait par erreur les URL contenant le
+ * marqueur) et d'une lecture « je comprends où en est la requête ».
+ */
+export type FlowStepId = "request-in" | "body-received" | "route-matched" | "kernel-dispatch" | "response" | "request-end" | "finish" | "ws-open" | "ws-message" | "ws-close" | "session" | "session-saved";
+/**
+ * Métadonnée **structurelle** d'une étape (jamais de présentation : libellé FR et
+ * couleur vivent côté front, qui mappe l'`id`). `order` = rang logique dans le
+ * cycle de SON protocole ; `protocol` = où l'étape apparaît (`"both"` = session).
+ */
+export interface FlowStepMeta {
+    /** Rang logique dans le cycle (tri du sélecteur d'étapes). */
+    order: number;
+    /** Protocole d'appartenance — pilote le sélecteur adaptatif côté Studio. */
+    protocol: LogProtocol | "both";
+}
+/**
+ * Table des étapes — **source unique** de l'ordre et de l'appartenance protocole,
+ * partagée back (filtre) et front (sélecteur groupé HTTP / WebSocket / Commun).
+ */
+export declare const FLOW_STEPS: Record<FlowStepId, FlowStepMeta>;
+/**
+ * Entrée minimale pour classer une étape — seuls `msgid`, `payload` et `msg`
+ * comptent. Un `Pdu`, un {@link IPduLike} (msg requis) ET un record wire relu
+ * (`ILogRecord` / miroir front, `msg` optionnel) la satisfont structurellement
+ * → la classification est utilisable des deux côtés de la frontière isomorphe.
+ */
+export type FlowClassifiable = Pick<IPduLike, "msgid" | "payload"> & {
+    msg?: string;
+};
+/**
+ * Classe un Pdu en **étape de cycle de vie** (id stable) ou `null` si la ligne
+ * n'est pas un jalon (log applicatif libre, ex. `DB-DEMO`). PUR, isomorphe,
+ * 0 état — réutilisé par le filtre back ({@link filterPdus}) ET le rendu front
+ * (colonne « Étape » + sélecteur) → une SEULE logique, jamais de divergence.
+ *
+ * Priorité aux marqueurs de **contenu** (route, session, cookie, bilan), puis au
+ * **nom d'event** générique. `onRequest` est désambiguïsé par le msgid `KERNEL`
+ * (dispatch kernel) vs contexte (entrée de requête).
+ *
+ * @param pdu - enregistrement (Pdu ou {@link IPduLike}, relu d'un JSONL aussi).
+ * @returns l'`id` d'étape, ou `null` pour un log hors cycle.
+ */
+export declare function pduFlowStep(pdu: FlowClassifiable): FlowStepId | null;

package/dist/types/syslog/drivers/pduProtocol.d.ts

@@ -0,0 +1,20 @@
+import type { IPduLike } from "./ILogDriver.js";
+/** Protocole d'origine d'un enregistrement de log. */
+export type LogProtocol = "ws" | "http";
+/**
+ * Classe un Pdu par **protocole** d'origine — `"ws"` ou `"http"` — de façon PURE,
+ * isomorphe et 0-alloc (une seule comparaison de `msgid`).
+ *
+ * Critère FIABLE : tout log émis dans un contexte WebSocket porte le msgid
+ * `"WEBSOCKET CONTEXT"` (forcé par défaut dans `WebsocketContext.log()`). Tout le
+ * reste du pipeline (req/http2/router/firewall/kernel/applicatif) est classé HTTP.
+ * Une seule logique → front et back ne divergent plus (le front filtrait par texte,
+ * source de faux positifs).
+ *
+ * Seul `msgid` compte → accepte un `Pdu`, un {@link IPduLike} ou un record wire
+ * relu (`ILogRecord` / miroir front) indifféremment.
+ *
+ * @param pdu - tout objet portant un `msgid`.
+ * @returns `"ws"` si le log provient d'une socket WebSocket, sinon `"http"`.
+ */
+export declare function pduProtocol(pdu: Pick<IPduLike, "msgid">): LogProtocol;

package/dist/types/syslog/httpFetch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Petit contrat `fetch` minimal et INJECTABLE, partagé par les destinations HTTP du
+ * Log Backplane (drivers `loki`/`opensearch` côté query, transports côté write).
+ *
+ * Pourquoi un type local plutôt que le `fetch` global de `lib.dom` : le workspace core
+ * est isomorphe (Node + browser) et ne tire pas `lib.dom`. On déclare donc la surface
+ * STRICTE qu'on utilise (statut + `text`/`json`), ce qui rend aussi le code **testable
+ * sans réseau** : un test passe un `FetchLike` factice. 0 `any`, narrowing explicite.
+ */
+export interface FetchResponseLike {
+    /** `true` si statut 2xx. */
+    readonly ok: boolean;
+    /** Code HTTP (utile pour distinguer 404 « pas encore d'index » d'une vraie panne). */
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}
+/** Sous-ensemble des options `RequestInit` réellement utilisées. */
+export interface FetchInitLike {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+/** Signature compatible `globalThis.fetch` (surface réduite). */
+export type FetchLike = (url: string, init?: FetchInitLike) => Promise<FetchResponseLike>;
+/**
+ * Résout l'implémentation `fetch` à utiliser : celle passée explicitement (tests,
+ * proxy custom), sinon le `fetch` global (Node ≥ 18). Lève si aucune n'est dispo
+ * (jamais d'échec silencieux d'un driver prod mal configuré).
+ *
+ * @param custom - implémentation explicite (prioritaire).
+ * @returns un `FetchLike` garanti non nul.
+ * @throws si aucun `fetch` n'est disponible.
+ */
+export declare function resolveFetch(custom?: FetchLike): FetchLike;
+/**
+ * `fetch` borné par un timeout (via `AbortController`) — un push/lecture de logs ne
+ * doit JAMAIS bloquer indéfiniment sur une destination injoignable. `timeoutMs ≤ 0`
+ * = pas de timeout.
+ *
+ * @param fetchImpl - implémentation `FetchLike`.
+ * @param url - URL cible.
+ * @param init - options de requête.
+ * @param timeoutMs - délai max avant `abort`.
+ * @returns la réponse, ou rejette (timeout/réseau).
+ */
+export declare function fetchWithTimeout(fetchImpl: FetchLike, url: string, init: FetchInitLike, timeoutMs: number): Promise<FetchResponseLike>;

package/dist/types/syslog/logColor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Gate de couleur ANSI des logs — résolue **une seule fois au boot**
+ * ({@link Kernel.initializeLog}), pas par log.
+ *
+ * Problème résolu : plusieurs loggers (Kernel, Context, request-logger…) bakent
+ * des codes ANSI DANS le `payload`/`msgid` d'un `Pdu` (ex. `clc.cyan("URL")`).
+ * Ces Pdu voyagent jusqu'au `FileTransport` JSON → l'ANSI polluait le `.jsonl`
+ * queryable (et le pipe stdout → collecteur en prod). Stripper à l'écriture =
+ * un `.replace()` PAR log sur le hot path (refusé, coût). À la place, un flag
+ * global gate la couleur à la SOURCE.
+ *
+ * Critère (résolu au boot) : couleur ON si `stdout` est un **TTY** (un humain
+ * regarde un terminal) ; OFF si pipe/fichier/redirection (prod, collecteur,
+ * conteneur) → payloads bruts → JSONL et stdout propres.
+ *
+ * Perf : les slots ci-dessous sont MUTÉS une fois (`setLogColor`) — le hot path
+ * appelle directement `identity` (OFF) ou la fonction `cli-color` (ON), **sans
+ * test booléen par log**. Reproduire `clc.x.y` ici garde le chaînage hors du
+ * hot path (une fonction figée, pas une chaîne de getters par appel).
+ *
+ * Isomorphe : au navigateur, `cli-color` est remplacé par le shim identité
+ * (alias rollup) → ON ≡ OFF, jamais d'ANSI quoi qu'il arrive.
+ */
+type ColorFn = (s: string | number) => string;
+/** Combinaisons `cli-color` réellement utilisées par les loggers Nodefony. */
+declare const KEYS: readonly ["cyan", "magenta", "red", "green", "yellow", "blue", "blackBright", "yellowBold", "redBold", "cyanBold", "blueBrightBold", "cyanBgBlue", "cyanBgBlack"];
+type ColorKey = (typeof KEYS)[number];
+type ColorMap = Record<ColorKey, ColorFn>;
+/**
+ * Helper de couleur partagé — référence STABLE, propriétés mutées par
+ * {@link setLogColor}. Les call-sites font `logColor.cyan("URL")`.
+ */
+export declare const logColor: ColorMap;
+/**
+ * Active/désactive la couleur ANSI des logs — à appeler **une fois au boot**.
+ * Swap les fonctions des slots ; aucun coût par log ensuite.
+ *
+ * @param enabled - `true` = couleur (TTY interactif), `false` = brut (pipe/fichier).
+ */
+export declare function setLogColor(enabled: boolean): void;
+/** `true` si la couleur ANSI est active (gate boot-time). */
+export declare function isLogColorEnabled(): boolean;
+/**
+ * Applique les conventions d'environnement couleur PAR-DESSUS un signal `isTTY`
+ * **déjà résolu** — au boot on passe `Kernel.isTTY` (qui honore déjà `NF_NO_TTY`),
+ * sans re-lire `process.stdout`. Conventions :
+ *
+ * - **`NO_COLOR`** (no-color.org) : présent **et non vide** → couleur OFF, quelle
+ *   que soit sa valeur. Priorité absolue (refus explicite de l'utilisateur).
+ * - **`FORCE_COLOR`** : non vide et ≠ `"0"` → couleur ON (override pipe/non-TTY,
+ *   ex. CI qui veut des logs colorés capturés).
+ * - sinon → couleur = `isTTY`.
+ *
+ * Isomorphe : `env` lu via `globalThis.process` (navigateur : pas de `process`).
+ *
+ * @param isTTY - signal TTY déjà résolu (ex. `Kernel.isTTY`, NF_NO_TTY-aware).
+ */
+export declare function resolveColorEnabled(isTTY: boolean): boolean;
+export {};