@hoilab/ada-cli 0.85.0 → 0.85.3

package/dist/core/colaboracion/rele/suscriptor.js

@@ -0,0 +1,173 @@
+/**
+ * Cliente de suscripción al relay AG8 — reconexión con backoff y replay.
+ *
+ * El cliente es la mitad E2E del par: presenta el token de sala en cabecera
+ * (NUNCA en URL ni argv), recibe tramas selladas y las abre con la MISMA
+ * primitiva scrypt+AES-256-GCM del share (src/core/share/cifrado.ts). Lo que
+ * sale del iterador son eventos ya descifrados; lo que cruza la red es
+ * ciphertext autenticado.
+ *
+ * Reconexión: un corte de red (o `ReleServidor.cortar()`) reintenta con
+ * backoff exponencial acotado. Al reconectar declara `x-rele-desde-seq` con
+ * la última secuencia entregada; el relay re-envía lo caído en el anillo y
+ * el cliente DEDUPLICA por seq (at-least-once → exactamente-once). Dos salidas
+ * limpias:
+ * - 401: token erróneo → error inmediato, SIN reintentos (reintentar una
+ *   credencial rechazada es martillear una puerta cerrada).
+ * - 410: sala cerrada → el iterador termina normalmente.
+ */
+import { abrir, ClaveIncorrecta } from "../../share/cifrado.js";
+const RETRASO_BASE = 100;
+const RETRASO_MAXIMO = 2000;
+/** Cola mínima productor/consumidor para convertir pushes en async iteration. */
+class Cola {
+    #pendientes = [];
+    #despertar = null;
+    #terminada = false;
+    #error = null;
+    empujar(evento) {
+        this.#pendientes.push(evento);
+        this.#despertar?.();
+        this.#despertar = null;
+    }
+    terminar(error) {
+        if (error) {
+            this.#error = error;
+        }
+        this.#terminada = true;
+        this.#despertar?.();
+        this.#despertar = null;
+    }
+    get terminada() {
+        return this.#terminada;
+    }
+    async siguiente() {
+        while (this.#pendientes.length === 0 && !this.#terminada) {
+            await new Promise((resolver) => {
+                this.#despertar = resolver;
+            });
+        }
+        if (this.#pendientes.length > 0) {
+            return this.#pendientes.shift();
+        }
+        if (this.#error) {
+            throw this.#error;
+        }
+        return undefined;
+    }
+}
+function esperar(ms) {
+    return new Promise((resolver) => {
+        setTimeout(resolver, ms);
+    });
+}
+export function suscribirse(url, token, opciones = {}) {
+    const base = opciones.retrasoBaseMs ?? RETRASO_BASE;
+    const maximo = opciones.retrasoMaximoMs ?? RETRASO_MAXIMO;
+    const cola = new Cola();
+    const control = new AbortController();
+    let ultimoEntregado = 0;
+    void (async () => {
+        let espera = base;
+        while (!control.signal.aborted && !cola.terminada) {
+            try {
+                const cabeceras = { "x-rele-token": token };
+                if (ultimoEntregado > 0) {
+                    cabeceras["x-rele-desde-seq"] = String(ultimoEntregado);
+                }
+                const respuesta = await fetch(url, {
+                    headers: cabeceras,
+                    signal: control.signal,
+                });
+                if (respuesta.status === 401) {
+                    cola.terminar(new Error("Token de sala rechazado por el relay."));
+                    break;
+                }
+                if (respuesta.status === 410) {
+                    cola.terminar();
+                    break;
+                }
+                if (!respuesta.ok || !respuesta.body) {
+                    throw new Error(`El relay respondió ${respuesta.status}.`);
+                }
+                espera = base;
+                const lector = respuesta.body.getReader();
+                const decodificador = new TextDecoder();
+                let resto = "";
+                try {
+                    for (;;) {
+                        const { done, value } = await lector.read();
+                        if (done || control.signal.aborted || cola.terminada) {
+                            break;
+                        }
+                        resto += decodificador.decode(value, { stream: true });
+                        let corte = resto.indexOf("\n\n");
+                        while (corte !== -1) {
+                            const bloque = resto.slice(0, corte);
+                            resto = resto.slice(corte + 2);
+                            corte = resto.indexOf("\n\n");
+                            for (const linea of bloque.split("\n")) {
+                                if (!linea.startsWith("data:")) {
+                                    continue;
+                                }
+                                let evento;
+                                try {
+                                    const claro = Buffer.from(abrir(Buffer.from(linea.slice(5), "base64"), token)).toString("utf8");
+                                    evento = JSON.parse(claro);
+                                }
+                                catch (e) {
+                                    if (e instanceof ClaveIncorrecta) {
+                                        throw e;
+                                    }
+                                    continue;
+                                }
+                                // Dedup por seq: el replay del relay puede re-entregar eventos
+                                // ya vistos antes del corte. Sin seq (relay viejo), pasa tal cual.
+                                if (typeof evento.seq === "number") {
+                                    if (evento.seq <= ultimoEntregado) {
+                                        continue;
+                                    }
+                                    ultimoEntregado = evento.seq;
+                                }
+                                cola.empujar(evento);
+                            }
+                        }
+                    }
+                }
+                finally {
+                    lector.cancel().catch(() => { });
+                }
+            }
+            catch (e) {
+                if (control.signal.aborted || cola.terminada) {
+                    break;
+                }
+                if (e instanceof ClaveIncorrecta) {
+                    cola.terminar(new Error("Una trama del relay no abre con el token de sala."));
+                    break;
+                }
+            }
+            if (control.signal.aborted || cola.terminada) {
+                break;
+            }
+            await esperar(espera);
+            espera = Math.min(espera * 2, maximo);
+        }
+        if (!cola.terminada) {
+            cola.terminar();
+        }
+    })();
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                next: () => cola
+                    .siguiente()
+                    .then((v) => (v === undefined ? { value: v, done: true } : { value: v, done: false })),
+            };
+        },
+        cerrar() {
+            control.abort();
+        },
+    };
+}
+//# sourceMappingURL=suscriptor.js.map

