labre-mcp 0.1.0

package/dist/work-on-evolution/write/patent/cpc-taxonomy-cache.mjs

@@ -0,0 +1,319 @@
+// CPC Taxonomy Cache: lazy-loaded hierarchical CPC code cache backed by BigQuery.
+//
+// Provides three levels of CPC hierarchy discovery with titles from
+// patents-public-data.cpc.definition (authoritative CPC taxonomy, all sections A-H + Y):
+//   1. getSubclasses(classCode)   — "G06" → [{code:"G06F", cnt:8M, title:"ELECTRIC DIGITAL DATA PROCESSING"}, ...]
+//   2. getGroups(subclassCode)    — "G06F" → [{code:"G06F9/", cnt:939K, title:"Arrangements for program control"}, ...]
+//   3. getSubgroups(groupCode)    — "G06F9/" → [{code:"G06F9/455", cnt:64K, title:"Emulation; Virtualisation"}, ...]
+//
+// Each entry includes { code, cnt, title } — titles come from BigQuery JOIN with cpc.definition.
+//
+// Cache is populated lazily from BigQuery on first access, then stored:
+//   - In-memory Map for fast repeated lookups
+//   - On-disk JSON file for cross-session persistence
+//
+// getCpcTitle(code) resolves titles from the cache (no static file needed).
+//
+// TTL defaults to 30 days (CPC taxonomy changes infrequently).
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { toErrorMessage } from '../../../lib/errors.mjs';
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** Default TTL for cached entries: 30 days in milliseconds. */
+export const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** Default cache file path. */
+export const DEFAULT_CACHE_PATH = join(homedir(), '.wardley-assistant', 'cpc-cache.json');
+/** BigQuery tables. */
+const BQ_PUBLICATIONS = '`patents-public-data.patents.publications`';
+const BQ_CPC_DEF = '`patents-public-data.cpc.definition`';
+// ─── SQL Templates (with JOIN cpc.definition for titles) ────────────────────
+/**
+ * SQL: subclasses of a 3-char class code, with titles from cpc.definition.
+ * e.g., "G06" → [{code:"G06F", cnt:8780599, title:"ELECTRIC DIGITAL DATA PROCESSING"}, ...]
+ */
+const SQL_SUBCLASSES = `
+  SELECT sc.code, sc.cnt, IFNULL(def.titleFull, sc.code) AS title
+  FROM (
+    SELECT DISTINCT SUBSTR(cpc.code, 1, 4) AS code, COUNT(*) AS cnt
+    FROM ${BQ_PUBLICATIONS}, UNNEST(cpc) AS cpc
+    WHERE SUBSTR(cpc.code, 1, 3) = @parent_code AND cpc.first = TRUE
+    GROUP BY code
+  ) sc
+  LEFT JOIN ${BQ_CPC_DEF} def ON def.symbol = sc.code
+  ORDER BY sc.cnt DESC
+`;
+/**
+ * SQL: groups of a 4-char subclass code, with titles from cpc.definition.
+ * Groups in publications are like "G06F9/" but in cpc.definition they are "G06F9/00".
+ * JOIN uses CONCAT(code, '00') to match.
+ */
+const SQL_GROUPS = `
+  SELECT grp.code, grp.cnt, IFNULL(def.titleFull, grp.code) AS title
+  FROM (
+    SELECT DISTINCT REGEXP_EXTRACT(cpc.code, r"^([A-H][0-9]{2}[A-Z][0-9]+/)") AS code, COUNT(*) AS cnt
+    FROM ${BQ_PUBLICATIONS}, UNNEST(cpc) AS cpc
+    WHERE SUBSTR(cpc.code, 1, 4) = @parent_code AND cpc.first = TRUE
+    GROUP BY code
+    HAVING code IS NOT NULL
+  ) grp
+  LEFT JOIN ${BQ_CPC_DEF} def ON def.symbol = CONCAT(grp.code, '00')
+  ORDER BY grp.cnt DESC
+`;
+/**
+ * SQL: subgroups of a group prefix, with titles from cpc.definition.
+ * Top 50 by patent count.
+ */
+const SQL_SUBGROUPS = `
+  SELECT sg.code, sg.cnt, IFNULL(def.titleFull, sg.code) AS title
+  FROM (
+    SELECT DISTINCT cpc.code AS code, COUNT(*) AS cnt
+    FROM ${BQ_PUBLICATIONS}, UNNEST(cpc) AS cpc
+    WHERE STARTS_WITH(cpc.code, @parent_code) AND cpc.first = TRUE
+    GROUP BY code
+    ORDER BY cnt DESC
+    LIMIT 50
+  ) sg
+  LEFT JOIN ${BQ_CPC_DEF} def ON def.symbol = sg.code
+  ORDER BY sg.cnt DESC
+`;
+// ─── Cache entry shape ──────────────────────────────────────────────────────
+/**
+ * @typedef {Object} CpcEntry
+ * @property {string} code - CPC code
+ * @property {number} cnt - Patent count
+ * @property {string} title - Human-readable title from cpc.definition
+ */
+/**
+ * @typedef {Object} CacheEntry
+ * @property {CpcEntry[]} children - Child codes with patent counts and titles
+ * @property {number} fetchedAt - Timestamp when this entry was fetched
+ */
+// ─── CPC Title resolution from cache ────────────────────────────────────────
+/** @type {Map<string, string>} Global title store populated from cache entries. */
+const _titleStore = new Map();
+/**
+ * Get the human-readable title for a CPC code.
+ * Resolves from the in-memory title store (populated by cache lookups).
+ *
+ * Fallback chain:
+ *   1. Exact match in title store
+ *   2. Trimmed trailing zeros (G06F9/50 → G06F9/5)
+ *   3. Parent group (G06F9/455 → G06F9/)
+ *   4. The code itself
+ *
+ * @param {string} code - CPC code at any hierarchy level
+ * @returns {string}
+ */
+export function getCpcTitle(code) {
+    if (_titleStore.has(code))
+        return _titleStore.get(code);
+    // Try trimming trailing zeros (BigQuery: G06F9/50 → cpc.definition: G06F9/5)
+    if (code.includes('/')) {
+        const trimmed = code.replace(/0+$/, '');
+        if (_titleStore.has(trimmed))
+            return _titleStore.get(trimmed);
+    }
+    // Try parent group (G06F9/455 → G06F9/)
+    const slashIdx = code.indexOf('/');
+    if (slashIdx > 0) {
+        const group = code.substring(0, slashIdx + 1);
+        if (_titleStore.has(group))
+            return _titleStore.get(group);
+    }
+    return code;
+}
+/**
+ * Register a title in the global store.
+ * Called internally when cache entries are loaded, or externally
+ * by the strategy to register titles from progressive discovery.
+ * @param {string} code
+ * @param {string} title
+ */
+export function setCpcTitle(code, title) {
+    if (code && title && title !== code) {
+        _titleStore.set(code, title);
+    }
+}
+// ─── CpcTaxonomyCache class ────────────────────────────────────────────────
+export class CpcTaxonomyCache {
+    _client; // any: BigQuery client (lazy, no exposed types)
+    _queryOptions;
+    _cachePath;
+    _ttlMs;
+    _memory;
+    _diskLoaded;
+    constructor({ bigqueryClient, queryOptions, cachePath, ttlMs } = {}) {
+        this._client = bigqueryClient || null;
+        this._queryOptions = queryOptions || {};
+        this._cachePath = cachePath || DEFAULT_CACHE_PATH;
+        this._ttlMs = ttlMs ?? DEFAULT_TTL_MS;
+        /** @type {Map<string, CacheEntry>} */
+        this._memory = new Map();
+        this._diskLoaded = false;
+    }
+    /**
+     * Get subclasses of a CPC class (3-char code → 4-char codes with titles).
+     * @param {string} classCode - 3-char class code (e.g., "G06")
+     * @returns {Promise<CpcEntry[]>}
+     */
+    async getSubclasses(classCode) {
+        const key = classCode.toUpperCase();
+        return this._getOrFetch(key, SQL_SUBCLASSES);
+    }
+    /**
+     * Get groups of a CPC subclass (4-char code → group prefixes with titles).
+     * @param {string} subclassCode - 4-char subclass code (e.g., "G06F")
+     * @returns {Promise<CpcEntry[]>}
+     */
+    async getGroups(subclassCode) {
+        const key = subclassCode.toUpperCase();
+        return this._getOrFetch(key, SQL_GROUPS);
+    }
+    /**
+     * Get subgroups of a CPC group (group prefix → full codes with titles).
+     * @param {string} groupCode - Group prefix (e.g., "G06F9/")
+     * @returns {Promise<CpcEntry[]>}
+     */
+    async getSubgroups(groupCode) {
+        const key = groupCode.toUpperCase();
+        return this._getOrFetch(key, SQL_SUBGROUPS);
+    }
+    /**
+     * Get cached children or fetch from BigQuery.
+     * Registers titles in the global store on load.
+     * @private
+     */
+    async _getOrFetch(parentCode, sql) {
+        // Check memory cache first
+        const cached = this._memory.get(parentCode);
+        if (cached && (Date.now() - cached.fetchedAt) < this._ttlMs) {
+            // Re-register titles (may have been lost if title store was cleared)
+            for (const child of cached.children)
+                setCpcTitle(child.code, child.title ?? child.code);
+            return cached.children;
+        }
+        // Load disk cache on first access
+        if (!this._diskLoaded) {
+            await this._loadFromDisk();
+            this._diskLoaded = true;
+            const diskCached = this._memory.get(parentCode);
+            if (diskCached && (Date.now() - diskCached.fetchedAt) < this._ttlMs) {
+                for (const child of diskCached.children)
+                    setCpcTitle(child.code, child.title ?? child.code);
+                return diskCached.children;
+            }
+        }
+        // Fetch from BigQuery
+        const children = await this._fetchFromBigQuery(parentCode, sql);
+        // Register titles
+        for (const child of children)
+            setCpcTitle(child.code, child.title ?? child.code);
+        // Store in memory + persist to disk
+        const entry = { children, fetchedAt: Date.now() };
+        this._memory.set(parentCode, entry);
+        await this._saveToDisk();
+        return children;
+    }
+    /**
+     * Fetch CPC hierarchy data from BigQuery (with titles from cpc.definition).
+     * @private
+     */
+    async _fetchFromBigQuery(parentCode, sql) {
+        if (!this._client)
+            return [];
+        try {
+            const [rows] = await this._client.query({
+                query: sql,
+                params: { parent_code: parentCode },
+                ...this._queryOptions,
+            });
+            return rows
+                .filter((r) => r.code)
+                .map((r) => ({
+                code: r.code,
+                cnt: Number(r.cnt) || 0,
+                title: r.title || r.code,
+            }));
+        }
+        catch (err) {
+            if (typeof process !== 'undefined' && process.env.WARDLEY_VERBOSE) {
+                console.error(`CpcTaxonomyCache: BigQuery fetch failed for "${parentCode}":`, toErrorMessage(err));
+            }
+            return [];
+        }
+    }
+    /** @private */
+    async _loadFromDisk() {
+        try {
+            const raw = await readFile(this._cachePath, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data && typeof data === 'object') {
+                for (const [key, entry] of Object.entries(data)) {
+                    if (entry?.children && entry?.fetchedAt) {
+                        this._memory.set(key, entry);
+                        // Register titles from disk cache
+                        for (const child of entry.children) {
+                            if (child.title)
+                                setCpcTitle(child.code, child.title ?? child.code);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // File doesn't exist or is corrupt — start fresh
+        }
+    }
+    /** @private */
+    async _saveToDisk() {
+        try {
+            const data = Object.fromEntries(this._memory.entries());
+            await mkdir(dirname(this._cachePath), { recursive: true });
+            await writeFile(this._cachePath, JSON.stringify(data, null, 2), 'utf-8');
+        }
+        catch {
+            // Disk write failed — non-critical
+        }
+    }
+    /** Clear all cached entries (memory + disk + title store). */
+    async clear() {
+        this._memory.clear();
+        _titleStore.clear();
+        try {
+            await writeFile(this._cachePath, '{}', 'utf-8');
+        }
+        catch { /* ignore */ }
+    }
+    /** Get the number of cached entries. */
+    get size() {
+        return this._memory.size;
+    }
+}
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create a CpcTaxonomyCache with BigQuery client from environment.
+ * @param {Object} [options]
+ * @returns {Promise<CpcTaxonomyCache>}
+ */
+export async function createTaxonomyCache(options = {}) {
+    try {
+        const { resolveConfig, getClient, defaultQueryOptions } = await import('../../../lib/patent/bigquery-client.mjs');
+        const config = resolveConfig();
+        const client = await getClient(config);
+        const queryOptions = defaultQueryOptions(config);
+        return new CpcTaxonomyCache({
+            bigqueryClient: client,
+            queryOptions,
+            cachePath: options.cachePath,
+            ttlMs: options.ttlMs,
+        });
+    }
+    catch {
+        return new CpcTaxonomyCache({
+            cachePath: options.cachePath,
+            ttlMs: options.ttlMs,
+        });
+    }
+}
+//# sourceMappingURL=cpc-taxonomy-cache.mjs.map

package/dist/work-on-evolution/write/patent/cpc-taxonomy-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpc-taxonomy-cache.mjs","sourceRoot":"","sources":["../../../../src/work-on-evolution/write/patent/cpc-taxonomy-cache.mts"],"names":[],"mappings":"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"}

package/dist/work-on-evolution/write/pipeline/pipeline-enriched.d.mts

@@ -0,0 +1,175 @@
+/**
+ * @typedef {Object} CapabilityPivotResult
+ * @property {string}  capabilityName   - The abstract capability name (e.g. "Manage customer relationships")
+ * @property {string}  nature           - Capability nature (activity/practice/data/knowledge)
+ * @property {number}  evolution        - Evolution score [0, 1]
+ * @property {number}  confidence       - Confidence in the evolution score [0, 1]
+ * @property {string}  method           - Strategy method that produced the score
+ * @property {Object}  evaluations      - Full evaluation results from all strategies
+ * @property {Object}  wardleyType      - Wardley component type metadata
+ * @property {Object}  routing          - Routing metadata from the evaluation
+ */
+/**
+ * Evaluate the capability pivot — the first step of the enriched pipeline.
+ *
+ * Given the standard estimateEvolution result (which already ran capability
+ * strategies), this function extracts the capability evolution score and
+ * wraps it in a structured CapabilityPivotResult.
+ *
+ * If the input was originally a solution (e.g. "Kubernetes"), the capability
+ * was already identified via identifyCapability (e.g. "Orchestrate containers").
+ * In that case, this function re-evaluates the capability directly as a
+ * generic capability through the capability strategies.
+ *
+ * If the input was already a capability (e.g. "container orchestration"),
+ * the standard evaluation results are used directly — no re-evaluation needed.
+ *
+ * @param {Object} standardResult - The standard estimateEvolution oneshot result
+ * @param {Object} component      - The original component input with identified capability
+ * @param {Object} options
+ * @param {Function} options.evaluateCapabilityFn - Function to evaluate a capability (accepts {name, description, strategy})
+ * @returns {Promise<CapabilityPivotResult>}
+ */
+export declare function evaluateCapabilityPivot(standardResult: any, component: any, options?: any): Promise<any>;
+/**
+ * Clamp the capability evolution between the SotA (upper bound) and legacy
+ * (lower bound) solution evolutions.
+ *
+ * In Wardley Mapping, the abstract capability should sit between its most
+ * evolved implementation (SotA) and its least evolved one (legacy).
+ * If only one bound is available, only that bound is enforced.
+ * If neither bound is available, the evolution is returned unchanged.
+ *
+ * @param {number} capabilityEvolution - The raw capability evolution score
+ * @param {number|null} sotaEvolution  - SotA solution evolution (upper bound), or null
+ * @param {number|null} legacyEvolution - Legacy solution evolution (lower bound), or null
+ * @returns {{ evolution: number, clamped: boolean, originalEvolution: number }}
+ */
+export declare function clampCapabilityEvolution(capabilityEvolution: number, sotaEvolution: number, legacyEvolution: number): {
+    evolution: number;
+    clamped: boolean;
+    originalEvolution: number;
+};
+/**
+ * Generate valid onlinewardleymaps.com OWM syntax for a 3-component pipeline.
+ *
+ * The output format is:
+ *
+ *   component "Capability Label" [visibility, pipeline_min] label [-53, -17]
+ *   pipeline "Capability Label"
+ *   {
+ *       component "Legacy Solution" [evolution] label [-61, -23]
+ *       component "Input Component" [evolution] label [-31, -3]
+ *       component "SotA Solution" [evolution] label [-4, 30]
+ *   }
+ *
+ * The capability is the outer pipeline container. Its evolution coordinate
+ * is the pipeline minimum (leftmost inner component evolution minus a small
+ * margin). The pipeline range spans from legacy (lowest) to SotA (highest).
+ *
+ * Inner components are ordered left-to-right by evolution (legacy → SotA).
+ *
+ * @param {Object} params
+ * @param {string} params.capabilityLabel  - Display label for the capability pipeline
+ * @param {number} params.capabilityEvolution - Evolution score of the capability pivot
+ * @param {string} params.componentName    - Original input component name
+ * @param {number} params.componentEvolution - Evolution of the input component (may equal SotA or legacy)
+ * @param {string} [params.sotaName]       - Name of the state-of-the-art solution
+ * @param {number} [params.sotaEvolution]  - Evolution of the SotA solution
+ * @param {string} [params.legacyName]     - Name of the legacy solution
+ * @param {number} [params.legacyEvolution] - Evolution of the legacy solution
+ * @param {number} [params.visibility]     - Y-axis visibility (default: 0.51)
+ * @param {string} [params.nature]         - Component nature (activity/practice/data/knowledge) — metadata only
+ * @returns {string} Valid OWM syntax string
+ */
+export declare function generateOwmSyntax(params: any): string;
+/**
+ * @typedef {Object} DiscoveredSolution
+ * @property {string} name        - Solution name (e.g. "Kubernetes", "Docker Swarm")
+ * @property {string} description - Brief description of the solution
+ * @property {'sota'|'legacy'} role - Whether this is the SotA or legacy solution
+ */
+/**
+ * @typedef {Object} SolutionDiscoveryResult
+ * @property {DiscoveredSolution|null} sota   - State-of-the-art / cutting-edge solution
+ * @property {DiscoveredSolution|null} legacy - Legacy / established / older solution
+ * @property {string} capabilityUsed          - The capability name used for discovery
+ * @property {number} confidence              - Confidence in the discovery (0–1)
+ */
+/**
+ * LLM prompt template for discovering representative solutions for a capability.
+ *
+ * Given a generic capability, the LLM identifies:
+ *   - A state-of-the-art (SotA) solution: the most modern, cutting-edge implementation
+ *   - A legacy solution: an older, well-established but less evolved implementation
+ *
+ * Both solutions must be NAMED (proper nouns with specific identity) — not generic
+ * descriptions. They should represent opposite ends of the evolution spectrum for
+ * the same underlying capability.
+ */
+/**
+ * Parse the LLM response for solution discovery into a structured result.
+ *
+ * Expected format:
+ *   sota_name=GitHub Actions
+ *   sota_description=Modern cloud-native CI/CD platform integrated with GitHub
+ *   legacy_name=Jenkins
+ *   legacy_description=Established open-source automation server, widely used but complex to maintain
+ *   confidence=0.88
+ *   reasoning=GitHub Actions represents modern SotA while Jenkins is the canonical legacy CI/CD tool
+ *
+ * @param {string} text           - Raw LLM response
+ * @param {string} capabilityName - Capability used for context in error messages
+ * @returns {SolutionDiscoveryResult}
+ */
+export declare function parseSolutionDiscoveryResponse(text: string, capabilityName: string): any;
+/**
+ * Discover two representative solutions (SotA + legacy) for a given capability
+ * using the Tier 2 LLM.
+ *
+ * This is Step 2 of the enriched pipeline: after the capability pivot is
+ * evaluated, we identify which named solutions sit at opposite ends of the
+ * evolution axis for that capability.
+ *
+ * The discovered solutions are NOT yet evaluated — they are returned as
+ * structured metadata for Step 3 (solution evaluation) to consume.
+ *
+ * @param {string} capabilityName - The generic capability name (e.g. "container orchestration")
+ * @param {Object} options
+ * @param {function(string): Promise<string>} options.llmCall - LLM call function
+ * @param {string}   [options.description]    - Additional context about the capability
+ * @param {string}   [options.excludeName]    - Original component name to exclude from results
+ * @returns {Promise<SolutionDiscoveryResult>}
+ */
+export declare function discoverPipelineSolutions(capabilityName: string, options?: any): Promise<any>;
+/**
+ * Evaluate a single discovered solution (SotA or legacy) via the solution strategies
+ * (12 Wardley properties). This reuses the same evaluation path as normal solution
+ * evaluations through dispatchSolutionStrategies().
+ *
+ * @param {DiscoveredSolution} solution - The discovered solution (name, description, role)
+ * @param {Object} options
+ * @param {Function} options.llmCall - LLM call function
+ * @returns {Promise<{ evolution: number|null, confidence: number, method: string, evaluations: Object }>}
+ */
+export declare function evaluateDiscoveredSolution(solution: any, options?: any): Promise<any>;
+/**
+ * Run the full enriched pipeline: capability pivot + SotA solution + legacy solution.
+ *
+ * Implements:
+ *   - Step 1: Capability pivot evaluation (always first)
+ *   - Step 2: Solution discovery — identifies SotA and legacy solutions via LLM
+ *   - Step 3: Solution evaluation — evaluates SotA and legacy via 12 Wardley property strategies
+ *
+ * OWM syntax is generated when all 3 components are available, or partially
+ * when at least the capability pivot is evaluated.
+ *
+ * @param {Object} standardResult - The standard estimateEvolution result
+ * @param {Object} component      - The original component with identified capability
+ * @param {Object} options
+ * @param {Function} options.evaluateCapabilityFn - Evaluator function for capability
+ * @param {Function} [options.llmCall]            - LLM call function for solution discovery
+ * @returns {Promise<Object>} Pipeline result with capability pivot, OWM output, and discovered solutions
+ */
+export declare function runEnrichedPipeline(standardResult: any, component: any, options?: any): Promise<any>;
+//# sourceMappingURL=pipeline-enriched.d.mts.map

package/dist/work-on-evolution/write/pipeline/pipeline-enriched.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-enriched.d.mts","sourceRoot":"","sources":["../../../../src/work-on-evolution/write/pipeline/pipeline-enriched.mts"],"names":[],"mappings":"AAuBA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAwDlH;AA8BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,mBAAmB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM;;;;EA2BnH;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,CAkFrD;AAID;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAGH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CA0CxF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAyCvG;AAID;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAuC/F;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CA0F9G"}