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

package/dist/types/nodefony/mcp/server.d.ts

@@ -0,0 +1,156 @@
+import { type IJsonRpcMessage, type IMcpHttpReply, type JsonRpcId } from "./protocol.js";
+import { type IJsonRpcNotification } from "nodefony";
+import { type IMcpTool, type IMcpCaller } from "./tools.js";
+/**
+ * Cœur du serveur MCP : un message JSON-RPC entre, une réponse HTTP sort.
+ *
+ * **Fonction pure** — elle ne touche ni au socket, ni au conteneur, ni à
+ * l'horloge. C'est ce qui permet d'éprouver le protocole entier (statuts
+ * compris) sans démarrer de serveur, et c'est aussi ce qui rend le transport
+ * interchangeable : le jour où un transport `stdio` serait nécessaire pour
+ * répondre application éteinte, il appellerait cette même fonction.
+ *
+ * ## Ce que la révision 2026-07-28 change, et pourquoi c'est ce qui rend cette
+ * porte viable
+ *
+ * Les sessions de niveau protocole ont disparu. Rien n'est retenu entre deux
+ * appels : chaque `POST` porte tout ce qu'il faut pour être servi. Un
+ * redémarrage du serveur de développement — celui que le superviseur déclenche
+ * à chaque fichier sauvegardé — ne casse donc aucun état, et la réponse
+ * suivante vient du code qui vient d'être rechargé. Aucun cache à invalider,
+ * jamais : la fraîcheur est une propriété du protocole, pas une discipline.
+ */
+/** Ce que ce serveur sait faire, annoncé à l'initialisation. */
+export interface IServerInfo {
+    name: string;
+    version: string;
+}
+/** Tout ce dont le traitement d'un message a besoin. */
+export interface IMcpServerContext {
+    /**
+     * Outils SERVIS, déjà ramassés et filtrés (`collectMcpTools`).
+     *
+     * ⭐ Ce sont des outils exécutables, pas des noms : c'est ce qui rend le
+     * protocole indépendant du catalogue. Tant que cette fonction recevait une
+     * allowlist de clés, elle devait connaître le catalogue pour la résoudre —
+     * et un serveur MCP d'un autre paquet aurait dû redéclarer le sien.
+     */
+    tools: readonly IMcpTool[];
+    /** Identité annoncée au client. */
+    serverInfo: IServerInfo;
+    /**
+     * Appelant établi par la porte, transmis aux handlers.
+     *
+     * Le protocole ne s'en sert PAS pour décider : la décision a déjà été prise à
+     * la collecte, et `tools` ne contient que ce qui lui revient. Il le transporte
+     * pour qu'un outil puisse borner ce qu'il REND à son sujet.
+     */
+    caller?: IMcpCaller;
+    /**
+     * Combien d'outils la collecte a RETENUS pour cet appelant.
+     *
+     * Sert uniquement à l'annonce de `server/discover` — un nombre, jamais un
+     * nom. Absent ou `0` = rien à signaler.
+     */
+    withheldCount?: number;
+    /**
+     * Cette porte sait-elle RECEVOIR une autorisation (porte HTTP protégée, qui
+     * publie son document RFC 9728 et défie par `401`) ? Absent ou `false` : les
+     * outils retenus ne s'ouvrent pas ici, et l'annonce ne renvoie à aucun
+     * document ni défi qui n'existent pas.
+     */
+    authorizable?: boolean;
+    /**
+     * Ce que la porte sait faire PENDANT un appel — absent, l'appel est servi
+     * comme une lecture courte : jamais annulé, sans progression.
+     */
+    transport?: IMcpTransport;
+    /**
+     * Les appels en cours de CET appelant, que `notifications/cancelled` abat —
+     * absent, seule la fermeture du flux annule un appel.
+     */
+    cancellation?: IMcpCancellation;
+    /**
+     * Révisions du protocole que CETTE porte accepte, la préférée en tête.
+     * Absent = toutes celles que le moteur sait servir ({@link MCP_SUPPORTED_VERSIONS}).
+     */
+    versions?: readonly string[];
+    /**
+     * Ce que l'agent lit pour savoir QUAND se servir de cette porte — la phrase
+     * d'ouverture des `instructions`. Absent = une phrase neutre.
+     */
+    instructions?: string;
+    /**
+     * Indices de cache des listes (`ttlMs`, `cacheScope`), servis aux clients de
+     * l'ère moderne seulement. Absent = `0` / `"private"`.
+     */
+    cache?: IMcpCacheHints;
+}
+/** Indices de cache d'un résultat MCP (spec `server/utilities/caching`). */
+export interface IMcpCacheHints {
+    /** Durée de fraîcheur en millisecondes, `>= 0` (MUST). */
+    ttlMs: number;
+    /** `private` dès que le résultat dépend de l'appelant. */
+    cacheScope: "public" | "private";
+}
+/**
+ * Le transport d'UNE requête, vu du protocole.
+ *
+ * Le protocole décide QUOI émettre (une progression liée à la requête) ; la
+ * porte décide COMMENT — et c'est à elle d'ouvrir son flux au premier envoi.
+ * Une porte qui ne sait pas tenir de flux ne fournit pas `notify` : la
+ * progression devient muette, la réponse reste du JSON.
+ */
+export interface IMcpTransport {
+    /** Abattu quand le client abandonne la requête. */
+    signal?: AbortSignal;
+    /** Émet une notification liée à la requête, AVANT la réponse finale. */
+    notify?: (notification: IJsonRpcNotification) => void;
+}
+/**
+ * Les appels en cours d'UN appelant, annulables par `notifications/cancelled`.
+ *
+ * Deux voies d'annulation coexistent. La révision `2026-07-28` fait de la
+ * fermeture du flux LA seule annulation en Streamable HTTP ; la révision
+ * `2025-11-25`, celle du SDK officiel, envoie à la place une notification dans
+ * un AUTRE `POST`, sans rien fermer. Cette table sert la seconde voie.
+ *
+ * La porte la fournit déjà LIÉE à l'appelant qu'elle a reconnu : l'identifiant
+ * JSON-RPC est choisi par le CLIENT, deux appelants peuvent donc envoyer le
+ * même, et une annulation ne doit jamais atteindre l'appel d'un autre.
+ */
+export interface IMcpCancellation {
+    /**
+     * Inscrit l'appel `id` le temps de son exécution.
+     *
+     * @param id - identifiant JSON-RPC de l'appel
+     * @returns le signal que la notification abat, et `close()`, à appeler
+     *   quand l'appel est fini (il le désinscrit)
+     */
+    open(id: JsonRpcId): {
+        readonly signal: AbortSignal;
+        close(): void;
+    };
+    /**
+     * Abat l'appel `id` s'il est en cours ; inconnu ou déjà fini, ne fait rien
+     * (la spec permet d'ignorer une telle annulation).
+     *
+     * @param id - identifiant JSON-RPC de l'appel visé
+     * @param reason - motif donné par le client, à journaliser seulement
+     */
+    cancel(id: JsonRpcId, reason: string | undefined): void;
+}
+/** En-têtes HTTP dont le protocole se sert. */
+export interface IMcpHeaders {
+    /** `MCP-Protocol-Version`, absent chez un client de l'ère legacy. */
+    protocolVersion?: string | undefined;
+}
+/**
+ * Traite UN message JSON-RPC.
+ *
+ * @param message - corps du `POST`, déjà parsé
+ * @param context - outils autorisés et briques qui répondent
+ * @param headers - en-têtes du transport (`MCP-Protocol-Version`)
+ * @returns statut HTTP et corps à écrire (corps `null` = `202` sans contenu)
+ */
+export declare function handleMcpMessage(message: IJsonRpcMessage | null, context: IMcpServerContext, headers?: IMcpHeaders): Promise<IMcpHttpReply>;

