agentic-qe 3.6.18 → 3.7.0

package/v3/dist/learning/dream/rvcow-branch-manager.d.ts

@@ -0,0 +1,170 @@
+/**
+ * RVCOWBranchManager - RVCOW Branching for Reversible Dream Cycles
+ * ADR-069: RVCOW Dream Cycle Branching
+ *
+ * Implements Copy-on-Write branching semantics using SQLite savepoints.
+ * Each dream cycle operates on an isolated branch (savepoint). After the
+ * dream completes, the branch is validated against quality thresholds.
+ * If validation passes, the savepoint is released (changes persist).
+ * If validation fails, the savepoint is rolled back (changes discarded).
+ *
+ * This gives us the same semantics as native RVCOW:
+ *   - createBranch  -> SAVEPOINT
+ *   - mergeBranch   -> RELEASE SAVEPOINT
+ *   - discardBranch -> ROLLBACK TO SAVEPOINT
+ *
+ * @module v3/learning/dream/rvcow-branch-manager
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+/**
+ * Represents an active RVCOW branch backed by a SQLite savepoint.
+ */
+export interface Branch {
+    /** Unique branch name (also the savepoint name) */
+    name: string;
+    /** When the branch was created */
+    createdAt: Date;
+    /** Current status */
+    status: 'active' | 'merged' | 'discarded';
+    /** Snapshot of pattern metrics at branch creation time */
+    baselineSnapshot: QualityBaseline;
+}
+/**
+ * Quality baseline captured before a dream cycle.
+ * Used to validate that the dream did not degrade knowledge quality.
+ */
+export interface QualityBaseline {
+    /** Total number of patterns */
+    patternCount: number;
+    /** Average confidence across all patterns */
+    avgConfidence: number;
+    /** Number of high-confidence patterns (confidence >= 0.8) */
+    highConfidenceCount: number;
+    /** Timestamp of baseline capture */
+    capturedAt: Date;
+}
+/**
+ * Result of validating a branch against a quality baseline.
+ */
+export interface ValidationResult {
+    /** Whether the branch passed validation */
+    passed: boolean;
+    /** Human-readable reason */
+    reason: string;
+    /** Delta in pattern count (positive = patterns added) */
+    patternCountDelta: number;
+    /** Delta in average confidence */
+    avgConfidenceDelta: number;
+    /** Number of high-confidence patterns that were lost */
+    highConfidenceLost: number;
+    /** Post-dream metrics for comparison */
+    postDreamMetrics: QualityBaseline;
+}
+/**
+ * Thresholds for dream branch validation.
+ */
+export interface ValidationThresholds {
+    /** Maximum allowed decrease in pattern count (as fraction). Default: 0.05 (5%) */
+    maxPatternCountDrop: number;
+    /** Maximum allowed decrease in average confidence. Default: 0.02 */
+    maxAvgConfidenceDrop: number;
+    /** Maximum fraction of high-confidence patterns that can be lost. Default: 0.05 (5%) */
+    maxHighConfidenceLoss: number;
+}
+/** Default validation thresholds */
+export declare const DEFAULT_VALIDATION_THRESHOLDS: ValidationThresholds;
+/**
+ * Events emitted by the branch manager.
+ */
+export type BranchEvent = 'dream:branch_created' | 'dream:branch_merged' | 'dream:branch_discarded';
+export type BranchEventListener = (event: BranchEvent, branch: Branch, detail?: ValidationResult) => void;
+/**
+ * Manages RVCOW branches for dream cycles using SQLite savepoints.
+ *
+ * Usage:
+ * ```typescript
+ * const manager = new RVCOWBranchManager(db);
+ * const branch = manager.createBranch('dream-123');
+ * // ... run dream logic ...
+ * const result = manager.validateBranch(branch, baseline);
+ * if (result.passed) {
+ *   manager.mergeBranch(branch);
+ * } else {
+ *   manager.discardBranch(branch);
+ * }
+ * ```
+ */
+export declare class RVCOWBranchManager {
+    private readonly db;
+    private readonly thresholds;
+    private activeBranches;
+    private listeners;
+    /** Optional RVF native adapter for COW fork snapshots of dream state */
+    private rvfAdapter?;
+    /** When true and rvfAdapter is set, createBranch() also forks an RVF snapshot */
+    private useRvfFork;
+    constructor(db: DatabaseType, thresholds?: ValidationThresholds);
+    /**
+     * Set an RVF native adapter for supplementary COW fork snapshots.
+     * When set with useRvfFork=true, createBranch() will additionally
+     * fork a portable .rvf snapshot alongside the SQLite savepoint.
+     * SQLite savepoints remain the primary branching mechanism.
+     */
+    setRvfAdapter(adapter: any, useRvfFork?: boolean): void;
+    /**
+     * Create a new RVCOW branch by issuing a SQLite SAVEPOINT.
+     * Captures a quality baseline snapshot before the savepoint.
+     *
+     * @param name - Unique branch name (used as savepoint identifier)
+     * @returns The created Branch
+     * @throws If a branch with this name already exists
+     */
+    createBranch(name: string): Branch;
+    /**
+     * Validate a branch by comparing post-dream metrics against the baseline.
+     *
+     * Checks:
+     * 1. Pattern count did not decrease beyond threshold
+     * 2. Average confidence did not drop beyond threshold
+     * 3. No excessive high-confidence patterns were quarantined/removed
+     *
+     * @param branch - The branch to validate
+     * @param baseline - The quality baseline to validate against (defaults to branch's own baseline)
+     * @returns Validation result with pass/fail and metrics
+     */
+    validateBranch(branch: Branch, baseline?: QualityBaseline): ValidationResult;
+    /**
+     * Merge a branch by releasing its savepoint.
+     * All changes made within the branch become permanent.
+     *
+     * @param branch - The branch to merge
+     */
+    mergeBranch(branch: Branch): void;
+    /**
+     * Discard a branch by rolling back to its savepoint.
+     * All changes made within the branch are undone.
+     *
+     * @param branch - The branch to discard
+     */
+    discardBranch(branch: Branch): void;
+    /**
+     * List all active branches.
+     */
+    listBranches(): Branch[];
+    /**
+     * Register a listener for branch events.
+     */
+    onEvent(listener: BranchEventListener): void;
+    /**
+     * Remove a previously registered listener.
+     */
+    offEvent(listener: BranchEventListener): void;
+    /**
+     * Capture a quality baseline from the current state of qe_patterns.
+     */
+    captureBaseline(): QualityBaseline;
+    private ensureBranchActive;
+    private sanitizeSavepointName;
+    private emit;
+}
+//# sourceMappingURL=rvcow-branch-manager.d.ts.map

