@yuaone/core 0.9.7 → 0.9.9

package/dist/meta-learning-engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module meta-learning-engine
+ * @description Orchestrator that combines MetaLearningCollector + StrategyLearner
+ * data to produce sophisticated `agent:policy_recommendation` events.
+ *
+ * ADVISORY ONLY — never writes to policy.json.
+ * All output is proposals only, not commands.
+ *
+ * Storage: ~/.yuan/strategy/meta-learning-reports.json — last 10 reports.
+ * Atomic writes (.tmp → renameSync).
+ */
+import { EventEmitter } from "events";
+import { MetaLearningCollector } from "./meta-learning-collector.js";
+import { StrategyLearner } from "./strategy-learner.js";
+export interface PolicyRecommendationDetail {
+    id: string;
+    type: "governor_tuning" | "playbook_preference" | "tool_ordering" | "iteration_budget";
+    description: string;
+    rationale: string;
+    suggestedValue?: unknown;
+    confidence: number;
+    supportingDataPoints: number;
+    generatedAt: string;
+}
+export interface MetaLearningReport {
+    generatedAt: string;
+    totalTasksAnalyzed: number;
+    recommendations: PolicyRecommendationDetail[];
+    topPlaybooks: Array<{
+        playbookId: string;
+        taskType: string;
+        score: number;
+    }>;
+    worstPerformingTaskTypes: string[];
+    avgIterationsPerTaskType: Record<string, number>;
+}
+export interface MetaLearningEngineConfig {
+    collector?: MetaLearningCollector;
+    strategyLearner?: StrategyLearner;
+    storageDir?: string;
+    minDataPoints?: number;
+}
+export declare class MetaLearningEngine extends EventEmitter {
+    private readonly collector;
+    private readonly strategyLearner;
+    private readonly storageFile;
+    private readonly storageDir;
+    private readonly minDataPoints;
+    private lastReport;
+    constructor(config?: MetaLearningEngineConfig);
+    /**
+     * Run analysis and produce recommendations.
+     * Emits `agent:policy_recommendation` event.
+     * ADVISORY ONLY — does not write to policy.json.
+     */
+    analyze(): Promise<MetaLearningReport>;
+    /** Get last report without re-analyzing. */
+    getLastReport(): MetaLearningReport | null;
+    private _saveReport;
+}
+//# sourceMappingURL=meta-learning-engine.d.ts.map

package/dist/meta-learning-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-learning-engine.d.ts","sourceRoot":"","sources":["../src/meta-learning-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIxD,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,eAAe,GAAG,kBAAkB,CAAC;IACvF,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,0BAA0B,EAAE,CAAC;IAC9C,YAAY,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7E,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkBD,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,UAAU,CAAmC;gBAEzC,MAAM,GAAE,wBAA6B;IAWjD;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAsL5C,4CAA4C;IAC5C,aAAa,IAAI,kBAAkB,GAAG,IAAI;IAM1C,OAAO,CAAC,WAAW;CA6BpB"}

package/dist/meta-learning-engine.js

