@nodefony/framework 10.0.0-alpha.1

package/dist/types/nodefony/src/docsReader.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Frontmatter d'un fichier de doc module. Tous les champs sont optionnels —
+ * un `.md` sans frontmatter reste lisible (titre dérivé du premier `# H1`).
+ *
+ * On accepte les alias historiques (`last-updated` ⇄ `updated`, `topic` ⇄
+ * `title`) pour ne pas réécrire les docs `architecture/*` déjà frontmattées.
+ */
+export interface DocFrontmatter {
+    title?: string;
+    navTitle?: string;
+    module?: string;
+    since?: string;
+    updated?: string;
+    status?: string;
+    order?: number;
+    [key: string]: unknown;
+}
+/** Entrée du sommaire docs d'un module (sans le corps markdown). */
+export interface DocSummary {
+    /** Identifiant url-safe = nom de fichier sans extension. */
+    slug: string;
+    /** Titre humain (frontmatter `title`/`topic`, sinon premier H1, sinon slug). */
+    title: string;
+    /**
+     * Libellé COURT du menu (frontmatter `navTitle`), repli sur {@link title}. Un
+     * titre est écrit pour être lu en tête d'article ; une colonne de navigation
+     * n'a pas la même largeur, et une recherche doit trouver le mot AFFICHÉ.
+     */
+    navTitle: string;
+    /** `draft` | `stable` | `deprecated` | `null`. */
+    status: string | null;
+    since: string | null;
+    /** `updated`/`last-updated` du frontmatter. */
+    updated: string | null;
+    /** Date ISO du dernier commit git du fichier (dérive doc↔code). `null` hors git. */
+    gitUpdated: string | null;
+    /** Ordre d'affichage croissant (frontmatter `order`, défaut 100, `index`=0). */
+    order: number;
+}
+/** Doc complète : frontmatter + corps markdown (frontmatter retiré). */
+export interface DocContent {
+    slug: string;
+    frontmatter: DocFrontmatter;
+    markdown: string;
+    gitUpdated: string | null;
+}
+/** Symbole TS exporté d'un module, projeté depuis `.ai/symbols.json`. */
+export interface ModuleSymbol {
+    name: string;
+    kind: string;
+    file: string;
+    description: string | null;
+    extends: string | null;
+    implements: string[];
+    decorators: string[];
+}
+/**
+ * Parse un bloc frontmatter YAML minimaliste (clé: valeur scalaires).
+ *
+ * Volontairement sans dépendance (`gray-matter` etc.) : on ne gère que des
+ * scalaires `key: value` entre deux `---`. Les listes inline (`[a, b]`) sont
+ * conservées en string brute. Suffisant pour `title/module/status/since/
+ * updated/order`. Renvoie `{ data, body }` ; sans fence → `data` vide.
+ */
+export declare function parseFrontmatter(raw: string): {
+    data: DocFrontmatter;
+    body: string;
+};
+/**
+ * Sommaire des docs d'un module : lit les `*.md` de `<modulePath>/docs/`
+ * (un niveau, non récursif), parse le frontmatter, trie par `order` puis slug.
+ *
+ * @param modulePath - chemin disque du module (`Module.path`).
+ * @returns liste triée (vide si le dossier `docs/` est absent).
+ */
+export declare function listModuleDocs(modulePath: string, withGit?: boolean): Promise<DocSummary[]>;
+/**
+ * Comptage rapide des docs (`*.md`) d'un module — readdir seul, sans lire/parser
+ * ni `git`. Pour les KPI/overview (`docsCount`) où seul le nombre importe.
+ *
+ * @param modulePath - chemin disque du module (`Module.path`).
+ * @returns nombre de fichiers `.md` dans `<modulePath>/docs/` (0 si absent).
+ */
+export declare function countModuleDocs(modulePath: string): Promise<number>;
+/**
+ * Lit une doc module par slug : frontmatter + corps markdown brut.
+ *
+ * Le slug est borné (`SLUG_RE`) avant toute jointure de chemin → pas de path
+ * traversal vers l'extérieur de `<modulePath>/docs/`.
+ *
+ * @returns `null` si slug invalide ou fichier absent.
+ */
+export declare function readModuleDoc(modulePath: string, slug: string): Promise<DocContent | null>;
+/** Où un terme cherché apparaît, et la ligne qui le porte. */
+export interface DocSearchMatch {
+    /** Ligne (1-indexée) dans le CORPS markdown, frontmatter retiré. */
+    line: number;
+    /** La ligne, ramenée à une fenêtre lisible autour du terme. */
+    text: string;
+}
+/** Une doc qui répond à la recherche, avec ses extraits. */
+export interface DocSearchHit {
+    /** Clé du module qui porte la doc (`http`, `security`, `core`…). */
+    module: string;
+    slug: string;
+    title: string;
+    /** Extraits, dans l'ordre du document — bornés (cf `perDoc`). */
+    matches: DocSearchMatch[];
+    /** Occurrences TOTALES dans la doc ; les extraits, eux, sont bornés. */
+    occurrences: number;
+    /** Pertinence décroissante — un titre ou un slug porteur du terme pèse. */
+    score: number;
+}
+/** Une doc à balayer : la clé du module qui la porte, et son chemin disque. */
+export interface DocSearchTarget {
+    /** Clé d'affichage du module (`http`, `security`, `core`…). */
+    key: string;
+    /** Chemin disque du module (`Module.path`). */
+    path: string;
+}
+/** Ce que rend une recherche : les docs retenues, et ce qu'elle a balayé. */
+export interface DocSearchResult {
+    /** Termes effectivement cherchés, après normalisation. */
+    terms: string[];
+    /** Docs balayées — dit à l'agent si le corpus était bien là. */
+    scanned: number;
+    /** Docs qui portent TOUS les termes — avant la borne d'affichage. */
+    matched: number;
+    /** Les meilleures, bornées par `limit`. */
+    hits: DocSearchHit[];
+    /**
+     * Phrase d'annonce, présente UNIQUEMENT quand la borne a joué.
+     *
+     * ⚠️ `matched` seul ne suffit pas à s'en apercevoir : quand le nombre de
+     * documents trouvés égale la borne — le cas exact d'un corpus fourni — un
+     * lecteur voit « 20 » des deux côtés et conclut qu'il tient tout. Il faut
+     * donc le DIRE, et nommer le geste qui donne la suite. Absente quand tout
+     * est rendu : annoncer une coupe qui n'a pas eu lieu ferait chercher un
+     * reste inexistant.
+     */
+    note?: string;
+}
+/**
+ * Cherche un texte dans les docs colocalisées des modules donnés.
+ *
+ * ⭐ **Pourquoi cette fonction existe** : chez un utilisateur, la documentation
+ * des modules vit sous `node_modules/@nodefony/<mod>/docs/` — un dossier que `git`
+ * ignore, donc que `rg` et les outils de recherche des agents EXCLUENT par
+ * défaut. La doc est livrée et introuvable ; c'est cette porte qui la rend
+ * atteignable, sans quoi l'agent réécrit à la main ce qui est déjà écrit.
+ *
+ * Un document est retenu s'il porte **TOUS** les termes (et non l'un d'eux) :
+ * sur un corpus où « session » apparaît partout, un OU rendrait le corpus.
+ * La comparaison est faite sans casse ni diacritiques ({@link fold}).
+ *
+ * Aucun index n'est conservé : le corpus est relu à chaque appel. C'est une
+ * opération de développement, rare et explicite — un index en mémoire coûterait
+ * en permanence ce qu'il ferait gagner quelques fois, et se périmerait à la
+ * première doc éditée.
+ *
+ * @param targets - modules à balayer (clé + chemin disque)
+ * @param query - texte cherché ; les espaces séparent des termes cumulatifs
+ * @param options - bornes de rendu (`limit` docs, `perDoc` extraits)
+ * @returns les docs retenues, et ce que la recherche a réellement balayé
+ */
+export declare function searchModuleDocs(targets: readonly DocSearchTarget[], query: string, options?: {
+    limit?: number;
+    perDoc?: number;
+}): Promise<DocSearchResult>;
+/**
+ * Symboles TS exportés d'un module + descriptions TSDoc, lus depuis
+ * `.ai/symbols.json` (à la racine de l'application, cf {@link appRoot}).
+ *
+ * 100 % auto-généré (jamais de `.d.ts` manuel) → zéro divergence avec le code.
+ * Tab API maigre tant que la couverture TSDoc est faible : c'est volontaire,
+ * ça pousse à documenter.
+ *
+ * @param packageName - nom npm du module (`Module.getModuleName()`, ex
+ *   `"@nodefony/http"`) — clé `.module` dans le graphe symbolique.
+ * @returns symboles exportés triés par kind puis nom (vide si fichier absent).
+ */
+export declare function listModuleSymbols(packageName: string): Promise<ModuleSymbol[]>;
+/** Ce qu'on a trouvé d'un symbole dans les types LIVRÉS d'un module. */
+export interface SymbolDeclaration {
+    /**
+     * Fichier de TYPES qui porte la déclaration, relatif au module — jamais
+     * absolu (une réponse ne publie pas l'arborescence du serveur).
+     *
+     * Nommé `declarationFile` et non `file` : le graphe symbolique porte DÉJÀ un
+     * `file`, qui désigne la SOURCE dans le dépôt d'origine — un chemin qui
+     * n'existe pas chez celui qui a installé le paquet. Deux notions sous un même
+     * nom, et la fusion des deux réponses en écrasait une.
+     */
+    declarationFile: string;
+    /** Le bloc de déclaration, TSDoc compris. */
+    declaration: string;
+    /** Le bloc a-t-il été coupé ? Une troncature muette vaut un mensonge. */
+    truncated: boolean;
+}
+/**
+ * Extrait la déclaration d'un symbole des types LIVRÉS d'un module.
+ *
+ * ⭐ **Pourquoi cette fonction existe** : le graphe symbolique
+ * (`.ai/symbols.json`) dit qu'un symbole existe, ce qu'il étend et la première
+ * phrase de sa documentation — mais **pas sa signature**. À « quels arguments
+ * prend cette méthode ? », un agent n'a donc aucune réponse : les `.d.ts` qui
+ * la portent vivent sous `node_modules`, que git ignore et que les outils de
+ * recherche de fichiers excluent. Il devine, et il devine faux.
+ *
+ * Le nom demandé ne touche JAMAIS un chemin : il sert à filtrer du texte. Les
+ * fichiers balayés sont dérivés du module, pas de l'appelant — un paramètre qui
+ * entrerait dans un `join` serait une traversée de répertoire offerte.
+ *
+ * @param modulePath - chemin disque du module (`Module.path`)
+ * @param symbolName - nom exact du symbole (`AbstractCrudService`, `IKernel`)
+ * @returns la déclaration et son fichier, ou `null` si rien ne la porte
+ */
+export declare function readSymbolDeclaration(modulePath: string, symbolName: string): Promise<SymbolDeclaration | null>;
+/**
+ * Identité du package npm du core (`@nodefony/core`) tel qu'indexé dans
+ * `.ai/symbols.json` — le core est référencé sous ce nom logique, **pas** sous
+ * son nom npm réel (`nodefony`, héritage JS).
+ */
+export declare const CORE_PACKAGE = "@nodefony/core";
+/** Dépendance d'un module : range déclarée + version installée. */
+export interface DepInfo {
+    name: string;
+    kind: "nodefony" | "external";
+    range: string | null;
+    installed: string | null;
+}
+/** Statut "outdated" d'une dep externe (registry npm). */
+export interface OutdatedInfo {
+    name: string;
+    installed: string | null;
+    latest: string | null;
+    outdated: boolean;
+}
+/**
+ * Dépendances d'un module : depuis son `package.json` (dependencies +
+ * peerDependencies) avec la version RÉELLEMENT installée (lue dans
+ * `node_modules/<dep>/package.json`, local puis hoisté à la racine).
+ */
+export declare function readDependencies(modulePath: string): Promise<DepInfo[]>;
+/**
+ * Vérifie les MAJ des deps EXTERNES via le registry npm (`/<pkg>/latest`).
+ * Les deps Nodefony (workspaces locaux) sont ignorées. Réseau → on-demand.
+ */
+export declare function checkOutdated(deps: DepInfo[]): Promise<OutdatedInfo[]>;
+/** Résultat d'un lancement de tests (un fichier ou toute la suite). */
+export interface TestRunResult {
+    ok: boolean;
+    code: number | null;
+    passed: number;
+    failed: number;
+    durationMs: number;
+    output: string;
+    mode: string;
+}
+/**
+ * Liste les fichiers de test **unit** d'un module (lançables par `vitest run`).
+ * Si aucune suite unit, repli sur tous les fichiers. Chemins relatifs au module.
+ */
+export declare function listTestFiles(modulePath: string): Promise<string[]>;
+/** Un groupe de suites de tests (pour l'onglet Tests de Studio). */
+export interface TestGroup {
+    /** Catégorie (`unit`/`integration`/`e2e`/`load`/`websockets`/`routing`/`memory`/`autre`). */
+    category: string;
+    files: string[];
+    /** Lançable depuis Studio ? (unit seulement — les autres tapent un serveur/DB). */
+    runnable: boolean;
+}
+/**
+ * Groupe TOUS les fichiers de test d'un module par catégorie (lecture seule pour
+ * l'onglet Tests — les non-unit ne sont pas lançables depuis Studio : ils exigent
+ * un serveur live / une base, donc `runnable:false`). Donne une vue complète des
+ * suites (intégration/e2e/charge/mémoire) qui étaient invisibles auparavant.
+ */
+export declare function listTestGroups(modulePath: string): Promise<TestGroup[]>;
+/** Commande exacte que `runModuleTests` lance — pure, testable sans process. */
+export interface TestRunCommand {
+    cmd: string;
+    args: string[];
+    mode: string;
+}
+/**
+ * Compose la commande d'un run de tests de module, sans l'exécuter.
+ *
+ * - 1 fichier (module vitest) → `npx vitest run <file>` : le chemin est un
+ *   FILTRE positionnel de vitest. Il ne doit JAMAIS suivre un `--` : vitest
+ *   ignore tout ce qui vient après, et la suite ENTIÈRE tourne en silence
+ *   (vécu : 18 fichiers joués pour un seul demandé, verdict « vert »). La
+ *   défense anti-injection d'argument est la garde de l'appelant (pas de
+ *   préfixe `-`, pas de `..`, suffixe `.test.ts` — cf KernelAdminApi).
+ * - sinon (module vitest) → run-all, reporters coverage FORCÉS vers
+ *   `.coverage` : l'onglet Coverage de Studio apparaît quelle que soit la
+ *   config du module (la liste `reporter` dupliquée par module divergeait).
+ * - sinon (cœur : monocart, pas de `vitest.config.ts`) → `npm run coverage`.
+ *
+ * @param modulePath - racine du module (où vit `vitest.config.ts`)
+ * @param file - chemin relatif d'UN fichier de test, déjà validé par l'appelant
+ * @returns commande, arguments en tableau (spawn sans shell) et libellé du mode
+ */
+export declare function testRunCommand(modulePath: string, file?: string): TestRunCommand;
+/**
+ * Lance les tests d'un module et renvoie un résumé (pass/fail/durée + tail).
+ *
+ * - 1 fichier (module vitest) → `npx vitest run <file>` (rapide, pass/fail).
+ * - sinon → `npm run coverage` (suite complète + refresh coverage ; marche
+ *   pour vitest comme pour monocart/core).
+ *
+ * ⚠️ EXÉCUTE un process — appelé UNIQUEMENT derrière le garde dev-only de
+ * l'endpoint (cf KernelAdminApi). spawn sans shell + args en tableau (pas
+ * d'injection shell). `file` validé en amont (suffixe .test.ts, pas de `..`).
+ */
+export declare function runModuleTests(modulePath: string, file?: string): Promise<TestRunResult>;
+/**
+ * Chemin disque racine du package core (`nodefony`).
+ *
+ * Le core n'est **pas** un module chargé (`kernel.getModules()` n'a pas de clé
+ * `core`) : c'est le socle de tous les autres. On résout donc son emplacement
+ * pour lire ses docs colocalisées (`<core>/docs/*.md`).
+ *
+ * Dev self-hosted : `<racine de l'app>/src/nodefony`. Fallback prod :
+ * résolution du package npm `nodefony` (remontée jusqu'à son `package.json`).
+ */
+export declare function resolveCorePath(): string;
+/** Couverture d'un fichier (pourcentages, format json-summary istanbul/v8). */
+export interface CoverageFile {
+    file: string;
+    lines: number;
+    statements: number;
+    functions: number;
+    branches: number;
+}
+/** Rapport de couverture d'un module pour Studio (onglet Coverage). */
+export interface CoverageReport {
+    available: boolean;
+    generated?: string | null;
+    total?: {
+        lines: number;
+        statements: number;
+        functions: number;
+        branches: number;
+    };
+    files?: CoverageFile[];
+}
+/**
+ * Lit le dernier rapport de couverture d'un module dans `<module>/.coverage/`.
+ * Préfère `coverage-summary.json` (vitest, a les statements) ; sinon parse
+ * `lcov.info` (produit par monocart côté core ET par vitest). Studio AFFICHE ce
+ * rapport — il ne lance pas les tests. `available:false` si rien de généré.
+ */
+export declare function readCoverage(modulePath: string): Promise<CoverageReport>;
+/** Descripteur du pseudo-module `core` pour la carte/détail Studio. */
+export interface CoreInfo {
+    path: string;
+    name: string;
+    version: string | null;
+    dependencies: string[];
+}
+/**
+ * Métadonnées du core pour Studio (carte + onglet Vue d'ensemble).
+ *
+ * `name` est forcé à `@nodefony/core` (cohérent avec `.ai/symbols.json` et le
+ * frontmatter `module:`), même si son `package.json` se nomme `nodefony`.
+ * `version`/`dependencies` viennent de ce `package.json`.
+ */
+export declare function readCoreInfo(): Promise<CoreInfo>;