package/v3/dist/learning/dream/rvcow-branch-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvcow-branch-manager.d.ts","sourceRoot":"","sources":["../../../src/learning/dream/rvcow-branch-manager.ts"],"names":[],"mappings":"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"}

package/v3/dist/learning/dream/rvcow-branch-manager.js

@@ -0,0 +1,263 @@
+/**
+ * RVCOWBranchManager - RVCOW Branching for Reversible Dream Cycles
+ * ADR-069: RVCOW Dream Cycle Branching
+ *
+ * Implements Copy-on-Write branching semantics using SQLite savepoints.
+ * Each dream cycle operates on an isolated branch (savepoint). After the
+ * dream completes, the branch is validated against quality thresholds.
+ * If validation passes, the savepoint is released (changes persist).
+ * If validation fails, the savepoint is rolled back (changes discarded).
+ *
+ * This gives us the same semantics as native RVCOW:
+ *   - createBranch  -> SAVEPOINT
+ *   - mergeBranch   -> RELEASE SAVEPOINT
+ *   - discardBranch -> ROLLBACK TO SAVEPOINT
+ *
+ * @module v3/learning/dream/rvcow-branch-manager
+ */
+/** Default validation thresholds */
+export const DEFAULT_VALIDATION_THRESHOLDS = {
+    maxPatternCountDrop: 0.05,
+    maxAvgConfidenceDrop: 0.02,
+    maxHighConfidenceLoss: 0.05,
+};
+// ============================================================================
+// RVCOWBranchManager
+// ============================================================================
+/**
+ * Manages RVCOW branches for dream cycles using SQLite savepoints.
+ *
+ * Usage:
+ * ```typescript
+ * const manager = new RVCOWBranchManager(db);
+ * const branch = manager.createBranch('dream-123');
+ * // ... run dream logic ...
+ * const result = manager.validateBranch(branch, baseline);
+ * if (result.passed) {
+ *   manager.mergeBranch(branch);
+ * } else {
+ *   manager.discardBranch(branch);
+ * }
+ * ```
+ */
+export class RVCOWBranchManager {
+    db;
+    thresholds;
+    activeBranches = new Map();
+    listeners = [];
+    /** Optional RVF native adapter for COW fork snapshots of dream state */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rvfAdapter;
+    /** When true and rvfAdapter is set, createBranch() also forks an RVF snapshot */
+    useRvfFork = false;
+    constructor(db, thresholds = DEFAULT_VALIDATION_THRESHOLDS) {
+        this.db = db;
+        this.thresholds = thresholds;
+    }
+    /**
+     * Set an RVF native adapter for supplementary COW fork snapshots.
+     * When set with useRvfFork=true, createBranch() will additionally
+     * fork a portable .rvf snapshot alongside the SQLite savepoint.
+     * SQLite savepoints remain the primary branching mechanism.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    setRvfAdapter(adapter, useRvfFork = true) {
+        this.rvfAdapter = adapter;
+        this.useRvfFork = useRvfFork;
+    }
+    // --------------------------------------------------------------------------
+    // Branch Lifecycle
+    // --------------------------------------------------------------------------
+    /**
+     * Create a new RVCOW branch by issuing a SQLite SAVEPOINT.
+     * Captures a quality baseline snapshot before the savepoint.
+     *
+     * @param name - Unique branch name (used as savepoint identifier)
+     * @returns The created Branch
+     * @throws If a branch with this name already exists
+     */
+    createBranch(name) {
+        if (this.activeBranches.has(name)) {
+            throw new Error(`Branch '${name}' already exists`);
+        }
+        // Sanitize name for use as savepoint identifier
+        const safeName = this.sanitizeSavepointName(name);
+        // Capture baseline before creating savepoint
+        const baseline = this.captureBaseline();
+        // Create SQLite savepoint
+        this.db.exec(`SAVEPOINT "${safeName}"`);
+        const branch = {
+            name,
+            createdAt: new Date(),
+            status: 'active',
+            baselineSnapshot: baseline,
+        };
+        // Supplementary RVF fork for portable brain snapshots (when configured)
+        if (this.rvfAdapter && this.useRvfFork) {
+            try {
+                this.rvfAdapter.fork(`/tmp/dream-branch-${name}.rvf`);
+            }
+            catch {
+                // RVF fork is best-effort — SQLite savepoint is the primary mechanism
+            }
+        }
+        this.activeBranches.set(name, branch);
+        this.emit('dream:branch_created', branch);
+        return branch;
+    }
+    /**
+     * Validate a branch by comparing post-dream metrics against the baseline.
+     *
+     * Checks:
+     * 1. Pattern count did not decrease beyond threshold
+     * 2. Average confidence did not drop beyond threshold
+     * 3. No excessive high-confidence patterns were quarantined/removed
+     *
+     * @param branch - The branch to validate
+     * @param baseline - The quality baseline to validate against (defaults to branch's own baseline)
+     * @returns Validation result with pass/fail and metrics
+     */
+    validateBranch(branch, baseline) {
+        this.ensureBranchActive(branch.name);
+        const base = baseline ?? branch.baselineSnapshot;
+        const current = this.captureBaseline();
+        const patternCountDelta = current.patternCount - base.patternCount;
+        const avgConfidenceDelta = current.avgConfidence - base.avgConfidence;
+        const highConfidenceLost = base.highConfidenceCount - current.highConfidenceCount;
+        const reasons = [];
+        let passed = true;
+        // Check 1: Pattern count did not decrease excessively
+        if (base.patternCount > 0) {
+            const dropFraction = -patternCountDelta / base.patternCount;
+            if (dropFraction > this.thresholds.maxPatternCountDrop) {
+                passed = false;
+                reasons.push(`Pattern count dropped by ${(dropFraction * 100).toFixed(1)}% ` +
+                    `(threshold: ${(this.thresholds.maxPatternCountDrop * 100).toFixed(1)}%)`);
+            }
+        }
+        // Check 2: Average confidence did not drop excessively
+        if (avgConfidenceDelta < -this.thresholds.maxAvgConfidenceDrop) {
+            passed = false;
+            reasons.push(`Avg confidence dropped by ${(-avgConfidenceDelta).toFixed(4)} ` +
+                `(threshold: ${this.thresholds.maxAvgConfidenceDrop})`);
+        }
+        // Check 3: High-confidence patterns not excessively quarantined
+        if (base.highConfidenceCount > 0 && highConfidenceLost > 0) {
+            const lossFraction = highConfidenceLost / base.highConfidenceCount;
+            if (lossFraction > this.thresholds.maxHighConfidenceLoss) {
+                passed = false;
+                reasons.push(`${highConfidenceLost} high-confidence patterns lost ` +
+                    `(${(lossFraction * 100).toFixed(1)}%, threshold: ${(this.thresholds.maxHighConfidenceLoss * 100).toFixed(1)}%)`);
+            }
+        }
+        const reason = passed
+            ? 'All quality checks passed'
+            : `Validation failed: ${reasons.join('; ')}`;
+        return {
+            passed,
+            reason,
+            patternCountDelta,
+            avgConfidenceDelta,
+            highConfidenceLost: Math.max(0, highConfidenceLost),
+            postDreamMetrics: current,
+        };
+    }
+    /**
+     * Merge a branch by releasing its savepoint.
+     * All changes made within the branch become permanent.
+     *
+     * @param branch - The branch to merge
+     */
+    mergeBranch(branch) {
+        this.ensureBranchActive(branch.name);
+        const safeName = this.sanitizeSavepointName(branch.name);
+        this.db.exec(`RELEASE SAVEPOINT "${safeName}"`);
+        branch.status = 'merged';
+        this.activeBranches.delete(branch.name);
+        this.emit('dream:branch_merged', branch);
+    }
+    /**
+     * Discard a branch by rolling back to its savepoint.
+     * All changes made within the branch are undone.
+     *
+     * @param branch - The branch to discard
+     */
+    discardBranch(branch) {
+        this.ensureBranchActive(branch.name);
+        const safeName = this.sanitizeSavepointName(branch.name);
+        // ROLLBACK TO keeps the savepoint active, so we release it after
+        this.db.exec(`ROLLBACK TO SAVEPOINT "${safeName}"`);
+        this.db.exec(`RELEASE SAVEPOINT "${safeName}"`);
+        branch.status = 'discarded';
+        this.activeBranches.delete(branch.name);
+        this.emit('dream:branch_discarded', branch);
+    }
+    /**
+     * List all active branches.
+     */
+    listBranches() {
+        return Array.from(this.activeBranches.values());
+    }
+    // --------------------------------------------------------------------------
+    // Event System
+    // --------------------------------------------------------------------------
+    /**
+     * Register a listener for branch events.
+     */
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Remove a previously registered listener.
+     */
+    offEvent(listener) {
+        const idx = this.listeners.indexOf(listener);
+        if (idx >= 0) {
+            this.listeners.splice(idx, 1);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Quality Baseline Capture
+    // --------------------------------------------------------------------------
+    /**
+     * Capture a quality baseline from the current state of qe_patterns.
+     */
+    captureBaseline() {
+        const countRow = this.db.prepare('SELECT COUNT(*) as cnt FROM qe_patterns').get();
+        const avgRow = this.db.prepare('SELECT AVG(confidence) as avg_conf FROM qe_patterns').get();
+        const highRow = this.db.prepare('SELECT COUNT(*) as cnt FROM qe_patterns WHERE confidence >= 0.8').get();
+        return {
+            patternCount: countRow?.cnt ?? 0,
+            avgConfidence: avgRow?.avg_conf ?? 0,
+            highConfidenceCount: highRow?.cnt ?? 0,
+            capturedAt: new Date(),
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Private Helpers
+    // --------------------------------------------------------------------------
+    ensureBranchActive(name) {
+        const branch = this.activeBranches.get(name);
+        if (!branch) {
+            throw new Error(`Branch '${name}' not found or not active`);
+        }
+        if (branch.status !== 'active') {
+            throw new Error(`Branch '${name}' is ${branch.status}, not active`);
+        }
+    }
+    sanitizeSavepointName(name) {
+        // Replace non-alphanumeric characters (except hyphens/underscores) with underscores
+        return name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    }
+    emit(event, branch, detail) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event, branch, detail);
+            }
+            catch {
+                // Swallow listener errors to avoid breaking the branch lifecycle
+            }
+        }
+    }
+}
+//# sourceMappingURL=rvcow-branch-manager.js.map

