nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/service/dev/devProjects.d.ts

@@ -0,0 +1,121 @@
+import path from "node:path";
+import type { DevProcessInfo, DevProcessWithCwd } from "./devProcess.js";
+/**
+ * Un projet Nodefony vivant sur ce poste — ce que `nodefony status` affiche et ce
+ * que `nodefony stop <projet>` accepte comme cible.
+ *
+ * Les deux commandes lisent la MÊME table : publier un nom qu'on ne pourrait pas
+ * viser, ou accepter un nom qui ne s'affiche nulle part, ferait de la table une
+ * décoration. C'est aussi pourquoi l'identité reste la RACINE et jamais le nom :
+ * deux clones d'un même dépôt portent le même `name` de `package.json`.
+ */
+export interface IProjectRuntime {
+    /** Étiquette lisible — `package.json#name`, ou le nom du dossier à défaut. */
+    readonly name: string;
+    /**
+     * D'où vient le nom, CONSTATÉ et non supposé : un `package.json` illisible
+     * (absent, JSON invalide, sans `name`) ne doit pas se lire comme un projet qui
+     * s'appellerait ainsi.
+     */
+    readonly nameSource: "package" | "dossier";
+    /** Racine du projet — l'IDENTITÉ, seule valeur sur laquelle on agit. */
+    readonly root: string;
+    /** `true` pour le projet du répertoire courant. */
+    readonly current: boolean;
+    /**
+     * Runtimes observés pour ce projet — la LISTE, pas un compte : `status` rend
+     * un tableau par projet (rôle, pid, uptime, mémoire), et un décompte seul
+     * obligerait à retourner chercher les process ailleurs.
+     */
+    readonly procs: readonly DevProcessInfo[];
+    /** Ports que ce projet déclare tenir (triés). */
+    readonly ports: readonly number[];
+}
+/**
+ * Lit le nom d'un projet dans son `package.json`.
+ *
+ * Repli sur le nom du DOSSIER, jamais sur une chaîne inventée : un projet sans
+ * `package.json` lisible reste désignable, et l'appelant sait par `nameSource`
+ * que le nom n'a pas été déclaré.
+ *
+ * @param root - racine du projet.
+ * @returns le nom déclaré, ou `null` si aucun n'est lisible.
+ */
+export declare function readProjectName(root: string): string | null;
+/** Dépendances injectables de {@link buildProjectTable} — aucun I/O par défaut imposé. */
+export interface IProjectTableDeps {
+    /** Nom déclaré d'un projet (défaut : lecture de son `package.json`). */
+    readonly readName?: (root: string) => string | null;
+    /** Ports qu'un projet déclare tenir (défaut : son fichier d'état runtime). */
+    readonly readPorts?: (root: string) => readonly number[];
+}
+/**
+ * Compose la table des projets Nodefony vivants — fonction PURE (toute lecture
+ * disque passe par {@link IProjectTableDeps}), donc éprouvable sans process ni
+ * fichier.
+ *
+ * Le projet courant figure toujours en tête et n'est OMIS que s'il ne tourne pas :
+ * une table qui listerait le voisin sans dire lequel est le nôtre obligerait à
+ * comparer des chemins à l'œil.
+ *
+ * @param cwd - racine du projet courant.
+ * @param mine - runtimes du projet courant.
+ * @param foreign - runtimes des autres projets (sortie `splitByProject().foreign`).
+ * @param myPorts - ports à l'écoute du projet courant.
+ * @param deps - lectures injectables (nom, ports).
+ * @returns la table, projet courant d'abord puis les autres par nom.
+ */
+export declare function buildProjectTable(cwd: string, mine: readonly DevProcessInfo[], foreign: readonly DevProcessWithCwd[], myPorts?: readonly number[], deps?: IProjectTableDeps): IProjectRuntime[];
+/**
+ * Met en forme la table des projets — lignes SANS couleur (l'appelant colore et
+ * indente), colonnes alignées sur le contenu réel.
+ *
+ * Le nom du projet courant porte un repère : c'est lui qu'on cherche d'abord, et
+ * comparer des racines à l'œil est précisément ce que cette table supprime. Un nom
+ * qui vient du dossier plutôt que du `package.json` est marqué `~` — l'utilisateur
+ * peut le viser tout autant, mais il sait que le projet ne s'est pas nommé.
+ *
+ * @param projects - table produite par {@link buildProjectTable}.
+ * @returns lignes prêtes à afficher (vide si aucun projet).
+ */
+export declare function formatProjectTable(projects: readonly IProjectRuntime[]): string[];
+/** Verdict de {@link resolveProjectTarget} — jamais un « le plus proche ». */
+export type ProjectResolution = {
+    readonly ok: true;
+    readonly project: IProjectRuntime;
+} | {
+    readonly ok: false;
+    readonly reason: "inconnu" | "ambigu";
+    /** Les projets qui expliquent le refus (tous, ou les homonymes). */
+    readonly candidates: readonly IProjectRuntime[];
+};
+/**
+ * Résout une cible `nodefony stop <projet>` — par NOM ou par CHEMIN.
+ *
+ * Le refus est la règle dès que la désignation n'est pas certaine : arrêter des
+ * process est irréversible, et deviner « le plus proche » ferait tomber le mauvais
+ * serveur sur une faute de frappe. Zéro correspondance et deux correspondances
+ * sont donc deux refus distincts, chacun avec de quoi corriger.
+ *
+ * Un argument contenant un séparateur, ou absolu, est traité comme un CHEMIN
+ * (résolu contre le répertoire courant) ; sinon il est comparé au nom déclaré ET
+ * au nom du dossier — un projet se désigne comme on le nomme, pas comme son
+ * `package.json` l'a nommé.
+ *
+ * ⚠️ La comparaison de chemins est exacte, casse comprise. Sur un système de
+ * fichiers insensible à la casse, une casse différente rend donc « inconnu »
+ * plutôt qu'une correspondance : un refus, jamais un mauvais arrêt.
+ *
+ * @param arg - ce que l'utilisateur a tapé.
+ * @param projects - table produite par {@link buildProjectTable}.
+ * @returns le projet visé, ou le motif du refus avec ses candidats.
+ */
+export declare function resolveProjectTarget(arg: string, projects: readonly IProjectRuntime[], 
+/**
+ * Grammaire de chemins — INJECTABLE pour que la règle s'éprouve sous une autre
+ * plateforme que celle qui joue le test (`path.win32` depuis un poste UNIX).
+ * Sans cela, le comportement Windows ne serait jamais qu'une intention : ici,
+ * `\` est un séparateur et `C:\…` est absolu, deux faits qu'un test macOS ne
+ * rencontre jamais par lui-même.
+ */
+grammar?: Pick<typeof path, "isAbsolute" | "sep" | "resolve" | "basename">): ProjectResolution;