package/dist/types/nodefony/src/idempotency.d.ts

@@ -0,0 +1,96 @@
+import type { IIdempotencyStore, IdempotentResponse } from "nodefony";
+/** `true` si la méthode est une mutation éligible à l'idempotence. */
+export declare function isMutationMethod(method: string | null | undefined): boolean;
+/**
+ * Borne d'une clé d'idempotence (convention Stripe). Une clé est un identifiant
+ * court (UUID) ; au-delà, elle est traitée comme ABSENTE (anti-DoS du cache borné).
+ */
+export declare const IDEMPOTENCY_KEY_MAX = 255;
+/**
+ * Verdict **neutre** rendu par {@link evaluateIdempotency} — décrit QUOI faire
+ * sans rien savoir du transport :
+ *  - `execute` : pas de clé en mode souple, ou store/identité absents → exécuter
+ *    SANS mémoriser (jamais de partage cross-identité).
+ *  - `guarded` : clé fraîche réservée *in-flight* → exécuter PUIS `complete(key)`
+ *    (succès) ou `abort(key)` (échec), `key` = clé scopée à réutiliser telle quelle.
+ *  - `replay` : rejeu d'une mutation déjà complétée → renvoyer `response` SANS
+ *    exécuter.
+ *  - `reject` : court-circuit d'erreur (400 clé requise / 409 concurrent / 422
+ *    clé réutilisée avec un autre payload).
+ */
+export type IdempotencyVerdict = {
+    kind: "execute";
+} | {
+    kind: "guarded";
+    key: string;
+} | {
+    kind: "replay";
+    response: IdempotentResponse;
+} | {
+    kind: "reject";
+    status: 400 | 409 | 422;
+    message: string;
+    detail?: string;
+};
+/**
+ * Résout la clé d'idempotence d'une requête : posée dans l'ALS par le pont WS
+ * (`als.idempotencyKey`) ou lue de l'en-tête HTTP `Idempotency-Key` (clé
+ * minuscule côté Node, éventuellement répétée → premier élément). L'ALS prime sur
+ * l'en-tête. Une clé > {@link IDEMPOTENCY_KEY_MAX} est traitée comme **absente**
+ * (anti-DoS) plutôt que stockée. `undefined` si rien d'exploitable.
+ */
+export declare function resolveIdempotencyKey(alsKey: unknown, header: unknown): string | undefined;
+/**
+ * Identité stable pour **scoper** le cache d'idempotence (anti-IDOR : un
+ * utilisateur ne doit jamais rejouer la clé d'un autre). Dérivée de l'utilisateur
+ * (`username` / `identifier` / `id`, sans coupler le framework au contrat `IUser`),
+ * avec fallback sur l'`userId` de l'ALS. `null` = pas d'identité fiable → l'appelant
+ * n'utilise PAS le cache (jamais de partage cross-identité).
+ *
+ * ⚠️ Doit renvoyer la MÊME valeur quel que soit le transport pour un même compte
+ * (sinon une mutation tentée en WS puis rejouée en HTTP ne dédoublonnerait pas).
+ * D'où la dérivation de `request.user` (posé UNIFORMÉMENT dans l'ALS par les deux
+ * transports), et NON de `getUserId()` seul (le firewall HTTP ne le pose pas
+ * toujours — vécu S4).
+ */
+export declare function resolveIdentity(user: unknown): string | null;
+/**
+ * Empreinte SHA-256 du **payload** d'une requête (parties sérialisables : nom de
+ * route + params + corps). Comparée par le store à l'empreinte mémorisée pour une
+ * clé : si elle diffère, la clé est réutilisée pour une AUTRE requête → 422
+ * (draft §2.4). Hash → empreinte courte (anti-DoS mémoire) + comparaison O(1).
+ */
+export declare function computeFingerprint(parts: unknown): string;
+/**
+ * Cœur normatif : à partir de la clé client, de l'identité, du fingerprint et du
+ * transport, rend le {@link IdempotencyVerdict} à appliquer. La réservation
+ * (`store.begin`) est **atomique** (mono-thread JS côté mémoire, `SET … NX` côté
+ * Redis) ; le store peut être sync (mémoire) ou async (distribué) → `begin` est
+ * `await`é, d'où le retour `Promise<IdempotencyVerdict>`.
+ *
+ * Le `required` **effectif** = `required || isWs` : une mutation par socket exige
+ * TOUJOURS une clé (le WS reconnecte/rejoue → muter sans garde-fou exposerait au
+ * double-effet), tandis qu'en HTTP la clé n'est exigée qu'en mode strict
+ * (`@Idempotent()` par défaut). Cela unifie les deux call-sites :
+ *  - admin : `required=false` → exige la clé seulement en WS (comportement S4) ;
+ *  - `@Idempotent()` : `required=true` (strict) → exige la clé même en HTTP ;
+ *  - `@Idempotent({required:false})` : souple en HTTP, mais toujours strict en WS.
+ */
+export declare function evaluateIdempotency(opts: {
+    /**
+     * Store résolu, ou `null`/`undefined` (service absent → dégrade en exécution
+     * directe). Accepte les deux : `Controller.get()` renvoie `null`, un
+     * `container.get()` peut renvoyer `undefined`.
+     */
+    store: IIdempotencyStore | null | undefined;
+    /** Identité scope (cf {@link resolveIdentity}), ou `null` → pas de cache. */
+    identity: string | null;
+    /** Clé client résolue (cf {@link resolveIdempotencyKey}), ou `undefined`. */
+    clientKey: string | undefined;
+    /** Empreinte du payload (cf {@link computeFingerprint}). */
+    fingerprint: string;
+    /** La requête arrive-t-elle par socket ? (clé alors obligatoire.) */
+    isWs: boolean;
+    /** Exigence déclarée d'une clé (mode strict). */
+    required: boolean;
+}): Promise<IdempotencyVerdict>;