@@ -0,0 +1,250 @@
+/**
+ * @module meta-learning-engine
+ * @description Orchestrator that combines MetaLearningCollector + StrategyLearner
+ * data to produce sophisticated `agent:policy_recommendation` events.
+ *
+ * ADVISORY ONLY — never writes to policy.json.
+ * All output is proposals only, not commands.
+ *
+ * Storage: ~/.yuan/strategy/meta-learning-reports.json — last 10 reports.
+ * Atomic writes (.tmp → renameSync).
+ */
+import { EventEmitter } from "events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { MetaLearningCollector } from "./meta-learning-collector.js";
+import { StrategyLearner } from "./strategy-learner.js";
+// ─── Helpers ───
+function stddev(values) {
+    if (values.length < 2)
+        return 0;
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    return Math.sqrt(variance);
+}
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+// ─── Class ───
+export class MetaLearningEngine extends EventEmitter {
+    collector;
+    strategyLearner;
+    storageFile;
+    storageDir;
+    minDataPoints;
+    lastReport = null;
+    constructor(config = {}) {
+        super();
+        this.collector = config.collector ?? new MetaLearningCollector();
+        this.strategyLearner = config.strategyLearner ?? new StrategyLearner();
+        this.storageDir = config.storageDir ?? join(homedir(), ".yuan", "strategy");
+        this.storageFile = join(this.storageDir, "meta-learning-reports.json");
+        this.minDataPoints = config.minDataPoints ?? 10;
+    }
+    // ─── Public API ───
+    /**
+     * Run analysis and produce recommendations.
+     * Emits `agent:policy_recommendation` event.
+     * ADVISORY ONLY — does not write to policy.json.
+     */
+    async analyze() {
+        const now = new Date().toISOString();
+        const reportId = randomUUID();
+        const allStats = this.collector.getStats();
+        // Collect unique task types
+        const taskTypes = [...new Set(allStats.map((s) => s.taskType))];
+        // Compute avgIterations per taskType
+        const avgIterationsPerTaskType = {};
+        const iterationsByTaskType = {};
+        for (const stat of allStats) {
+            const arr = iterationsByTaskType[stat.taskType] ?? [];
+            arr.push(stat.iterationsUsed);
+            iterationsByTaskType[stat.taskType] = arr;
+        }
+        for (const taskType of taskTypes) {
+            avgIterationsPerTaskType[taskType] = mean(iterationsByTaskType[taskType] ?? []);
+        }
+        // Collect base report from collector (for taskTypeStats / success rates)
+        const collectorReport = this.collector.generateReport();
+        // Worst performing task types: success rate < 50%
+        const worstPerformingTaskTypes = [];
+        for (const [taskType, stats] of Object.entries(collectorReport.taskTypeStats)) {
+            const successRate = stats.total > 0 ? stats.success / stats.total : 0;
+            if (successRate < 0.5 && stats.total >= this.minDataPoints) {
+                worstPerformingTaskTypes.push(taskType);
+            }
+        }
+        const recommendations = [];
+        // ── 1. Governor Tuning Recommendations ──
+        for (const taskType of taskTypes) {
+            const iterations = iterationsByTaskType[taskType] ?? [];
+            const count = iterations.length;
+            if (count < this.minDataPoints)
+                continue;
+            const avg = avgIterationsPerTaskType[taskType];
+            if (avg > 15) {
+                recommendations.push({
+                    id: randomUUID(),
+                    type: "governor_tuning",
+                    description: `Reduce maxIterations for taskType "${taskType}"`,
+                    rationale: `Average iterations (${avg.toFixed(1)}) exceeds 15 — reducing to 12 may cut cost without losing quality.`,
+                    suggestedValue: { maxIterations: 12, taskType },
+                    confidence: Math.min(0.9, (avg - 15) / 10 + 0.5),
+                    supportingDataPoints: count,
+                    generatedAt: now,
+                });
+            }
+            else if (avg < 5) {
+                recommendations.push({
+                    id: randomUUID(),
+                    type: "governor_tuning",
+                    description: `Increase maxIterations for taskType "${taskType}" to allow more exploration`,
+                    rationale: `Average iterations (${avg.toFixed(1)}) is below 5 — the agent may be under-exploring. Increasing budget may improve quality.`,
+                    suggestedValue: { maxIterations: 20, taskType },
+                    confidence: Math.min(0.8, (5 - avg) / 5 + 0.4),
+                    supportingDataPoints: count,
+                    generatedAt: now,
+                });
+            }
+        }
+        // ── 2. Playbook Preference Recommendations ──
+        const topPlaybooks = [];
+        for (const taskType of taskTypes) {
+            const rankings = this.strategyLearner.rankPlaybooks(taskType);
+            if (rankings.length === 0)
+                continue;
+            const top = rankings[0];
+            topPlaybooks.push({ playbookId: top.playbookId, taskType: top.taskType, score: top.score });
+            // Get the metric for confidence check
+            const metric = this.strategyLearner.getMetric(top.playbookId);
+            const confidence = metric?.confidence ?? 0;
+            const totalRuns = (metric?.successCount ?? 0) + (metric?.failureCount ?? 0);
+            if (confidence > 0.7 && totalRuns >= this.minDataPoints) {
+                recommendations.push({
+                    id: randomUUID(),
+                    type: "playbook_preference",
+                    description: `Prefer playbook "${top.playbookId}" for taskType "${taskType}"`,
+                    rationale: `Playbook "${top.playbookId}" has confidence ${(confidence * 100).toFixed(1)}% over ${totalRuns} runs (score: ${top.score.toFixed(2)}).`,
+                    suggestedValue: { playbookId: top.playbookId, taskType },
+                    confidence,
+                    supportingDataPoints: totalRuns,
+                    generatedAt: now,
+                });
+            }
+        }
+        // ── 3. Tool Ordering Recommendations ──
+        for (const taskType of taskTypes) {
+            const successfulStats = allStats.filter((s) => s.taskType === taskType && s.success);
+            const totalSuccessful = successfulStats.length;
+            if (totalSuccessful < this.minDataPoints)
+                continue;
+            // Count tool appearances in successful runs
+            const toolCounts = new Map();
+            for (const stat of successfulStats) {
+                const seen = new Set();
+                for (const tool of stat.toolSequence) {
+                    if (!seen.has(tool)) {
+                        toolCounts.set(tool, (toolCounts.get(tool) ?? 0) + 1);
+                        seen.add(tool);
+                    }
+                }
+            }
+            for (const [tool, count] of toolCounts.entries()) {
+                const rate = count / totalSuccessful;
+                if (rate > 0.8) {
+                    recommendations.push({
+                        id: randomUUID(),
+                        type: "tool_ordering",
+                        description: `Always use tool "${tool}" early for taskType "${taskType}"`,
+                        rationale: `Tool "${tool}" appears in ${(rate * 100).toFixed(1)}% of successful runs for "${taskType}" (${count}/${totalSuccessful}). Using it early may improve outcomes.`,
+                        suggestedValue: { tool, taskType, position: "early" },
+                        confidence: Math.min(0.95, rate),
+                        supportingDataPoints: totalSuccessful,
+                        generatedAt: now,
+                    });
+                }
+            }
+        }
+        // ── 4. Iteration Budget Recommendations ──
+        for (const taskType of taskTypes) {
+            const iterations = iterationsByTaskType[taskType] ?? [];
+            if (iterations.length < this.minDataPoints)
+                continue;
+            const sd = stddev(iterations);
+            if (sd > 8) {
+                const avg = avgIterationsPerTaskType[taskType];
+                recommendations.push({
+                    id: randomUUID(),
+                    type: "iteration_budget",
+                    description: `Use adaptive iteration budget for taskType "${taskType}"`,
+                    rationale: `High variance in iteration counts (stddev: ${sd.toFixed(1)}, mean: ${avg.toFixed(1)}) across ${iterations.length} runs suggests a fixed budget is suboptimal. An adaptive budget (e.g. range ${Math.max(1, Math.round(avg - sd))}–${Math.round(avg + sd)}) may reduce wasted compute.`,
+                    suggestedValue: {
+                        taskType,
+                        minIterations: Math.max(1, Math.round(avg - sd)),
+                        maxIterations: Math.round(avg + sd),
+                        adaptive: true,
+                    },
+                    confidence: Math.min(0.85, sd / 20 + 0.4),
+                    supportingDataPoints: iterations.length,
+                    generatedAt: now,
+                });
+            }
+        }
+        const report = {
+            generatedAt: now,
+            totalTasksAnalyzed: allStats.length,
+            recommendations,
+            topPlaybooks,
+            worstPerformingTaskTypes,
+            avgIterationsPerTaskType,
+        };
+        this.lastReport = report;
+        this._saveReport(report);
+        // Emit advisory event — PROPOSALS ONLY, not commands
+        this.emit("event", {
+            kind: "agent:policy_recommendation",
+            recommendations,
+            reportId,
+            timestamp: Date.now(),
+        });
+        return report;
+    }
+    /** Get last report without re-analyzing. */
+    getLastReport() {
+        return this.lastReport;
+    }
+    // ─── Internal ───
+    _saveReport(report) {
+        const tmpFile = `${this.storageFile}.tmp`;
+        try {
+            if (!existsSync(this.storageDir)) {
+                mkdirSync(this.storageDir, { recursive: true });
+            }
+            // Load existing reports (keep last 10)
+            let existing = [];
+            if (existsSync(this.storageFile)) {
+                try {
+                    const raw = readFileSync(this.storageFile, "utf-8");
+                    existing = JSON.parse(raw);
+                }
+                catch {
+                    existing = [];
+                }
+            }
+            existing.push(report);
+            if (existing.length > 10) {
+                existing = existing.slice(existing.length - 10);
+            }
+            writeFileSync(tmpFile, JSON.stringify(existing, null, 2), "utf-8");
+            renameSync(tmpFile, this.storageFile);
+        }
+        catch {
+            // Non-fatal: storage failures should not crash the agent loop
+        }
+    }
+}
+//# sourceMappingURL=meta-learning-engine.js.map