package/dist/types/nodefony/mcp/sessionTicket.d.ts

@@ -0,0 +1,60 @@
+/** Durée de vie d'un ticket : le temps d'une requête de connexion en boucle locale. */
+export declare const SESSION_TICKET_TTL_MS = 10000;
+/**
+ * Tickets en attente au plus. Un outil en émet UN et le rachète aussitôt :
+ * en atteindre huit signale un usage anormal, refusé plutôt qu'accumulé.
+ */
+export declare const SESSION_TICKET_MAX_PENDING = 8;
+/** Longueur d'un ticket : 32 octets d'aléa en base64url, sans remplissage. */
+export declare const SESSION_TICKET_LENGTH = 43;
+/** En-tête qui porte le ticket vers la route de connexion par ticket. */
+export declare const SESSION_TICKET_HEADER = "x-nodefony-session-ticket";
+/** Réglages du magasin — injectés par les tests, défauts en production. */
+export interface ISessionTicketStoreOptions {
+    /** Horloge, en millisecondes. */
+    readonly now?: () => number;
+    /** Empreinte d'un ticket (instrumentée pour compter les hachages). */
+    readonly fingerprint?: (ticket: string) => string;
+}
+/** Empreinte sous laquelle un ticket est rangé : le ticket brut n'est jamais gardé. */
+export declare function fingerprintSessionTicket(ticket: string): string;
+/**
+ * Tickets à usage unique qui autorisent l'ouverture d'UNE session pour une
+ * identité donnée — celle au nom de laquelle un outil MCP tire de vraies
+ * requêtes HTTP vers l'application.
+ *
+ * Le ticket ne quitte jamais le process : l'outil qui l'émet est celui qui le
+ * présente, en boucle locale, à la route de connexion de sa porte
+ * (`defineTicketSessionGate`). L'identité est fixée à l'émission — la
+ * requête de rachat n'en porte aucune, donc ne peut pas en choisir une autre.
+ *
+ * Aucune minuterie : les tickets expirés sont purgés à chaque émission et à
+ * chaque rachat, sur au plus {@link SESSION_TICKET_MAX_PENDING} entrées.
+ */
+export declare class SessionTicketStore {
+    #private;
+    /**
+     * @param options - horloge et empreinte, injectées par les tests.
+     */
+    constructor(options?: ISessionTicketStoreOptions);
+    /** Nombre de tickets émis, ni rachetés ni expirés. */
+    get pending(): number;
+    /**
+     * Émet un ticket pour `identifier`, valable {@link SESSION_TICKET_TTL_MS} ms.
+     *
+     * @param identifier - identifiant du compte pour lequel la session s'ouvrira.
+     * @returns le ticket, à présenter dans {@link SESSION_TICKET_HEADER}.
+     * @throws Error - identifiant vide, ou plafond de tickets en attente atteint.
+     */
+    issue(identifier: string): string;
+    /**
+     * Rachète un ticket : le retire, et rend l'identité pour laquelle il a été émis.
+     *
+     * La forme est contrôlée AVANT l'empreinte : une entrée hostile (1 Mo, autre
+     * type) ne coûte pas un hachage.
+     *
+     * @param ticket - valeur reçue, non fiable.
+     * @returns l'identifiant, ou `null` (absent, malformé, inconnu, expiré, déjà racheté).
+     */
+    redeem(ticket: unknown): string | null;
+}