package/dist/core/colaboracion/rele/suscriptor.js.map

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

package/dist/core/colaboracion/sesion-colaborativa.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Sesión colaborativa E2E local — CO1 (Fase 4), versión mínima sin red.
+ *
+ * Referencia omp: collab-web/src/lib/{socket,codec,link}.ts (relay WebSocket +
+ * AES-256-GCM). El hallazgo CO1 pide colaboración en vivo cifrada; la pieza
+ * que se adelanta aquí es el sustrato sobre el que todo lo demás cuelga: DOS
+ * agentes (dos instancias independientes) escriben al MISMO journal arbolado
+ * (src/core/sesion/journal-tree.ts, reusado tal cual) sin pisarse.
+ *
+ * Por qué no hay relay ni cifrado todavía: el árbol de journal ya resuelve el
+ * problema duro del merge — dos ramas hermanas bajo el mismo padre son
+ * válidas por construcción, así que "sin pisarse" no necesita locks sino ids
+ * únicos por agente. El cifrado E2E y el relay llegan con AG8 (streamProxy);
+ * cuando aterricen, esta clase es la unidad que sincroniza.
+ *
+ * Contrato:
+ * - Cada agente tiene SU instancia, apuntando al mismo fichero JSONL en disco.
+ * - appendAgente genera ids con prefijo del agente + sufijo aleatorio: nunca
+ *   colisionan ni entre procesos ni tras reinicios.
+ * - sincronizar() fusiona lo que haya en disco con lo local (unión por id,
+ *   reconstrucción padres-primero) y republica el fichero atómicamente
+ *   (saveAtomic de JournalTree: temp + fsync + rename).
+ * - La fusión NUNCA pierde entradas de ningún lado: es unión, no
+ *   last-writer-wins.
+ */
+import { type JournalEntry, JournalTree } from "../sesion/journal-tree.ts";
+/** Id de la entrada raíz de toda sesión colaborativa. */
+export declare const RAIZ_COLABORACION = "colaboracion-raiz";
+export interface ResultadoSincronizacion {
+    /** Entradas locales que sobrevivieron a la fusión (todas, por contrato). */
+    readonly totales: number;
+    /** Entradas traídas desde disco que no estaban en memoria. */
+    readonly traidasDeDisco: number;
+}
+export declare class SesionColaborativa {
+    #private;
+    readonly rutaFichero: string;
+    private constructor();
+    get journal(): JournalTree;
+    /**
+     * Abre (o crea) la sesión colaborativa en `dir`. Si el fichero existe,
+     * carga su árbol; si no, crea uno nuevo con la entrada raíz.
+     */
+    static abrir(dir: string, nombre?: string): SesionColaborativa;
+    /**
+     * El agente `agenteId` añade una entrada. El padre es la leaf ACTUAL del
+     * árbol local; si otro agente colgó algo del mismo padre mientras tanto,
+     * el resultado son ramas hermanas — válido por diseño del árbol, nada se
+     * pisa.
+     */
+    appendAgente(agenteId: string, type: string, data: unknown): JournalEntry;
+    /** Ids de los agentes presentes (prefijos antes de '#' de las entradas no raíz). */
+    participantes(): string[];
+    /**
+     * Fusiona el estado de disco con el local y republica atómicamente.
+     * Unión por id, reconstrucción padres-primero: si algún ciclo o padre
+     * huérfano apareciera, lanza en vez de escribir un fichero roto.
+     */
+    sincronizar(): ResultadoSincronizacion;
+}
+//# sourceMappingURL=sesion-colaborativa.d.ts.map