package/dist/types/nodefony/src/idempotencyGc.d.ts

@@ -0,0 +1,30 @@
+import { GcScheduler, type IIdempotencyStore } from "nodefony";
+/**
+ * Options d'armement du balayage périodique d'un store d'idempotence.
+ */
+export interface IIdempotencyGcOptions {
+    /** Intervalle entre deux purges (s). 0 = désarmé (cron / TTL natif). */
+    intervalS: number;
+    /** Étale le départ (anti thundering-herd cluster sur le store SQL partagé). */
+    jitter: boolean;
+    /** Reçoit l'erreur d'une passe de gc qui a levé. */
+    onError: (error: unknown) => void;
+    /** Journalise l'armement (observabilité boot / preuve e2e). */
+    log?: (message: string) => void;
+}
+/**
+ * Arme un {@link GcScheduler} qui purge périodiquement les entrées expirées d'un
+ * store d'idempotence — **UNIQUEMENT si le store expose `gc()`**.
+ *
+ * Pourquoi ce gating : un store à **expiration native** (`redis` → `SET … PX`) ou à
+ * **purge passive** (`memory` → éviction FIFO au cap) **n'expose pas** `gc()` ; les
+ * brancher sur un timer serait un no-op coûteux. Seul un store **SQL** (`drizzle`,
+ * `DELETE WHERE expiresAt <= now`) en a besoin — et son `gc()` était jusqu'ici
+ * **orphelin** (jamais appelé → fuite : les clés mortes s'accumulaient en base).
+ * Ce helper ferme ce trou, et l'isole de `onKernelBoot` pour être **testable sans
+ * booter un kernel**.
+ *
+ * @returns le scheduler armé (à `stop()` au shutdown), ou `null` si le store n'a
+ *   pas de `gc()` (rien à planifier).
+ */
+export declare function scheduleIdempotencyGc(store: IIdempotencyStore, opts: IIdempotencyGcOptions): GcScheduler | null;

