@linklabjs/core 0.1.0 → 0.1.2

package/dist/navigation/Scheduler.js

@@ -0,0 +1,107 @@
+/**
+ * Scheduler - Exécution d'actions par priorité (mode SCHEDULE)
+ *
+ * À chaque step :
+ *   1. Filtre les actions disponibles (condition when + cooldown + terminal)
+ *   2. Sélectionne la plus prioritaire (weight le plus élevé)
+ *   3. L'exécute et met à jour l'état interne
+ *
+ * C'est le cœur du moteur d'agent : une boucle de décision
+ * déterministe basée sur les poids et l'état de la stack.
+ */
+export class Scheduler {
+    actions;
+    graph;
+    actionStates;
+    constructor(actions, graph) {
+        this.actions = actions;
+        this.graph = graph;
+        // Initialise l'état de chaque action
+        this.actionStates = new Map(actions.map(a => [
+            a.name,
+            { cooldownUntil: 0, executionCount: 0, executed: false }
+        ]));
+    }
+    /**
+     * Exécute un step du scheduler.
+     * Retourne null si aucune action n'est disponible (terminaison naturelle).
+     */
+    async step(time, stack) {
+        const available = this.getAvailableActions(time, stack);
+        if (available.length === 0)
+            return null;
+        // Sélection déterministe : weight le plus élevé
+        const selected = available.reduce((best, action) => action.weight > best.weight ? action : best);
+        console.log(`  ⚙️  [Scheduler t=${time}] → ${selected.name} (weight: ${selected.weight})`);
+        let result;
+        let updatedStack = stack;
+        try {
+            updatedStack = await selected.execute(stack, this.graph);
+            result = { type: 'SUCCESS', data: updatedStack };
+        }
+        catch (err) {
+            result = {
+                type: 'FAIL',
+                reason: err instanceof Error ? err.message : String(err)
+            };
+            console.error(`  ❌ [Scheduler] Action échouée: ${selected.name}`, err);
+        }
+        // Callback optionnel (analytics, logging externe...)
+        if (selected.onUse) {
+            try {
+                selected.onUse(stack, result);
+            }
+            catch {
+                // Silencieux — le callback ne doit pas planter le scheduler
+            }
+        }
+        // Mise à jour de l'état de l'action
+        this.updateState(selected, result, time);
+        return {
+            selectedAction: selected.name,
+            result,
+            updatedStack: result.type === 'SUCCESS' ? updatedStack : stack
+        };
+    }
+    /**
+     * Retourne les actions disponibles à un instant t pour une stack donnée.
+     * Filtre : terminal déjà exécuté, cooldown, maxExecutions, condition when().
+     */
+    getAvailableActions(time, stack) {
+        return this.actions.filter(action => {
+            const state = this.actionStates.get(action.name);
+            // Action terminale déjà exécutée
+            if (action.terminal && state.executed)
+                return false;
+            // En cooldown
+            if (state.cooldownUntil > time)
+                return false;
+            // Limite d'exécutions atteinte
+            if (action.maxExecutions !== undefined && state.executionCount >= action.maxExecutions) {
+                return false;
+            }
+            // Condition métier
+            if (!action.when)
+                return true;
+            try {
+                return action.when(stack);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    updateState(action, result, time) {
+        const current = this.actionStates.get(action.name);
+        this.actionStates.set(action.name, {
+            cooldownUntil: result.type === 'DEFER' ? time + (action.cooldown ?? 0) : 0,
+            executionCount: current.executionCount + 1,
+            executed: action.terminal ? true : current.executed,
+            lastResult: result
+        });
+    }
+    getActionState(name) {
+        return this.actionStates.get(name);
+    }
+}
+//# sourceMappingURL=Scheduler.js.map

package/dist/navigation/Scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduler.js","sourceRoot":"","sources":["../../src/navigation/Scheduler.ts"],"names":[],"mappings":"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"}

package/dist/navigation/Trail.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Trail — Contexte de navigation vivant
+ *
+ * Trois niveaux de contexte, trois durées de vie :
+ *
+ *   global   — vit aussi longtemps que l'instance LinkLab
+ *              config, feature flags, métriques globales
+ *
+ *   user     — vit le temps d'une session
+ *              userId, permissions, préférences, historique récent
+ *
+ *   frames   — vit le temps d'une navigation
+ *              le chemin parcouru, position courante
+ *
+ * Deux niveaux d'API :
+ *
+ *   Bas niveau  — trail.push(frame), trail.pop(), trail.compact()
+ *                 fondation sur laquelle tout repose
+ *
+ *   Haut niveau — API fluente, construite sur push()
+ *                 cinema.people('Nolan').movies
+ *
+ * Contrat de sérialisation :
+ *   global et user ne contiennent que des données — jamais de fonctions.
+ *   Un Trail sérialisé peut être rejoué exactement.
+ */
+import type { Frame } from '../types/index.js';
+export interface TrailInit {
+    global?: Record<string, any>;
+    user?: Record<string, any>;
+    frames?: Frame[];
+}
+/** Format de sérialisation — versionné pour les migrations futures */
+export interface SerializedTrail {
+    v: number;
+    global: Record<string, any>;
+    user: Record<string, any>;
+    frames: Frame[];
+    savedAt: string;
+}
+export declare class Trail {
+    /** Contexte global — long terme */
+    readonly global: Record<string, any>;
+    /** Contexte utilisateur — session */
+    readonly user: Record<string, any>;
+    /** Frames de navigation — readonly depuis l'extérieur */
+    private _frames;
+    private constructor();
+    /** Crée un Trail vierge, avec contextes optionnels */
+    static create(init?: TrailInit): Trail;
+    /** Restaure un Trail depuis sa forme sérialisée */
+    static from(serialized: string | SerializedTrail): Trail;
+    /** Toutes les frames — tableau immuable depuis l'extérieur */
+    get frames(): readonly Frame[];
+    /** Dernière frame — position courante */
+    get current(): Frame | undefined;
+    /** Nombre de frames */
+    get depth(): number;
+    /** Vrai si toutes les frames sont résolues */
+    get isFullyResolved(): boolean;
+    /** Frames non résolues */
+    get unresolved(): Frame[];
+    /**
+     * Pousse une frame sur le Trail.
+     * Retourne this pour le chaînage.
+     *
+     * Si state n'est pas précisé :
+     *   - id fourni  → RESOLVED
+     *   - id absent  → UNRESOLVED
+     */
+    push(frame: Frame): this;
+    /**
+     * Retire et retourne la dernière frame.
+     * Retourne undefined si le Trail est vide.
+     */
+    pop(): Frame | undefined;
+    /**
+     * Met à jour une frame existante par index ou par entity.
+     * Réservé à LinkLab — permet au moteur de synchroniser les frames résolues.
+     *
+     * @param entity  - L'entité de la frame à mettre à jour
+     * @param updated - Les nouvelles valeurs à merger
+     */
+    updateFrame(entity: string, updated: Partial<Frame>): boolean;
+    /**
+     * Compacte le Trail — supprime les frames non-discriminantes
+     * en conservant uniquement les frames qui portent un id
+     * ou qui sont la position courante.
+     *
+     * Exemple :
+     *   [cinema][people(Nolan)][movies(Interstellar)][actors]
+     *   →  [people(Nolan)][movies(Interstellar)][actors]
+     *
+     * Note : réservé à LinkLab — appelé par le moteur, pas par les hooks.
+     */
+    compact(): this;
+    /**
+     * Retourne la frame à l'index donné (0 = première).
+     * Accepte les index négatifs (-1 = dernière).
+     */
+    at(index: number): Frame | undefined;
+    /**
+     * Retourne la dernière frame dont l'entity correspond.
+     */
+    find(entity: string): Frame | undefined;
+    /**
+     * Retourne un Trail tronqué jusqu'à l'index donné (non inclus).
+     * Utile pour le replay partiel.
+     */
+    slice(end: number): Trail;
+    /**
+     * Sérialise le Trail en JSON.
+     * global et user ne doivent contenir que des données — les fonctions
+     * sont silencieusement ignorées par JSON.stringify.
+     */
+    serialize(): string;
+    toJSON(): SerializedTrail;
+    /**
+     * Deep copy — utile pour le replay ou les tests.
+     * Le clone est indépendant — modifier l'un ne modifie pas l'autre.
+     */
+    clone(): Trail;
+    /**
+     * Représentation lisible du Trail courant.
+     * ex: [people(Nolan)] → [movies(Interstellar)] → [actors?]
+     */
+    toString(): string;
+}
+//# sourceMappingURL=Trail.d.ts.map

package/dist/navigation/Trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Trail.d.ts","sourceRoot":"","sources":["../../src/navigation/Trail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAI9C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,EAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAQ,MAAM,CAAA;IACf,MAAM,EAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,IAAI,EAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,MAAM,EAAG,KAAK,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAID,qBAAa,KAAK;IAChB,mCAAmC;IACnC,SAAgB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE3C,qCAAqC;IACrC,SAAgB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEzC,yDAAyD;IACzD,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO;IAQP,sDAAsD;IACtD,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,SAAc,GAAG,KAAK;IAI1C,mDAAmD;IACnD,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,KAAK;IAkBxD,8DAA8D;IAC9D,IAAI,MAAM,IAAI,SAAS,KAAK,EAAE,CAE7B;IAED,yCAAyC;IACzC,IAAI,OAAO,IAAI,KAAK,GAAG,SAAS,CAE/B;IAED,uBAAuB;IACvB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8CAA8C;IAC9C,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,0BAA0B;IAC1B,IAAI,UAAU,IAAI,KAAK,EAAE,CAExB;IAID;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IASxB;;;OAGG;IACH,GAAG,IAAI,KAAK,GAAG,SAAS;IAIxB;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO;IAS7D;;;;;;;;;;OAUG;IACH,OAAO,IAAI,IAAI;IAQf;;;OAGG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAKpC;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIvC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK;IAUzB;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAInB,MAAM,IAAI,eAAe;IAUzB;;;OAGG;IACH,KAAK,IAAI,KAAK;IAMd;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAWnB"}

package/dist/navigation/Trail.js

@@ -0,0 +1,202 @@
+/**
+ * Trail — Contexte de navigation vivant
+ *
+ * Trois niveaux de contexte, trois durées de vie :
+ *
+ *   global   — vit aussi longtemps que l'instance LinkLab
+ *              config, feature flags, métriques globales
+ *
+ *   user     — vit le temps d'une session
+ *              userId, permissions, préférences, historique récent
+ *
+ *   frames   — vit le temps d'une navigation
+ *              le chemin parcouru, position courante
+ *
+ * Deux niveaux d'API :
+ *
+ *   Bas niveau  — trail.push(frame), trail.pop(), trail.compact()
+ *                 fondation sur laquelle tout repose
+ *
+ *   Haut niveau — API fluente, construite sur push()
+ *                 cinema.people('Nolan').movies
+ *
+ * Contrat de sérialisation :
+ *   global et user ne contiennent que des données — jamais de fonctions.
+ *   Un Trail sérialisé peut être rejoué exactement.
+ */
+// ── Trail ─────────────────────────────────────────────────────
+export class Trail {
+    /** Contexte global — long terme */
+    global;
+    /** Contexte utilisateur — session */
+    user;
+    /** Frames de navigation — readonly depuis l'extérieur */
+    _frames;
+    constructor(init = {}) {
+        this.global = init.global ?? {};
+        this.user = init.user ?? {};
+        this._frames = init.frames ? init.frames.map(f => ({ ...f })) : [];
+    }
+    // ── Factories ──────────────────────────────────────────────
+    /** Crée un Trail vierge, avec contextes optionnels */
+    static create(init = {}) {
+        return new Trail(init);
+    }
+    /** Restaure un Trail depuis sa forme sérialisée */
+    static from(serialized) {
+        const data = typeof serialized === 'string'
+            ? JSON.parse(serialized)
+            : serialized;
+        if (data.v !== 1) {
+            throw new Error(`Trail.from: version ${data.v} non supportée`);
+        }
+        return new Trail({
+            global: data.global ?? {},
+            user: data.user ?? {},
+            frames: data.frames ?? [],
+        });
+    }
+    // ── Accesseurs frames ──────────────────────────────────────
+    /** Toutes les frames — tableau immuable depuis l'extérieur */
+    get frames() {
+        return this._frames;
+    }
+    /** Dernière frame — position courante */
+    get current() {
+        return this._frames[this._frames.length - 1];
+    }
+    /** Nombre de frames */
+    get depth() {
+        return this._frames.length;
+    }
+    /** Vrai si toutes les frames sont résolues */
+    get isFullyResolved() {
+        return this._frames.every(f => f.state === 'RESOLVED');
+    }
+    /** Frames non résolues */
+    get unresolved() {
+        return this._frames.filter(f => f.state === 'UNRESOLVED');
+    }
+    // ── API bas niveau ─────────────────────────────────────────
+    /**
+     * Pousse une frame sur le Trail.
+     * Retourne this pour le chaînage.
+     *
+     * Si state n'est pas précisé :
+     *   - id fourni  → RESOLVED
+     *   - id absent  → UNRESOLVED
+     */
+    push(frame) {
+        const normalized = {
+            ...frame,
+            state: frame.state ?? (frame.id !== undefined ? 'RESOLVED' : 'UNRESOLVED'),
+        };
+        this._frames.push(normalized);
+        return this;
+    }
+    /**
+     * Retire et retourne la dernière frame.
+     * Retourne undefined si le Trail est vide.
+     */
+    pop() {
+        return this._frames.pop();
+    }
+    /**
+     * Met à jour une frame existante par index ou par entity.
+     * Réservé à LinkLab — permet au moteur de synchroniser les frames résolues.
+     *
+     * @param entity  - L'entité de la frame à mettre à jour
+     * @param updated - Les nouvelles valeurs à merger
+     */
+    updateFrame(entity, updated) {
+        const idx = this._frames.findIndex(f => f.entity === entity && f.state === 'UNRESOLVED');
+        if (idx === -1)
+            return false;
+        this._frames[idx] = { ...this._frames[idx], ...updated };
+        return true;
+    }
+    /**
+     * Compacte le Trail — supprime les frames non-discriminantes
+     * en conservant uniquement les frames qui portent un id
+     * ou qui sont la position courante.
+     *
+     * Exemple :
+     *   [cinema][people(Nolan)][movies(Interstellar)][actors]
+     *   →  [people(Nolan)][movies(Interstellar)][actors]
+     *
+     * Note : réservé à LinkLab — appelé par le moteur, pas par les hooks.
+     */
+    compact() {
+        const last = this._frames.length - 1;
+        this._frames = this._frames.filter((f, i) => i === last || f.id !== undefined);
+        return this;
+    }
+    /**
+     * Retourne la frame à l'index donné (0 = première).
+     * Accepte les index négatifs (-1 = dernière).
+     */
+    at(index) {
+        if (index < 0)
+            index = this._frames.length + index;
+        return this._frames[index];
+    }
+    /**
+     * Retourne la dernière frame dont l'entity correspond.
+     */
+    find(entity) {
+        return [...this._frames].reverse().find(f => f.entity === entity);
+    }
+    /**
+     * Retourne un Trail tronqué jusqu'à l'index donné (non inclus).
+     * Utile pour le replay partiel.
+     */
+    slice(end) {
+        return new Trail({
+            global: { ...this.global },
+            user: { ...this.user },
+            frames: this._frames.slice(0, end),
+        });
+    }
+    // ── Sérialisation ──────────────────────────────────────────
+    /**
+     * Sérialise le Trail en JSON.
+     * global et user ne doivent contenir que des données — les fonctions
+     * sont silencieusement ignorées par JSON.stringify.
+     */
+    serialize() {
+        return JSON.stringify(this.toJSON());
+    }
+    toJSON() {
+        return {
+            v: 1,
+            global: this.global,
+            user: this.user,
+            frames: [...this._frames],
+            savedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Deep copy — utile pour le replay ou les tests.
+     * Le clone est indépendant — modifier l'un ne modifie pas l'autre.
+     */
+    clone() {
+        return Trail.from(this.toJSON());
+    }
+    // ── Debug ──────────────────────────────────────────────────
+    /**
+     * Représentation lisible du Trail courant.
+     * ex: [people(Nolan)] → [movies(Interstellar)] → [actors?]
+     */
+    toString() {
+        if (this._frames.length === 0)
+            return '(trail vide)';
+        return this._frames
+            .map(f => {
+            const id = f.id !== undefined ? `(${f.id})` : '';
+            const state = f.state === 'UNRESOLVED' ? '?' : f.state === 'DEFERRED' ? '…' : '';
+            return `[${f.entity}${id}${state}]`;
+        })
+            .join(' → ');
+    }
+}
+//# sourceMappingURL=Trail.js.map

package/dist/navigation/Trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Trail.js","sourceRoot":"","sources":["../../src/navigation/Trail.ts"],"names":[],"mappings":"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"}

package/dist/navigation/TrailParser.d.ts

@@ -0,0 +1,96 @@
+/**
+ * TrailParser — Désérialise des représentations externes vers un Trail
+ *
+ * Trois sources supportées :
+ *
+ *   URL path   →  /cinema/people/Nolan/movies/Interstellar/actors
+ *   URL fluent →  cinema.people(Nolan).movies(Interstellar).actors
+ *   JSON       →  SerializedTrail (via Trail.from)
+ *
+ * Le parser est stateless — toutes les méthodes sont statiques.
+ * Il ne valide pas les entités contre le graphe — c'est le rôle du moteur.
+ */
+import { Trail } from './Trail.js';
+export declare class TrailParser {
+    /**
+     * Parse un path HTTP en Trail.
+     *
+     * Convention :
+     *   /entity              → Frame(entity, UNRESOLVED)
+     *   /entity/id           → Frame(entity, id, RESOLVED)
+     *   /entity/id/other     → Frame(entity, id) + Frame(other, UNRESOLVED)
+     *
+     * Exemples :
+     *   /people                     → [people?]
+     *   /people/Nolan               → [people(Nolan)]
+     *   /people/Nolan/movies        → [people(Nolan)] → [movies?]
+     *   /people/Nolan/movies/2      → [people(Nolan)] → [movies(2)]
+     *   /cinema/people/Nolan/movies → [cinema] → [people(Nolan)] → [movies?]
+     *
+     * @param path  - URL path, avec ou sans slash initial
+     * @param init  - Contextes global/user à injecter
+     */
+    static fromPath(path: string, init?: {
+        global?: Record<string, any>;
+        user?: Record<string, any>;
+    }): Trail;
+    /**
+     * Parse une expression fluente en Trail.
+     *
+     * Syntaxe :
+     *   entity                  → Frame(entity, UNRESOLVED)
+     *   entity(id)              → Frame(entity, id, RESOLVED)
+     *   entity.other            → Frame(entity) + Frame(other)
+     *   entity(id).other(id2)   → Frame(entity,id) + Frame(other,id2)
+     *
+     * Exemples :
+     *   people                         → [people?]
+     *   people(Nolan)                  → [people(Nolan)]
+     *   people(Nolan).movies           → [people(Nolan)] → [movies?]
+     *   cinema.people(Nolan).movies(2) → [cinema] → [people(Nolan)] → [movies(2)]
+     *
+     * @param expr  - Expression fluente
+     * @param init  - Contextes global/user à injecter
+     */
+    static fromFluent(expr: string, init?: {
+        global?: Record<string, any>;
+        user?: Record<string, any>;
+    }): Trail;
+    /**
+     * Sérialise un Trail en path HTTP.
+     *
+     * Exemple :
+     *   Trail([people(Nolan)][movies?])  →  /people/Nolan/movies
+     */
+    static toPath(trail: Trail): string;
+    /**
+     * Sérialise un Trail en expression fluente.
+     *
+     * Exemple :
+     *   Trail([people(Nolan)][movies?])  →  people(Nolan).movies
+     */
+    static toFluent(trail: Trail): string;
+    /**
+     * Heuristique : un segment ressemble-t-il à un nom d'entité ?
+     * Les entités commencent par une lettre minuscule et ne contiennent
+     * que des lettres, chiffres et tirets.
+     */
+    private static looksLikeEntity;
+    /**
+     * Essaie de convertir un id en nombre, sinon garde la string.
+     */
+    private static coerceId;
+    /**
+     * Tokenise une expression fluente en segments.
+     * Préserve le contenu des parenthèses (les ids peuvent contenir des points).
+     *
+     * ex: "cinema.people(Nolan.Jr).movies"
+     *   → ["cinema", "people(Nolan.Jr)", "movies"]
+     */
+    private static tokenizeFluent;
+    /**
+     * Parse un token "entity" ou "entity(id)" en Frame.
+     */
+    private static parseToken;
+}
+//# sourceMappingURL=TrailParser.d.ts.map

package/dist/navigation/TrailParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailParser.d.ts","sourceRoot":"","sources":["../../src/navigation/TrailParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGlC,qBAAa,WAAW;IAItB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAO,GACtE,KAAK;IAyBR;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,UAAU,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAO,GACtE,KAAK;IAcR;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAanC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQrC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAI9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;IAKvB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAwB7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;CAqB1B"}