package/v3/dist/learning/dream/rvcow-branch-manager.js.map

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

package/v3/dist/learning/dream/speculative-dreamer.d.ts

@@ -0,0 +1,129 @@
+/**
+ * SpeculativeDreamer - Parallel Dream Strategies with Branch Selection
+ * ADR-069: RVCOW Dream Cycle Branching
+ *
+ * Runs 2-3 dream strategies in parallel RVCOW branches, each with
+ * different parameters (decay rates, spread factors, noise levels).
+ * After all strategies complete, compares validation scores and merges
+ * the best-performing branch. All other branches are discarded.
+ *
+ * This implements the "adversarial dream" concept from the Six Thinking
+ * Hats analysis, where diverse strategies compete and the best wins.
+ *
+ * @module v3/learning/dream/speculative-dreamer
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import type { ActivationConfig } from './spreading-activation.js';
+import { RVCOWBranchManager, type Branch, type ValidationResult, type ValidationThresholds } from './rvcow-branch-manager.js';
+/**
+ * A named dream strategy with custom activation parameters.
+ */
+export interface DreamStrategy {
+    /** Human-readable strategy name */
+    name: string;
+    /** Custom activation config overrides */
+    activationConfig: Partial<ActivationConfig>;
+    /** Optional description of the strategy's approach */
+    description?: string;
+}
+/**
+ * Result of a single speculative dream branch.
+ */
+export interface StrategyResult {
+    /** The strategy that was executed */
+    strategy: DreamStrategy;
+    /** The branch used */
+    branch: Branch;
+    /** Validation result against baseline */
+    validation: ValidationResult;
+    /** Whether this strategy was selected as the winner */
+    selected: boolean;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Result of the full speculative dreaming process.
+ */
+export interface SpeculativeDreamResult {
+    /** All strategy results, including winner and losers */
+    strategies: StrategyResult[];
+    /** The winning strategy (or null if all failed validation) */
+    winner: StrategyResult | null;
+    /** Total wall-clock time */
+    totalDurationMs: number;
+}
+/**
+ * Callback that executes a dream cycle with the given activation config.
+ * The implementation should use the provided config overrides when running
+ * spreading activation. It returns the number of insights generated.
+ */
+export type DreamExecutor = (activationConfigOverrides: Partial<ActivationConfig>) => Promise<number>;
+/**
+ * Predefined dream strategies with different parameter profiles.
+ */
+export declare const BUILT_IN_STRATEGIES: DreamStrategy[];
+/**
+ * Runs multiple dream strategies in separate RVCOW branches and selects the best.
+ *
+ * Because SQLite savepoints are sequential (not truly parallel), strategies
+ * are executed one at a time but each in its own savepoint. The branch manager
+ * ensures that failed strategies leave no trace in the database.
+ *
+ * @example
+ * ```typescript
+ * const dreamer = new SpeculativeDreamer(db);
+ * const result = await dreamer.dream(
+ *   BUILT_IN_STRATEGIES,
+ *   async (configOverrides) => {
+ *     // Run dream with configOverrides applied
+ *     return insightCount;
+ *   }
+ * );
+ * if (result.winner) {
+ *   console.log(`Best strategy: ${result.winner.strategy.name}`);
+ * }
+ * ```
+ */
+export declare class SpeculativeDreamer {
+    private readonly db;
+    private readonly branchManager;
+    constructor(db: DatabaseType, thresholds?: ValidationThresholds);
+    /**
+     * Run multiple dream strategies sequentially in separate RVCOW branches,
+     * then merge the best-performing one and discard the rest.
+     *
+     * Strategy execution flow:
+     * 1. Capture baseline before any strategy runs
+     * 2. For each strategy:
+     *    a. Create branch (SAVEPOINT)
+     *    b. Execute dream with strategy params
+     *    c. Validate branch against baseline
+     *    d. Discard branch (ROLLBACK) -- we keep results in memory only
+     * 3. Replay the winning strategy in a final branch and merge it
+     *
+     * Note: Because we must discard each branch before starting the next
+     * (SQLite savepoint semantics), the winning strategy is re-executed
+     * in step 3. This is acceptable because dream cycles are deterministic
+     * given the same input state and parameters.
+     *
+     * @param strategies - 2-3 strategies to compete
+     * @param executor - Callback that runs the dream with given config
+     * @returns Result with winner and all strategy details
+     */
+    dream(strategies: DreamStrategy[], executor: DreamExecutor): Promise<SpeculativeDreamResult>;
+    /**
+     * Get the underlying branch manager (for event subscription).
+     */
+    getBranchManager(): RVCOWBranchManager;
+    /**
+     * Execute a single strategy in a branch, validate, then discard.
+     * We discard because we need to try all strategies from the same baseline.
+     */
+    private executeStrategy;
+    /**
+     * Score a validation result for comparison.
+     * Higher score = better dream result.
+     */
+    private scoreValidation;
+}
+//# sourceMappingURL=speculative-dreamer.d.ts.map

package/v3/dist/learning/dream/speculative-dreamer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculative-dreamer.d.ts","sourceRoot":"","sources":["../../../src/learning/dream/speculative-dreamer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,KAAK,MAAM,EAEX,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAMnC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE5C,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,QAAQ,EAAE,aAAa,CAAC;IAExB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,yCAAyC;IACzC,UAAU,EAAE,gBAAgB,CAAC;IAE7B,uDAAuD;IACvD,QAAQ,EAAE,OAAO,CAAC;IAElB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,UAAU,EAAE,cAAc,EAAE,CAAC;IAE7B,8DAA8D;IAC9D,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE9B,4BAA4B;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,yBAAyB,EAAE,OAAO,CAAC,gBAAgB,CAAC,KACjD,OAAO,CAAC,MAAM,CAAC,CAAC;AAMrB;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,EA+B9C,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAGhC,EAAE,EAAE,YAAY,EACjC,UAAU,CAAC,EAAE,oBAAoB;IAKnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,KAAK,CACT,UAAU,EAAE,aAAa,EAAE,EAC3B,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,sBAAsB,CAAC;IAsDlC;;OAEG;IACH,gBAAgB,IAAI,kBAAkB;IAQtC;;;OAGG;YACW,eAAe;IA4C7B;;;OAGG;IACH,OAAO,CAAC,eAAe;CASxB"}