package/dist/types/service/dev/devStatusReport.d.ts

@@ -0,0 +1,141 @@
+import { type DevObservationDeps, type DevProcessInfo, type DevProcessWithCwd, type DiscoverOptions, type PortState, type RuntimeMode } from "./devProcess.js";
+import { type IReadinessProbe } from "./bootVerdict.js";
+/** `true` si `name` est une commande système standalone (status/stop). */
+export declare function isStandaloneDevCommand(name: string): boolean;
+/**
+ * Exécute une commande système standalone par son nom — point d'entrée du fast-path
+ * `CliKernel.start` (avant tout boot). N'écrit jamais via le syslog (kernel non booté).
+ * `stop --all` = trans-projets explicite (défaut : scope au projet du cwd).
+ */
+export declare function runStandaloneDevCommand(name: string): Promise<number>;
+/**
+ * Rapport d'introspection des process dev — forme JSON, SOURCE DE VÉRITÉ unique
+ * partagée par le rendu ANSI CLI (`nodefony status`) et le data plane Studio
+ * (`GET /nodefony/kernel/api/processes`). CLI et Web affichent EXACTEMENT le même état.
+ */
+export interface DevStatusReport {
+    /**
+     * `false` si l'OBSERVATION EXTERNE n'a pas pu être menée — CONSTATÉ, jamais déduit
+     * de la plateforme : Windows, mais aussi `ps` absent (images Node minces, distroless,
+     * Alpine nu) ou syntaxe refusée (certaines BSD).
+     *
+     * Ne signifie plus « rapport vide » : le pidfile, le fichier d'état et la sonde TCP
+     * répondent partout, donc la topologie et les ports restent rapportés. Le drapeau dit
+     * seulement que les colonnes issues de `ps` (mémoire résidente, part CPU, instances
+     * Vite) manquent — ce qu'un avertissement du rapport énonce en toutes lettres.
+     */
+    readonly supported: boolean;
+    /** `true` si au moins un process runtime Nodefony tourne. */
+    readonly running: boolean;
+    /**
+     * Mode runtime dominant détecté (`dev`/`prod`/`cluster`), ou `null` si aucun process
+     * principal vivant. Pilote le libellé du rapport (dev vs production vs cluster).
+     */
+    readonly mode: RuntimeMode | null;
+    /** Process runtime observés (triés superviseur/master → serveur/worker → Vite). */
+    readonly processes: readonly DevProcessInfo[];
+    /** État des ports serveur sondés. */
+    readonly ports: readonly PortState[];
+    /** Décompte par rôle + ports à l'écoute. */
+    readonly summary: {
+        readonly supervisors: number;
+        readonly servers: number;
+        readonly vites: number;
+        /** Masters cluster (superviseurs prod, 0 HTTP). */
+        readonly masters: number;
+        /** Workers cluster (servent le HTTP). */
+        readonly workers: number;
+        readonly portsUp: number;
+        readonly portsTotal: number;
+    };
+    /** Incohérences détectées (pidfile périmé, orphelins, empilement) — fail-loud. */
+    readonly warnings: readonly string[];
+    /** Pidfile single-instance du superviseur — indice, chemin RELATIF (pas de fuite FS). */
+    readonly pidfile: {
+        readonly path: string;
+        readonly pid: number | null;
+        readonly alive: boolean;
+    };
+    /**
+     * `false` si le cwd n'est PAS un projet Nodefony (`isNodefonyProjectDir`) —
+     * le rendu remplace alors « lance nodefony dev » par un message explicite
+     * (un dev perdu hors projet croyait l'app simplement arrêtée, vécu).
+     */
+    readonly inProject: boolean;
+    /**
+     * Runtimes des AUTRES projets du poste — jamais comptés dans {@link processes},
+     * jamais tus. `status` s'attribuait ces process : une application arrêtée
+     * s'entendait dire « 4 process · 2/2 ports UP », diagnostic faux et rassurant à
+     * tort. Ils sont NOMMÉS avec leur dossier, exactement comme `nodefony stop` le
+     * fait — un dev qui cherche qui tient son port a besoin de la réponse.
+     */
+    readonly foreign: readonly DevProcessWithCwd[];
+    /**
+     * Ce que le runtime dit de sa DISPONIBILITÉ — `null` quand la sonde n'a rien
+     * pu conclure (aucun port en écoute, runtime muet), jamais un verdict deviné.
+     *
+     * Distinct des ports : un pod dont un composant retient la mise en service
+     * (schéma de base en retard, cache froid) écoute parfaitement et ne reçoit
+     * pourtant AUCUN trafic — l'orchestrateur l'a sorti du répartiteur de charge.
+     * Annoncer « 2/2 ports UP » sans le dire serait le diagnostic faux et
+     * rassurant que ce rapport s'interdit.
+     */
+    readonly readiness: IReadinessProbe | null;
+    /**
+     * Ports occupés par un projet identifié qui n'est PAS le nôtre (port → racine).
+     * Sépare « pas à moi » de « pas mort » : sans cette table, un port du voisin se
+     * lit comme un serveur à nous, ou comme un arrêt qui a échoué.
+     */
+    readonly portOwners: Readonly<Record<number, string>>;
+}
+/**
+ * Compose le {@link DevStatusReport} (décompte + incohérences) — fonction PURE :
+ * `pidAlive` est fourni par l'appelant (aucun syscall ici → testable sans `ps`/process).
+ * Centralise la synthèse + les warnings consommés AUSSI BIEN par le rendu ANSI CLI
+ * ({@link renderStatus}) que par le data plane Studio ({@link collectDevStatus}).
+ */
+export declare function buildDevStatus(cwd: string, pid: number | null, pidAlive: boolean, procs: readonly DevProcessInfo[], ports: readonly PortState[], inProject?: boolean, 
+/**
+ * `true` si `ps` a réellement répondu — verdict fourni par l'appelant. Paramètre et
+ * non lecture d'environnement : la fonction reste PURE, et un test peut éprouver
+ * depuis n'importe quel système ce que dit un rapport privé d'observation.
+ */
+discoverySupported?: boolean, 
+/**
+ * Runtimes des AUTRES projets, déjà écartés de `procs` par l'appelant — la
+ * partition coûte un `lsof` par pid hors Linux (mesuré à plus d'une seconde pour
+ * un seul process), elle se fait donc UNE fois, là où les syscalls ont lieu.
+ */
+foreign?: readonly DevProcessWithCwd[], 
+/**
+ * `true` si le rattachement au projet n'a pas pu être établi (répertoire courant
+ * des pids illisible) : `procs` est alors la liste GLOBALE du poste, et le rapport
+ * doit l'annoncer plutôt que laisser croire à un décompte scopé.
+ */
+projectScopeBlind?: boolean, 
+/**
+ * Verdict de disponibilité fourni par l'appelant (la fonction reste PURE, cf
+ * `discoverySupported`) — `null` = non sondée, ce qui ne se lit jamais comme
+ * « prêt ».
+ */
+readiness?: IReadinessProbe | null): DevStatusReport;
+/**
+ * Collecte l'état dev (ps + sonde ports + pidfile) → {@link DevStatusReport} JSON.
+ * Best-effort : Windows (pas de `ps` POSIX) → `supported:false`. `opts.includeSelf`
+ * (data plane = le serveur DOIT se compter). AUCUN boot kernel requis (observation
+ * externe pure) → utilisable depuis le fast-path standalone ET depuis le data plane.
+ */
+export declare function collectDevStatus(cwd: string, opts?: DiscoverOptions & DevObservationDeps): Promise<DevStatusReport>;
+/** Collecte (ps + ports + pidfile) puis écrit le rapport status sur stdout. */
+export declare function runStatusReport(cwd: string, deps?: DevObservationDeps): Promise<void>;
+/**
+ * Tableau ANSI des process dev (RÔLE/PID/PPID/UPTIME/RSS/%CPU + `↳ bundles`) —
+ * LE gabarit partagé `nodefony status` ⇄ bilan de fin de boot (même topologie,
+ * même sérieux). `indent` décale toute la grille (le bilan l'aligne sous ses
+ * lignes `➜`).
+ *
+ * Largeur de la colonne RÔLE = plus long label réel (labels courts : supervisor /
+ * server / vite) → alignement stable. Le détail des bundles Vite passe sur une 2ᵉ
+ * ligne indentée (hors colonne) au lieu de faire déborder la grille.
+ */
+export declare function renderProcessTable(lines: string[], procs: readonly DevProcessInfo[], indent?: string): void;