package/dist/meta-learning-engine.js.map

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

package/dist/overhead-governor.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module overhead-governor
+ * @description 서브시스템 실행 정책 중앙 관리자.
+ *
+ * "Main loop is sacred. All secondary intelligence must earn the right to block."
+ *
+ * 모든 optional 서브시스템(AutoTSC, Debate, SelfReflection, QAPipeline 등)은
+ * 이 Governor의 결정 없이 blocking으로 실행될 수 없다.
+ *
+ * 모드:
+ *   OFF      — 실행 안 함
+ *   SHADOW   — 실제 실행 없이 "실행됐을 것" 로그만 남김
+ *   BLOCKING — 실제 blocking 실행
+ */
+export type GuardMode = "OFF" | "SHADOW" | "BLOCKING";
+export type TaskPhase = "explore" | "implement" | "verify" | "finalize";
+/**
+ * Governor가 결정할 때 사용하는 런타임 시그널.
+ */
+export interface TriggerContext {
+    /** 이번 iteration에서 변경된 파일 목록 */
+    changedFiles: string[];
+    /** 마지막 verify 이후 write 횟수 */
+    writeCountSinceVerify: number;
+    /** 누적 tool 에러 횟수 */
+    failureCount: number;
+    /** 반복되는 에러 시그니처 (동일 에러 문자열) */
+    repeatedErrorSignature?: string;
+    /** planner 신뢰도 (0~1) */
+    plannerConfidence?: number;
+    /** 현재 컨텍스트 사용률 (0~1) */
+    contextUsageRatio: number;
+    /** 위험한 write (핵심 파일: tsconfig, package.json, public API 등) */
+    riskyWrite: boolean;
+    /** 현재 task phase */
+    taskPhase: TaskPhase;
+    /** 현재 iteration index */
+    iteration: number;
+    /** 이번 iteration에서 이미 verify가 실행됐는지 */
+    verifyRanThisIteration: boolean;
+    /** 이번 iteration에서 이미 summarize가 실행됐는지 */
+    summarizeRanThisIteration: boolean;
+    /** 이번 iteration에서 llmFixer가 실행된 횟수 */
+    llmFixerRunCount: number;
+}
+/**
+ * 각 서브시스템별 사용자 설정 (feature flags).
+ * 기본값은 GPT 권장 정책.
+ */
+export interface OverheadGovernorConfig {
+    autoTsc?: GuardMode;
+    debate?: GuardMode;
+    deepVerify?: GuardMode;
+    quickVerify?: GuardMode;
+    qaPipeline?: GuardMode;
+    llmFixer?: GuardMode;
+    summarize?: GuardMode;
+    /** ResearchAgent — web/repo/docs search orchestration */
+    research?: GuardMode;
+    /** PatchTournamentExecutor — multi-candidate patch generation + selection */
+    tournament?: GuardMode;
+    /** IncidentDebugMode — log/trace/commit failure analysis */
+    debugMode?: GuardMode;
+}
+export declare class OverheadGovernor {
+    private readonly cfg;
+    /** Shadow mode 로그 콜백 (TUI로 보내거나 stdout) */
+    private readonly onShadow?;
+    constructor(config?: OverheadGovernorConfig, onShadow?: (subsystem: string, reason: string) => void);
+    /** Auto-TSC: TS 타입 체크 자동 실행 여부 */
+    shouldRunAutoTsc(ctx: TriggerContext): GuardMode;
+    /** DebateOrchestrator: 복잡한 태스크에서 multi-agent debate */
+    shouldRunDebate(ctx: TriggerContext): GuardMode;
+    /** SelfReflection.deepVerify: 완료 시점 심층 코드 검증 */
+    shouldRunDeepVerify(ctx: TriggerContext): GuardMode;
+    /** SelfReflection.quickVerify: 주기적 경량 검증 */
+    shouldRunQuickVerify(ctx: TriggerContext): GuardMode;
+    /** QAPipeline: write 후 코드 품질 검사 */
+    shouldRunQaPipeline(ctx: TriggerContext): GuardMode;
+    /** SelfDebugLoop.llmFixer: LLM 기반 에러 자동 수정 */
+    shouldRunLlmFixer(ctx: TriggerContext): GuardMode;
+    /** ContextBudgetManager.summarize: 컨텍스트 요약으로 공간 확보 */
+    shouldRunSummarize(ctx: TriggerContext): GuardMode;
+    /** ResearchAgent: only run when goal requires external information */
+    shouldRunResearch(ctx: TriggerContext): GuardMode;
+    /** PatchTournamentExecutor: only run for high-risk writes in finalize */
+    shouldRunTournament(ctx: TriggerContext): GuardMode;
+    /** IncidentDebugMode: only run when repeated errors detected */
+    shouldRunDebugMode(ctx: TriggerContext): GuardMode;
+    private _shadow;
+    /**
+     * 현재 설정 반환 (디버그용).
+     */
+    getConfig(): Required<OverheadGovernorConfig>;
+    /**
+     * Load overrides from a JSON file (e.g. ~/.yuan/policy.json).
+     * Only keys that exist in OverheadGovernorConfig are applied.
+     * Unknown keys are silently ignored — safe to call with arbitrary files.
+     *
+     * Example .yuan/policy.json:
+     *   { "research": "BLOCKING", "tournament": "BLOCKING", "debugMode": "BLOCKING" }
+     */
+    static loadFromFile(filePath: string): OverheadGovernorConfig;
+}
+//# sourceMappingURL=overhead-governor.d.ts.map

package/dist/overhead-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overhead-governor.d.ts","sourceRoot":"","sources":["../src/overhead-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,sBAAsB,EAAE,OAAO,CAAC;IAChC,yCAAyC;IACzC,yBAAyB,EAAE,OAAO,CAAC;IACnC,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAkBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmC;IACvD,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA8C;gBAGtE,MAAM,CAAC,EAAE,sBAAsB,EAC/B,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI;IAQxD,kCAAkC;IAClC,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IA6BhD,uDAAuD;IACvD,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAmB/C,gDAAgD;IAChD,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAoBnD,4CAA4C;IAC5C,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAoBpD,mCAAmC;IACnC,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAanD,8CAA8C;IAC9C,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAgBjD,sDAAsD;IACtD,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAqBlD,sEAAsE;IACtE,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAWjD,yEAAyE;IACzE,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAWnD,gEAAgE;IAChE,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS;IAelD,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,sBAAsB,CAAC;IAI7C;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB;CAoB9D"}