package/dist/types/nodefony/src/idempotencyStoreRegistry.d.ts

@@ -0,0 +1,59 @@
+import type { Module, IIdempotencyStore } from "nodefony";
+import type { FrameworkConfig } from "../config/config.js";
+/**
+ * Registre de **fabriques de stores d'idempotence DISTRIBUÉS** — résout le nom
+ * configuré (`framework.idempotency.store`) vers une instance d'
+ * {@link IIdempotencyStore}, SANS coupler le framework à un backend en dur.
+ *
+ * Pourquoi : le store d'idempotence est pluggable par contrat (le contrat vit au
+ * CORE, `nodefony`). Le DÉFAUT mémoire (`MemoryIdempotencyStore`, per-pod) reste
+ * enregistré par `@services` du module framework (zéro config, toujours présent)
+ * → il n'est PAS dans ce registre. Ce registre ne porte QUE les **overrides
+ * distribués opt-in** (`redis`, `drizzle`) : un `if (name === "redis")` dans le
+ * framework trahirait la promesse pluggable, et le framework ne peut de toute
+ * façon pas importer `@nodefony/redis` (graphe inverse).
+ *
+ * Inversion de dépendance : les adapters (`@nodefony/redis`/`@nodefony/drizzle`)
+ * exportent une classe PURE (`import type` du contrat core) ; l'**application**
+ * câble la fabrique (`registerIdempotencyStore("redis", …)`), car activer un
+ * store distribué est une décision de **déploiement** (cluster multi-pod), pas
+ * une conséquence du chargement du module. Convention-frère : `tokenStoreRegistry`
+ * (`@nodefony/security`), `backplaneRegistry` (`@nodefony/realtime`).
+ */
+/**
+ * Contexte passé à une fabrique de store : de quoi se construire (résolutions
+ * coûteuses en lazy à l'intérieur de l'instance). Le module donne accès au
+ * container kernel (`ctx.module.kernel?.container?.get("redis")`).
+ */
+export interface IIdempotencyStoreFactoryContext {
+    /** Module framework (porte `kernel.container` pour résoudre `redis`, etc.). */
+    readonly module: Module;
+    /** Config framework validée + gelée. */
+    readonly config: FrameworkConfig;
+}
+/** Fabrique d'un store d'idempotence pour un nom donné. */
+export type IdempotencyStoreFactory = (ctx: IIdempotencyStoreFactoryContext) => IIdempotencyStore;
+/**
+ * Enregistre (ou remplace) la fabrique d'un store d'idempotence distribué.
+ * Appelée par l'application pour les adapters (`redis`/`drizzle`).
+ */
+export declare function registerIdempotencyStore(name: string, factory: IdempotencyStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getIdempotencyStoreFactory(name: string): IdempotencyStoreFactory | undefined;
+/**
+ * Noms de stores distribués enregistrés (résolution `auto` + validation boot).
+ * N'inclut PAS `"memory"` : dans `resolveAutoStore`, memory est le **fallback**
+ * (per-pod), jamais une préférence à sélectionner — l'y mettre fausserait le choix.
+ */
+export declare function listIdempotencyStores(): string[];
+/**
+ * Backends d'idempotence UTILISABLES, pour l'AFFICHAGE (écran Studio « Stores »).
+ * Inclut le builtin `"memory"` (toujours présent via `@services`, per-pod) EN TÊTE
+ * + les stores distribués enregistrés. Distinct de {@link listIdempotencyStores}
+ * (distribués seuls, pour la résolution) : côté Studio, le store résolu doit
+ * TOUJOURS figurer dans les backends dispo — sinon `resolved: "memory"` apparaît
+ * absent de la liste (incohérence). Convention-frère : les autres briques
+ * enregistrent leur builtin `memory` dans leur registre, donc `listXStores()`
+ * l'inclut déjà ; idempotency pose son memory hors registre → on le rajoute ici.
+ */
+export declare function listIdempotencyBackends(): string[];

package/dist/types/nodefony/src/scopeCatalog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Un groupe de scopes d'**une API** — le préfixe avant `:` (`orders`) et la liste
+ * (triée) de ses scopes déclarés (`orders:read`, `orders:write`). Un scope sans
+ * `:` (ex. `@RequireScope("orders")` = toute l'API) se groupe sous lui-même.
+ */
+export interface IApiScopeGroup {
+    /** Préfixe d'API (segment avant le `:`). */
+    readonly api: string;
+    /** Scopes `api:action` déclarés pour cette API, triés et dédupliqués. */
+    readonly scopes: readonly string[];
+}
+/**
+ * P6.8 — **Découverte au boot** : scanne TOUTES les routes montées (`Router.routes`)
+ * et agrège les scopes déclarés par `@RequireScope`, **regroupés par API** (préfixe
+ * avant `:`). C'est la source du formulaire « créer une clé API » de Studio : les
+ * scopes proposés DÉRIVENT du code (les routes), au lieu d'une liste plate de config
+ * qui se périme dès qu'on ajoute un `@RequireScope` sans penser à la config.
+ *
+ * **Cold path** : appelé à la demande (ouverture du formulaire), jamais sur le hot
+ * path requête. Lecture `Reflect` par route → coût proportionnel au nombre de routes,
+ * payé une fois par consultation.
+ *
+ * @returns les groupes triés par nom d'API (chaque groupe a ses scopes triés).
+ */
+export declare function collectDeclaredApiScopes(): IApiScopeGroup[];
+export default collectDeclaredApiScopes;

package/dist/types/nodefony/src/syslogFilters.d.ts

@@ -0,0 +1,52 @@
+import type { FlowStepId } from "nodefony";
+/**
+ * Ce que le journal sait TRIER — un seul axe, le temps.
+ *
+ * Le nom est public (celui de la ligne rendue, `ILogRecord.timeStamp`) ; l'axe
+ * technique du driver est l'`uid` du Pdu, un compteur monotone d'émission. Les
+ * deux disent la même chose, à ceci près que l'`uid` départage deux logs de la
+ * MÊME milliseconde — ce qu'un tri sur l'horodatage seul ne saurait pas faire.
+ */
+export declare const SYSLOG_SORTABLE: readonly ["timeStamp"];
+/**
+ * Le vocabulaire de filtre du journal — une **donnée**, publiée telle quelle
+ * dans le catalogue admin.
+ *
+ * Il remplace une lecture à la main qui acceptait tout et ne validait rien :
+ * `?severity=CRITICAL` (au lieu de `CRITIC`), `?protocol=grpc`, `?flow=nimporte`
+ * et même `?severty=ERROR` posaient un critère vide et rendaient le journal
+ * ENTIER sous un `200` — la réponse qu'un exploitant lit comme « aucune erreur ».
+ *
+ * `severity` et `flow` sont **répétables** (`?severity=ERROR&severity=CRITIC`) :
+ * c'est le OU dont le viewer a besoin, et la seule raison d'être de la nature
+ * `{ each }` du contrat.
+ */
+export declare const SYSLOG_FILTERS: {
+    /** Corrélation log↔requête (ALS) — match exact, la clé de la trace. */
+    readonly requestId: "string";
+    /** Nom de module/service — inclusion insensible à la casse côté driver. */
+    readonly module: "string";
+    /** Catégorie de message (msgid) — inclusion insensible à la casse. */
+    readonly msgid: "string";
+    /** Protocole d'origine ; absent = les deux. */
+    readonly protocol: readonly ["ws", "http"];
+    /**
+     * Sévérités RFC 5424 — l'allowlist EST {@link SEVERITY_NAMES} (source unique
+     * du cœur), jamais une liste recopiée qui finirait par diverger de l'enum.
+     */
+    readonly severity: {
+        readonly each: readonly ["EMERGENCY", "ALERT", "CRITIC", "ERROR", "WARNING", "NOTICE", "INFO", "DEBUG"];
+    };
+    /**
+     * Étapes du cycle de vie — l'allowlist est dérivée de la table `FLOW_STEPS`
+     * elle-même : ajouter une étape suffit à la rendre filtrable, et aucune
+     * seconde liste ne peut se périmer.
+     */
+    readonly flow: {
+        readonly each: FlowStepId[];
+    };
+    /** Borne basse d'horodatage (epoch ms, incluse). */
+    readonly from: "int";
+    /** Borne haute d'horodatage (epoch ms, incluse). */
+    readonly to: "int";
+};