package/dist/core/colaboracion/sesion-colaborativa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sesion-colaborativa.d.ts","sourceRoot":"","sources":["../../../src/core/colaboracion/sesion-colaborativa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,EAAE,KAAK,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE3E,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,kBAAkB;;IAG9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,OAAO;IAKP,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAuB,GAAG,kBAAkB;IAU5E;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY;IAOzE,oFAAoF;IACpF,aAAa,IAAI,MAAM,EAAE;IAUzB;;;;OAIG;IACH,WAAW,IAAI,uBAAuB;CAyCtC"}

package/dist/core/colaboracion/sesion-colaborativa.js

@@ -0,0 +1,127 @@
+/**
+ * Sesión colaborativa E2E local — CO1 (Fase 4), versión mínima sin red.
+ *
+ * Referencia omp: collab-web/src/lib/{socket,codec,link}.ts (relay WebSocket +
+ * AES-256-GCM). El hallazgo CO1 pide colaboración en vivo cifrada; la pieza
+ * que se adelanta aquí es el sustrato sobre el que todo lo demás cuelga: DOS
+ * agentes (dos instancias independientes) escriben al MISMO journal arbolado
+ * (src/core/sesion/journal-tree.ts, reusado tal cual) sin pisarse.
+ *
+ * Por qué no hay relay ni cifrado todavía: el árbol de journal ya resuelve el
+ * problema duro del merge — dos ramas hermanas bajo el mismo padre son
+ * válidas por construcción, así que "sin pisarse" no necesita locks sino ids
+ * únicos por agente. El cifrado E2E y el relay llegan con AG8 (streamProxy);
+ * cuando aterricen, esta clase es la unidad que sincroniza.
+ *
+ * Contrato:
+ * - Cada agente tiene SU instancia, apuntando al mismo fichero JSONL en disco.
+ * - appendAgente genera ids con prefijo del agente + sufijo aleatorio: nunca
+ *   colisionan ni entre procesos ni tras reinicios.
+ * - sincronizar() fusiona lo que haya en disco con lo local (unión por id,
+ *   reconstrucción padres-primero) y republica el fichero atómicamente
+ *   (saveAtomic de JournalTree: temp + fsync + rename).
+ * - La fusión NUNCA pierde entradas de ningún lado: es unión, no
+ *   last-writer-wins.
+ */
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { JournalTree } from "../sesion/journal-tree.js";
+/** Id de la entrada raíz de toda sesión colaborativa. */
+export const RAIZ_COLABORACION = "colaboracion-raiz";
+export class SesionColaborativa {
+    #journal;
+    #contador = 0;
+    rutaFichero;
+    constructor(rutaFichero, journal) {
+        this.rutaFichero = rutaFichero;
+        this.#journal = journal;
+    }
+    get journal() {
+        return this.#journal;
+    }
+    /**
+     * Abre (o crea) la sesión colaborativa en `dir`. Si el fichero existe,
+     * carga su árbol; si no, crea uno nuevo con la entrada raíz.
+     */
+    static abrir(dir, nombre = "colaboracion.jsonl") {
+        const rutaFichero = join(dir, nombre);
+        if (!fs.existsSync(rutaFichero)) {
+            const j = new JournalTree();
+            j.append({ id: RAIZ_COLABORACION, parentId: null, type: "colaboracion-raiz", data: {} });
+            return new SesionColaborativa(rutaFichero, j);
+        }
+        return new SesionColaborativa(rutaFichero, JournalTree.loadAtomic(rutaFichero));
+    }
+    /**
+     * El agente `agenteId` añade una entrada. El padre es la leaf ACTUAL del
+     * árbol local; si otro agente colgó algo del mismo padre mientras tanto,
+     * el resultado son ramas hermanas — válido por diseño del árbol, nada se
+     * pisa.
+     */
+    appendAgente(agenteId, type, data) {
+        if (!agenteId.trim())
+            throw new Error("appendAgente: agenteId requerido");
+        const id = `${agenteId}#${++this.#contador}-${randomUUID().slice(0, 8)}`;
+        const padre = this.#journal.getLeaf()?.id ?? RAIZ_COLABORACION;
+        return this.#journal.append({ id, parentId: padre, type, data });
+    }
+    /** Ids de los agentes presentes (prefijos antes de '#' de las entradas no raíz). */
+    participantes() {
+        const out = new Set();
+        for (const e of this.#journal.entries()) {
+            if (e.id === RAIZ_COLABORACION)
+                continue;
+            const hash = e.id.indexOf("#");
+            if (hash > 0)
+                out.add(e.id.slice(0, hash));
+        }
+        return [...out].sort();
+    }
+    /**
+     * Fusiona el estado de disco con el local y republica atómicamente.
+     * Unión por id, reconstrucción padres-primero: si algún ciclo o padre
+     * huérfano apareciera, lanza en vez de escribir un fichero roto.
+     */
+    sincronizar() {
+        const disco = fs.existsSync(this.rutaFichero) ? JournalTree.loadAtomic(this.rutaFichero) : new JournalTree();
+        const porId = new Map();
+        const orden = [];
+        for (const e of this.#journal.entries()) {
+            porId.set(e.id, e);
+            orden.push(e.id);
+        }
+        let traidasDeDisco = 0;
+        for (const e of disco.entries()) {
+            if (porId.has(e.id))
+                continue;
+            porId.set(e.id, e);
+            orden.push(e.id);
+            traidasDeDisco++;
+        }
+        // Reconstrucción padres-primero (los moves pueden dejar el orden de
+        // inserción inconsistente con la jerarquía).
+        const fusionado = new JournalTree();
+        let pendientes = [...orden];
+        while (pendientes.length > 0) {
+            let progreso = false;
+            const resto = [];
+            for (const id of pendientes) {
+                const e = porId.get(id);
+                if (e.parentId !== null && !fusionado.has(e.parentId)) {
+                    resto.push(id);
+                    continue;
+                }
+                fusionado.append({ ...e });
+                progreso = true;
+            }
+            if (!progreso)
+                throw new Error("sincronizar: ciclo o padre huérfano en la fusión");
+            pendientes = resto;
+        }
+        this.#journal = fusionado;
+        fusionado.saveAtomic(this.rutaFichero);
+        return { totales: fusionado.size, traidasDeDisco };
+    }
+}
+//# sourceMappingURL=sesion-colaborativa.js.map