package/dist/types/service/dev/devStop.d.ts

@@ -0,0 +1,57 @@
+import { type DevObservationDeps, type DevProcessInfo } from "./devProcess.js";
+/**
+ * Filtre de `--all` : sans projet de référence, la SEULE preuve restante serait le
+ * titre de process. C'est peu pour un `kill -9` trans-projets — un homonyme
+ * suffirait. On exige donc une SECONDE preuve, indépendante du nom : le process
+ * travaille bien dans un projet Nodefony (`package.json` qui dépend de `nodefony`,
+ * ou `node_modules/nodefony`), lui-même ou un ancêtre (un Vite tourne dans le
+ * SOUS-dossier de son bundle). Un cwd illisible — process d'un autre utilisateur,
+ * `lsof` muet — ne prouve rien : on n'y touche pas.
+ *
+ * PURE (dépendances injectables) : `--all` tue sans garde-fou de projet, il ne
+ * doit pas rester une branche non éprouvée.
+ *
+ * @param procs - runtimes découverts par `ps`.
+ * @param getCwd - lecture du cwd d'un pid (défaut : `processCwd`).
+ * @param isProject - test « ce dossier est un projet Nodefony » (défaut : `isNodefonyProjectDir`).
+ * @returns `kept` = appartenance PROUVÉE (tuables) ; `rejected` = épargnés + le motif.
+ */
+export declare function scopeAllToNodefonyProjects(procs: readonly DevProcessInfo[], getCwd?: (pid: number) => string | null, isProject?: (dir: string) => boolean): {
+    kept: DevProcessInfo[];
+    rejected: {
+        proc: DevProcessInfo;
+        why: string;
+    }[];
+};
+/**
+ * Racines des projets auxquels appartiennent `procs` — dédupliquées.
+ *
+ * Sert à `--all` pour savoir QUELS ports vérifier après un arrêt trans-projets :
+ * un port qu'on ne sonde pas ne peut ni confirmer ni infirmer l'arrêt, et le
+ * rapport concluait « ✓ arrêté proprement » sans avoir regardé les trois quarts
+ * des ports qu'il venait de libérer.
+ *
+ * Fonction PURE (lecture du cwd injectable). Les rôles Vite sont ignorés : ils
+ * travaillent parfois dans un sous-dossier, et leur parent porte déjà la racine.
+ *
+ * @param procs - runtimes sur le point d'être arrêtés.
+ * @param getCwd - lecture du répertoire courant d'un pid.
+ * @returns les racines distinctes, sans celles qu'on n'a pas pu lire.
+ */
+export declare function hostProjects(procs: readonly DevProcessInfo[], getCwd?: (pid: number) => string | null): string[];
+/**
+ * Découvre, tue (SIGTERM→SIGKILL) et nettoie ; écrit un rapport sur stdout.
+ *
+ * `opts.target` désigne un AUTRE projet par son nom ou son chemin — strictement
+ * l'équivalent de `cd <projet> && nodefony stop`, obtenu en substituant la racine
+ * visée au répertoire courant : une seule mécanique d'arrêt, jamais deux.
+ *
+ * @returns le code de sortie — `0` si l'arrêt a eu lieu (ou n'avait rien à faire),
+ *   `1` si la cible n'a pas pu être DÉSIGNÉE sans ambiguïté. Un `stop` qui n'a rien
+ *   arrêté parce qu'il n'a pas compris la cible ne doit pas se lire comme un succès
+ *   dans un script.
+ */
+export declare function runStopReport(cwd: string, opts?: {
+    all?: boolean;
+    target?: string;
+} & DevObservationDeps): Promise<number>;