package/dist/types/nodefony/mcp/stdio.d.ts

@@ -0,0 +1,38 @@
+import type { Readable } from "node:stream";
+import type { IMcpGate, IMcpGateRuntime } from "./gate.js";
+/**
+ * Le transport stdio de MCP : le client lance le serveur et lui parle par
+ * l'entrée et la sortie standard, un message JSON-RPC par ligne.
+ *
+ * Toute la règle vit dans la porte ({@link IMcpGate.respondStdio}) : ce
+ * fichier n'apporte que la lecture ligne à ligne et l'écriture des réponses.
+ */
+/** Ce que sert une boucle stdio. */
+export interface IMcpStdioOptions {
+    /** L'entrée du protocole — `process.stdin` en pratique. */
+    input: Readable;
+    /**
+     * Écrit UNE ligne sur la sortie du protocole, saut de ligne compris. La
+     * sortie standard EST le protocole : rien d'autre ne doit y écrire.
+     */
+    write: (line: string) => void;
+    /** Modules, identité, journal — transmis à la porte. */
+    runtime?: IMcpGateRuntime | undefined;
+}
+/**
+ * Sert une porte MCP sur un flux de lignes, jusqu'à la fin de l'entrée.
+ *
+ * Chaque ligne est servie SANS attendre la précédente : une
+ * `notifications/cancelled` doit pouvoir arriver pendant l'appel qu'elle
+ * vise. Les réponses partent donc dans l'ordre où elles se terminent — chacune
+ * porte son identifiant, c'est ce que JSON-RPC prévoit. Une ligne vide est
+ * ignorée ; une ligne illisible rend `-32700` sans arrêter la boucle.
+ *
+ * L'entrée fermée, le client est parti : les appels encore en cours sont
+ * abattus (leur signal), puis la promesse se résout quand tous ont rendu.
+ *
+ * @param gate - la porte à servir.
+ * @param options - entrée, écriture d'une ligne, environnement de la porte.
+ * @returns une promesse résolue à la fin de l'entrée, appels en cours clos.
+ */
+export declare function serveMcpStdio(gate: IMcpGate, options: IMcpStdioOptions): Promise<void>;