package/dist/core/colaboracion/sesion-colaborativa.js.map

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

package/dist/core/commits/agentic.d.ts

@@ -0,0 +1,101 @@
+/**
+ * D08 — Commit agéntico: el mensaje sale de una conversación con herramientas
+ * sobre el diff REAL del índice, nunca de una sola pasada ciega.
+ *
+ * Por qué agéntico y no map-reduce single-shot (D14 manda cutover limpio, sin
+ * convivencia de dos pipelines):
+ *
+ *   - El modelo decide QUÉ mirar: puede pedir el diff de un fichero concreto
+ *     (`diff_de_fichero`) en vez de tragarse 25 diffs recortados a ciegas.
+ *   - Ve el estilo real del repo (`commits_recientes`): imita `feat(x): …` si
+ *     el repo lo usa y no si no.
+ *   - La proposal se VALIDA contra el diff antes de aceptarse, con errores y
+ *     avisos ESTRUCTURADOS que se le devuelven como recordatorios sintéticos
+ *     (hasta 3×). «No inventes cambios» deja de ser un ruego del prompt y pasa
+ *     a ser una comprobación: todo fichero citado que no esté en el diff es un
+ *     error y la propuesta se rechaza.
+ *
+ * Degradación honesta: si tras los recordatorios sigue sin haber propuesta
+ * válida, se genera un mensaje DETERMINISTA desde los datos del diff (solo
+ * ficheros reales, sin tipo convencional inventado) y se marca `usedFallback`
+ * para que el llamador sepa que esto salió sin el modelo, no con él.
+ */
+import { type TrozoDeFichero } from "./diff.ts";
+/** Tipos de conventional commits que la validación acepta. */
+export declare const TIPOS_CONVENCIONALES: readonly ["feat", "fix", "docs", "style", "perf", "test", "build", "ci", "chore", "revert"];
+export type TipoConvencional = (typeof TIPOS_CONVENCIONALES)[number];
+/** ¿El titular vale para cualquier commit? */
+export declare function esGenerico(mensaje: string): boolean;
+/** Un problema que NO bloquea la propuesta pero se reporta. */
+export interface Aviso {
+    codigo: string;
+    detalle: string;
+}
+/** Un problema que SÍ bloquea: se devuelve al modelo como recordatorio. */
+export interface ErrorDePropuesta {
+    campo: string;
+    detalle: string;
+}
+export interface PropuestaCruda {
+    tipo: string;
+    ambito?: string;
+    titular: string;
+    cuerpo?: string;
+    ficheros: string[];
+}
+export interface PropuestaAgentic {
+    mensaje: string;
+    ficheros: string[];
+    avisos: Aviso[];
+    /** true = salió por la vía determinista; el modelo nunca dio una propuesta válida. */
+    usedFallback: boolean;
+}
+/**
+ * Lo que el CLI inyecta para poder probar todo sin red ni repo.
+ * `llamar` debe LANZAR si el proveedor falla; devolver "" cuenta como ronda perdida.
+ */
+export interface DependenciasAgenticas {
+    llamar: (sistema: string, usuario: string) => Promise<string>;
+    ejecutarGit: (args: string[]) => string;
+    rondas?: number;
+}
+/** Fallo con nombre: el CLI distingue índice vacío de modelo caído sin leer prosa. */
+export type CausaDeFallo = "diff-vacio" | "diff-ilegible" | "modelo";
+export declare class ErrorDeCommit extends Error {
+    readonly causa: CausaDeFallo;
+    constructor(causa: CausaDeFallo, mensaje: string);
+}
+/** ¿La respuesta es una llamada a herramienta? */
+export declare function esLlamadaAHerramienta(json: unknown): json is {
+    herramienta: string;
+    argumentos?: Record<string, unknown>;
+};
+/** ¿Es la propuesta final? */
+export declare function esPropuesta(json: unknown): json is {
+    proponer_commit: Record<string, unknown>;
+};
+/**
+ * Valida una propuesta cruda CONTRA EL DIFF REAL.
+ *
+ * Errores (bloquean): tipo desconocido, titular vacío/genérico, ficheros
+ * citados que no están en el diff. Avisos (se acepta y se reportan): ámbito
+ * que no corresponde a ningún paquete del diff, titular largo, cobertura
+ * parcial de los ficheros con sustancia.
+ */
+export declare function validarPropuesta(propuesta: PropuestaCruda, trozos: TrozoDeFichero[]): {
+    errores: ErrorDePropuesta[];
+    avisos: Aviso[];
+};
+/**
+ * Mensaje determinista desde el diff, para cuando el modelo no da una
+ * propuesta válida. Solo dice cosas que están EN el diff: qué ficheros cambian
+ * y cuánto. No usa tipo convencional porque deducirlo sin semántica sería
+ * inventar.
+ */
+export declare function mensajeDeterminista(trozos: TrozoDeFichero[]): string;
+/**
+ * El bucle agéntico: propuesta → validación → recordatorio sintético → …
+ * hasta aceptar una propuesta o agotar `1 + rondas` intentos.
+ */
+export declare function generarMensajeAgentic(diff: string, deps: DependenciasAgenticas): Promise<PropuestaAgentic>;
+//# sourceMappingURL=agentic.d.ts.map

package/dist/core/commits/agentic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic.d.ts","sourceRoot":"","sources":["../../../src/core/commits/agentic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAiC,KAAK,cAAc,EAAqB,MAAM,WAAW,CAAC;AAElG,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,6FAWvB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAYrE,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAInD;AAED,+DAA+D;AAC/D,MAAM,WAAW,KAAK;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,sFAAsF;IACtF,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,eAAe,GAAG,QAAQ,CAAC;AACrE,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBACjB,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM;CAKhD;AAoCD,kDAAkD;AAClD,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,OAAO,GACX,IAAI,IAAI;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAIvE;AAED,8BAA8B;AAC9B,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAM/F;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,cAAc,EAAE,GACtB;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,CAsDlD;AA4CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CASpE;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2DhH"}