package/dist/types/service/fetchService.d.ts

@@ -0,0 +1,29 @@
+import type Module from "../kernel/Module.js";
+import type Kernel from "../kernel/Kernel.js";
+import Service from "../Service.js";
+/**
+ * Service `Fetch` — façade DI au-dessus de l'API `fetch` **native** de Node.js.
+ *
+ * Depuis Node 21, `fetch`, `Response`, `Request` et `Headers` sont des globaux
+ * stables (implémentation undici intégrée). Ce service les expose via le
+ * conteneur d'injection (`@inject("Fetch")`) — la dépendance `node-fetch` n'est
+ * donc plus nécessaire (un appel réseau de moins à bundler, perfs undici natives).
+ *
+ * `fetch` est lié à `globalThis` pour éviter le `TypeError: Illegal invocation`
+ * quand il est appelé via `this.fetch(...)` (undici exige `globalThis` comme `this`).
+ *
+ * Posé au container par l'{@link Injector} à la construction du kernel : une
+ * instance par kernel, partagée par tous ses consommateurs.
+ */
+declare class Fetch extends Service {
+    fetch: typeof globalThis.fetch;
+    Response: typeof globalThis.Response;
+    Request: typeof globalThis.Request;
+    Headers: typeof globalThis.Headers;
+    /**
+     * @param owner - porteur du service : le kernel (service core) ou un module.
+     *   Seul son `container` est utilisé — c'est ce dont un `Service` a besoin pour exister.
+     */
+    constructor(owner: Module | Kernel);
+}
+export default Fetch;