package/dist/types/nodefony/mcp/stream.d.ts

@@ -0,0 +1,76 @@
+import type { IMcpTransport } from "./server.js";
+/**
+ * Le flux de réponse d'une requête MCP, ouvert PARESSEUSEMENT — brique
+ * générique de la boîte à outils, indépendante du transport.
+ *
+ * Toute porte (HTTP de développement, porte d'une application, futur `stdio`)
+ * a la même décision à prendre : répondre en un objet, ou en flux quand
+ * l'appel a quelque chose à dire en route. La règle vit ICI, une fois : le flux
+ * ne s'ouvre qu'au PREMIER envoi, les envois s'enchaînent dans l'ordre, et la
+ * réponse finale clôt le flux. Un appel qui ne dit rien en route n'ouvre rien —
+ * la porte répond alors comme avant.
+ *
+ * Exception : un appel encore en cours au bout du délai de grâce
+ * ({@link MCP_STREAM_GRACE_MS}) ouvre le flux sans rien y écrire. La norme
+ * oblige le client à accepter une réponse SSE (`transports/streamable-http`),
+ * avec ou sans `progressToken` ; or une réponse JSON qui tarde tombe sous le
+ * délai d'inactivité de la requête (408), quand un flux ouvert le désarme et
+ * bat de lui-même. Un outil court n'y voit rien : il a répondu avant.
+ *
+ * La porte ne fournit que ce qu'elle seule sait faire : OUVRIR son flux
+ * (`renderSse()` pour une route HTTP).
+ */
+/**
+ * Délai de grâce, en ms : au-delà, un appel sans réponse ouvre le flux. Très en
+ * deçà du délai d'inactivité d'une requête (30 s par défaut), assez long pour
+ * qu'un outil ordinaire réponde en JSON comme avant.
+ */
+export declare const MCP_STREAM_GRACE_MS = 5000;
+/** Ce qu'une porte sait ouvrir : un puits d'événements, ordonné. */
+export interface IMcpEventSink {
+    /** Le flux est-il fermé (client parti, ou clos) ? */
+    readonly closed: boolean;
+    /**
+     * Envoie un message JSON-RPC ; peut lever à l'appel ou rendre une promesse
+     * de contre-pression.
+     */
+    send(data: unknown): Promise<void> | undefined;
+}
+/** Le flux de réponse d'UNE requête, vu de la porte. */
+export interface IMcpResponseStream<S extends IMcpEventSink> {
+    /** À donner au protocole (`IMcpServerContext.transport`). */
+    readonly transport: IMcpTransport;
+    /**
+     * Attend les envois en cours puis, si un flux a été ouvert, y écrit la
+     * réponse finale.
+     *
+     * @param body - la réponse JSON-RPC finale.
+     * @returns le flux ouvert (à clore par la porte), ou `null` : rien n'a été
+     *   envoyé en route, la porte répond en un objet.
+     */
+    finish(body: unknown): Promise<S | null>;
+}
+/** Options de {@link createMcpResponseStream}. */
+export interface IMcpResponseStreamOptions<S extends IMcpEventSink> {
+    /** Abattu quand le client abandonne la requête. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Ouvre le flux de la porte ; absent quand le client n'en accepte pas — la
+     * progression devient alors muette, jamais refusée.
+     */
+    open?: (() => S | Promise<S>) | undefined;
+    /**
+     * Ouvre le flux si l'appel n'a pas répondu dans ce délai (ms) ; absent ou 0 :
+     * le flux ne s'ouvre qu'au premier envoi.
+     */
+    graceMs?: number | undefined;
+    /** Un envoi perdu (client parti, événement refusé) : à journaliser. */
+    onError?: ((error: unknown, final: boolean) => void) | undefined;
+}
+/**
+ * Fabrique le flux de réponse paresseux d'une requête MCP.
+ *
+ * @param options - signal d'abandon, ouverture du flux, journal des pertes.
+ * @returns le transport à donner au protocole, et `finish()`.
+ */
+export declare function createMcpResponseStream<S extends IMcpEventSink>(options: IMcpResponseStreamOptions<S>): IMcpResponseStream<S>;