package/dist/types/service/gitService.d.ts

@@ -0,0 +1,24 @@
+/** Identité git du dépôt courant. Champs `""` si indéterminés (hors dépôt). */
+export interface GitInfo {
+    /** Branche courante, ou sha court si HEAD détaché. */
+    branch: string;
+    /** Commit HEAD court (7 caractères). */
+    commit: string;
+}
+/**
+ * Introspection git du dépôt — **sans spawn `git` ni dépendance** (lecture directe
+ * de `.git/`). Résultat caché pour la vie du process. Best-effort : champs `""`
+ * hors d'un dépôt (ex. container sans `.git`). Consommé par le data plane kernel
+ * (`/nodefony/kernel/api/info` → `git`) et la barre de debug (bloc `app`).
+ */
+export default class GitService {
+    /**
+     * Lit branche + commit court (une fois, puis cache process).
+     *
+     * @param cwd - racine où chercher `.git` (défaut `process.cwd()`)
+     * @returns `{ branch, commit }` — champs `""` si indéterminés
+     */
+    static read(cwd?: string): GitInfo;
+    /** Branche seule (raccourci). */
+    static branch(cwd?: string): string;
+}

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

@@ -0,0 +1,134 @@
+export type Pci = unknown;
+export type ModuleName = string;
+export type Message = string;
+export type Msgid = string;
+export type PduDate = string | number | Date;
+export type Status = "NOTDEFINED" | "INVALID" | "ACCEPTED" | "DROPPED";
+type SeverityKeys = keyof typeof SysLogSeverity;
+type SeverityValues = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | -1;
+export type Severity = SeverityKeys | SeverityValues;
+declare enum SysLogSeverity {
+    EMERGENCY = 0,
+    ALERT = 1,
+    CRITIC = 2,
+    ERROR = 3,
+    WARNING = 4,
+    NOTICE = 5,
+    INFO = 6,
+    DEBUG = 7
+}
+/**
+ * Les noms de sévérité RFC 5424, **dans l'ordre de l'enum** (l'index EST la
+ * valeur : `SEVERITY_NAMES[3] === "ERROR"`). Les huit niveaux de la RFC, et
+ * rien d'autre : une animation de terminal n'est pas un niveau de journal.
+ *
+ * Source **unique** du vocabulaire, côté serveur comme côté navigateur (le
+ * bundle client la réexporte). Elle existe parce qu'elle était écrite trois
+ * fois — deux copies dans la console d'administration, dans deux ORDRES
+ * différents, et aucune côté data plane, si bien qu'un `?severity=CRITICAL`
+ * n'était refusé nulle part : il rendait le journal entier.
+ *
+ * Pour un sélecteur qui va du moins au plus grave, lire `[...SEVERITY_NAMES]
+ * .reverse()` — l'ordre d'affichage se dérive, il ne se redéclare pas.
+ */
+export declare const SEVERITY_NAMES: readonly ["EMERGENCY", "ALERT", "CRITIC", "ERROR", "WARNING", "NOTICE", "INFO", "DEBUG"];
+/** Un nom de sévérité RFC 5424. */
+export type SeverityName = (typeof SEVERITY_NAMES)[number];
+/**
+ * `moduleName` porté par une entrée de journal venue d'un NAVIGATEUR.
+ *
+ * Valeur de confiance : le pod l'impose lui-même en recevant un lot sur le canal
+ * montant, sans jamais reprendre ce que la page prétend être. Une ligne qui la porte
+ * a donc traversé ce canal, et rien d'autre ne peut la produire.
+ *
+ * Elle vit ICI, dans le cœur isomorphe, pour la même raison que
+ * {@link SEVERITY_NAMES} : le serveur l'écrit, le navigateur la lit pour distinguer
+ * ces lignes à l'écran. Une copie côté console d'administration dériverait le jour
+ * où le mot change — et un écran qui ne reconnaît plus l'origine ne se plaint pas,
+ * il affiche simplement une ligne de plus au milieu des autres.
+ */
+export declare const BROWSER_ORIGIN = "browser";
+declare class Pdu {
+    payload: Pci;
+    uid: number;
+    severity: number;
+    timeStamp: number;
+    severityName: keyof typeof SysLogSeverity;
+    typePayload: string | null;
+    moduleName: ModuleName;
+    msgid: Msgid;
+    msg: Message;
+    status: Status;
+    /** PID du process émetteur (= procid RFC 5424). Constant, capturé au chargement du module. */
+    pid: number;
+    /**
+     * Identifiant de la requête en cours (corrélation log↔requête).
+     *
+     * Présent UNIQUEMENT si le Pdu est créé dans une bulle `RequestContext` active
+     * (ALS Node) ET que {@link Pdu.requestIdProvider} a été branché côté Node — voir
+     * `src/index.ts` (barrel Node uniquement, isomorphisme préservé : le bundle
+     * client/browser ne branche pas, le provider reste `null` → 0 alloc, 0 lecture).
+     *
+     * Combiné à `pid` (procid RFC 5424), permet la corrélation **complète** :
+     * `pid` = quel worker, `requestId` = quelle requête. Voyage dans ring buffer +
+     * `nodefony:syslog` + transports JSON (champ public sérialisé naturellement).
+     */
+    requestId?: string;
+    /**
+     * Provider injectable du `requestId` courant (ALS). Branché par le barrel
+     * Node (`src/index.ts`) sur `RequestContext.getRequestId`. Reste `null` côté
+     * browser/debugbar (le bundle client n'importe pas `node:async_hooks`) et
+     * pendant les phases boot pré-Kernel (cohérent : pas de requête en cours).
+     *
+     * Coût : 1 test de référence par Pdu (~5 ns) quand `null` ; ~50-100 ns quand
+     * branché (lecture ALS + accès propriété). Pas d'alloc supplémentaire si
+     * `requestId` est `undefined` (le champ reste non-défini sur l'instance).
+     */
+    static requestIdProvider: (() => string | undefined) | null;
+    /**
+     * Construit un Pdu prêt à être publié dans le pipeline Syslog.
+     *
+     * @param pci - payload (string, Error, objet — typé `unknown`, narrower côté lecteur).
+     * @param severity - niveau RFC 5424 (string `"INFO"` ou numérique `6`). Défaut `"INFO"`.
+     * @param moduleName - nom du module/service qui a produit le log. Défaut `"nodefony"`.
+     * @param msgid - catégorie de message (`"AUTH"`, `"ROUTER"`, etc.). Défaut `""`.
+     * @param msg - détail libre optionnel. Défaut `""`.
+     * @param date - timestamp (number, Date, ou string parsable). Défaut `Date.now()`.
+     * @throws Si `severity` n'est pas une valeur valide de {@link SysLogSeverity}.
+     */
+    constructor(pci: Pci, severity?: Severity, moduleName?: ModuleName, msgid?: Msgid, msg?: Message, date?: PduDate);
+    /**
+     * Map bidirectionnelle des sévérités RFC 5424 (`{ INFO: 6, 6: "INFO", ... }`).
+     *
+     * @returns dictionnaire `{ severityName: severityValue }` plus enum reverse.
+     */
+    static sysLogSeverity(): Record<Severity, Severity>;
+    /**
+     * Convertit une sévérité numérique ou string en son nom canonique.
+     *
+     * @param severity - valeur numérique (`6`) ou string (`"INFO"` ou `"6"`).
+     * @returns nom canonique (`"INFO"`) ou `undefined` si invalide.
+     */
+    static severityToString(severity: number | string): string | undefined;
+    /**
+     * Retourne le timestamp formaté `HH:MM:SS GMT±HHMM (TZ Name)`.
+     *
+     * @returns time string lisible par humain.
+     */
+    getDate(): string;
+    /**
+     * Sérialise le Pdu en string mono-ligne pour transport console/file.
+     *
+     * @returns ligne formatée `TimeStamp:... Log:... ModuleName:... SeverityName:... MessageID:... UID:... Message:...`.
+     */
+    toString(): string;
+    /**
+     * Réhydrate un Pdu existant à partir d'une string JSON — mute uniquement les
+     * clés déjà présentes sur l'instance (filtre `key in this`).
+     *
+     * @param str - JSON sérialisé d'un Pdu.
+     * @returns objet parsé (ou `null` si JSON vide). Mute l'instance courante au passage.
+     */
+    parseJson(str: string): Record<string, unknown> | null;
+}
+export default Pdu;