package/dist/types/nodefony/mcp/ticketSession.d.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import type { Controller } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+import { SessionTicketStore } from "./sessionTicket.js";
+/** Message unique de tout refus : la cause fine ne sort jamais vers l'appelant. */
+export declare const TICKET_SESSION_REFUSED = "ticket de session refus\u00E9";
+/** Ce que la route reçoit, tel que la requête le présente. */
+export interface ITicketSessionRequest {
+    /** Valeur de l'en-tête du ticket, non fiable. */
+    readonly ticket: unknown;
+    /** Adresse distante de la connexion. */
+    readonly remoteAddress: string | undefined;
+    /**
+     * La requête a traversé un relais (`isRelayedRequest`) : sur une porte
+     * locale, l'adresse ne prouve alors plus la localité.
+     */
+    readonly relayed?: boolean | undefined;
+}
+/** Compte pour lequel la session vient d'être ouverte. */
+export interface ITicketSessionUser {
+    readonly identifier: string;
+    readonly roles?: readonly string[] | undefined;
+}
+/** Ce dont la décision a besoin, fourni par la porte. */
+export interface ITicketSessionDeps {
+    /** Magasin des tickets, `null` si aucun n'a jamais été émis. */
+    readonly tickets: SessionTicketStore | null;
+    /**
+     * Ouvre la session pour `identifier` par le flux de session de l'application,
+     * `null` quand aucun n'est installé. Lève si le compte est inconnu ou refusé.
+     */
+    readonly establish: ((identifier: string) => Promise<ITicketSessionUser>) | null;
+    /** Pseudonyme public de la session ouverte, `null` si aucune ne l'est. */
+    readonly sessionRef: () => string | null;
+    /**
+     * Refuser tout appel qui ne vient pas de la machine locale. Absent = `true` :
+     * le ticket ne quitte jamais le process, la boucle locale est son seul chemin.
+     */
+    readonly localOnly?: boolean;
+}
+/** Verdict de la route : la session ouverte, ou un refus. */
+export type TicketSessionVerdict = {
+    readonly status: 200;
+    readonly identifier: string;
+    readonly roles: readonly string[];
+    readonly ref: string;
+} | {
+    readonly status: 403 | 503;
+    readonly message: string;
+};
+/**
+ * Décide l'ouverture d'une session par ticket.
+ *
+ * Ordre délibéré : la localité, puis la présence d'un flux de session, et
+ * seulement ensuite le rachat du ticket — un appel qui ne peut pas aboutir ne
+ * consomme pas le ticket. L'identité vient du TICKET, jamais de la requête.
+ *
+ * @param request - le ticket présenté et l'adresse de l'appelant.
+ * @param deps - magasin de tickets, flux de session, exigence de localité.
+ * @returns `200` avec le compte et le pseudonyme de session, `403` uniforme, ou
+ *   `503` quand l'application n'a pas de flux de session.
+ */
+export declare function openTicketSession(request: ITicketSessionRequest, deps: ITicketSessionDeps): Promise<TicketSessionVerdict>;
+/**
+ * Vue minimale du flux de session (`authFlow`, fourni par `@nodefony/security`).
+ * Ce module n'en dépend pas : le service se résout par NOM.
+ */
+export interface ISessionFlowView {
+    establishSessionFor(context: ContextType, identifier: string, reason?: string): Promise<unknown>;
+}
+/** Vue minimale du service de sessions (`sessions`, `@nodefony/http`). */
+export interface ISessionServiceView {
+    /** Pseudonyme public d'une session, non réversible. */
+    sessionRef(id: string): string;
+    /** Détruit la session désignée par son pseudonyme. */
+    destroyByRef(ref: string, actor?: string | null): Promise<boolean>;
+}
+/**
+ * Le service résolu est-il un flux de session utilisable ?
+ *
+ * @param value - service lu dans le conteneur.
+ * @returns `true` s'il ouvre une session pour une identité prouvée.
+ */
+export declare function isSessionFlowView(value: unknown): value is ISessionFlowView;
+/**
+ * Le service résolu est-il un service de sessions utilisable ?
+ *
+ * @param value - service lu dans le conteneur.
+ * @returns `true` s'il dérive un pseudonyme et détruit une session par lui.
+ */
+export declare function isSessionServiceView(value: unknown): value is ISessionServiceView;
+/**
+ * Lit le compte rendu par le flux de session, sans lui faire confiance.
+ *
+ * @param value - retour de `establishSessionFor`.
+ * @param identifier - identité du ticket, retenue si le retour n'en porte pas.
+ * @returns l'identifiant et les rôles chaîne du compte.
+ */
+export declare function toTicketSessionUser(value: unknown, identifier: string): ITicketSessionUser;
+/**
+ * Lit, côté outil, la réponse de la route de connexion par ticket — sans lui
+ * faire confiance. Vit à côté de {@link openTicketSession}, qui en produit la
+ * forme : deux copies du format divergeraient.
+ *
+ * @param body - corps de la réponse, `null` si aucun.
+ * @returns le compte et le pseudonyme de session, ou le message du refus.
+ */
+export declare function readTicketSessionVerdict(body: string | null): {
+    identifier: string;
+    roles: readonly string[];
+    ref: string;
+} | {
+    message: string;
+};
+/** Définition d'une porte de session par ticket — validée et figée au boot. */
+export declare const ticketSessionGateSchema: z.ZodObject<{
+    factor: z.ZodString;
+    localOnly: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Ce qu'on passe à {@link defineTicketSessionGate}. */
+export type ITicketSessionGateDefinition = z.input<typeof ticketSessionGateSchema>;
+/** Réglages effectifs d'une porte de session par ticket. */
+export type ITicketSessionGateSettings = z.output<typeof ticketSessionGateSchema>;
+/** Une porte de session par ticket définie — à servir depuis une action de controller. */
+export interface ITicketSessionGate {
+    /** Les réglages effectifs, validés et figés. */
+    readonly settings: ITicketSessionGateSettings;
+    /** Tickets émis, ni rachetés ni expirés. */
+    readonly pending: number;
+    /**
+     * Émet un ticket à usage unique pour `identifier`.
+     *
+     * @param identifier - compte au nom duquel la session s'ouvrira.
+     * @returns le ticket, à présenter dans {@link SESSION_TICKET_HEADER}.
+     * @throws Error - identifiant vide, ou plafond de tickets en attente atteint.
+     */
+    issue(identifier: string): string;
+    /**
+     * Sert la requête courante d'un controller : rachète le ticket et ouvre la
+     * session par le flux de l'application (`authFlow`, résolu par NOM).
+     *
+     * @param controller - le controller qui déclare la route (`POST`, chemin littéral).
+     * @returns ce que l'action doit rendre : le verdict en JSON, à son statut.
+     */
+    serve(controller: Controller): Promise<unknown>;
+    /**
+     * Détruit une session ouverte par ticket, au nom du facteur de la porte.
+     *
+     * @param sessions - le service `sessions` lu dans le conteneur.
+     * @param ref - pseudonyme rendu par la route.
+     * @returns `true` si une session a été détruite.
+     */
+    close(sessions: unknown, ref: string): Promise<boolean>;
+}
+/**
+ * Définit une porte de session par ticket : ce qui permet à un outil MCP de
+ * tirer de vraies requêtes HTTP vers l'application AU NOM d'un compte.
+ *
+ * Une session ne s'ouvre que par le flux de session de l'application
+ * (`authFlow.establishSessionFor`) : il revérifie le compte (actif, non
+ * verrouillé), régénère l'identifiant et écrit l'audit. Ce flux exige une
+ * requête en cours ; l'outil en envoie donc une, en boucle locale, à la route
+ * que le controller déclare, et récupère le cookie que la réponse pose.
+ * Fabriquer la session sans requête aurait recopié la règle de connexion.
+ *
+ * Comme {@link defineMcpGate}, la porte ne monte AUCUNE route : le controller
+ * qui en a besoin la déclare, chemin écrit en littéral, et appelle `serve`.
+ * Le magasin de tickets n'est alloué qu'au premier ticket émis.
+ *
+ * @param definition - facteur d'audit et exigence de localité.
+ * @returns la porte, figée.
+ * @throws BootConfigurationError - définition hors schéma.
+ */
+export declare function defineTicketSessionGate(definition: ITicketSessionGateDefinition): ITicketSessionGate;