@cleocode/core 2026.4.30 → 2026.4.35

package/dist/memory/brain-purge.js

@@ -0,0 +1,243 @@
+/**
+ * Brain.db noise purge utility — removes 2927 noise entries leaving ~57 signal entries.
+ *
+ * Purge rules:
+ * - Patterns: keep newest per unique pattern text (dedup), delete duplicates
+ * - Learnings: delete ALL (all are auto-generated task completion noise)
+ * - Decisions: delete ALL except D-mntpeeer (the one real architectural decision)
+ * - Observations: delete task-start/task-complete/session-note/test/junk noise
+ *
+ * Safety: requires backup to exist before calling. Never touches tasks.db.
+ *
+ * @task T524
+ * @epic T523
+ */
+import { inArray, ne, sql } from 'drizzle-orm';
+import { brainDecisions, brainLearnings, brainObservations, brainPatterns, } from '../store/brain-schema.js';
+import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import { ensureFts5Tables, rebuildFts5Index } from './brain-search.js';
+/**
+ * Count rows in a table using native DB PRAGMA (avoids Drizzle type issues).
+ * Falls back to 0 on error.
+ */
+function countRowsNative(tableName) {
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb)
+        return 0;
+    try {
+        const row = nativeDb.prepare(`SELECT COUNT(*) AS cnt FROM ${tableName}`).get();
+        return row?.cnt ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Execute the brain.db noise purge.
+ *
+ * Deletes ~2927 noise entries across four tables, leaving ~57 signal entries.
+ * The one real architectural decision (D-mntpeeer) is explicitly preserved.
+ *
+ * Rules applied in order:
+ * 1. Patterns: deduplicate by pattern text — keep newest per unique text, delete older dupes
+ * 2. Learnings: delete all (100% noise — auto-generated "Completed:" and dependency notices)
+ * 3. Decisions: delete all except D-mntpeeer
+ * 4. Observations: delete task-start, task-complete, session-note, and test/junk entries
+ *
+ * @param projectRoot - Absolute path to the project root (e.g. /mnt/projects/cleocode)
+ * @returns PurgeResult with before/after counts and FTS5 status
+ */
+export async function purgeBrainNoise(projectRoot) {
+    const db = await getBrainDb(projectRoot);
+    // =========================================================================
+    // Pre-purge counts
+    // =========================================================================
+    const beforePatterns = countRowsNative('brain_patterns');
+    const beforeLearnings = countRowsNative('brain_learnings');
+    const beforeDecisions = countRowsNative('brain_decisions');
+    const beforeObservations = countRowsNative('brain_observations');
+    console.log('Pre-purge counts:');
+    console.log(`  Patterns:     ${beforePatterns}`);
+    console.log(`  Learnings:    ${beforeLearnings}`);
+    console.log(`  Decisions:    ${beforeDecisions}`);
+    console.log(`  Observations: ${beforeObservations}`);
+    // =========================================================================
+    // SAFETY: Confirm D-mntpeeer exists before any destructive operation
+    // =========================================================================
+    const realDecision = await db.select().from(brainDecisions).where(sql `id = 'D-mntpeeer'`);
+    if (realDecision.length === 0) {
+        throw new Error('SAFETY ABORT: D-mntpeeer not found in brain_decisions. Backup and restore required.');
+    }
+    console.log('Safety check passed: D-mntpeeer confirmed present');
+    // =========================================================================
+    // Rule 1: Pattern deduplication
+    // Strategy: for each unique pattern text, find the MAX(extracted_at) row,
+    // delete all other rows with the same text.
+    // =========================================================================
+    // Get all patterns to find duplicates in TS (safer than raw SQL subquery)
+    const allPatterns = await db.select().from(brainPatterns);
+    // Group by normalized pattern text
+    const patternGroups = new Map();
+    for (const p of allPatterns) {
+        const key = p.pattern.trim().toLowerCase();
+        const group = patternGroups.get(key) ?? [];
+        group.push(p);
+        patternGroups.set(key, group);
+    }
+    // Collect IDs to delete: for each group with >1 entry, keep newest (max extractedAt), delete rest
+    const patternIdsToDelete = [];
+    for (const [, group] of patternGroups) {
+        if (group.length <= 1)
+            continue;
+        // Sort by extractedAt desc, keep first, delete the rest
+        group.sort((a, b) => (b.extractedAt > a.extractedAt ? 1 : -1));
+        const toDelete = group.slice(1).map((p) => p.id);
+        patternIdsToDelete.push(...toDelete);
+    }
+    let patternsDeleted = 0;
+    if (patternIdsToDelete.length > 0) {
+        // Delete in batches of 500 to avoid SQLite parameter limits
+        const BATCH = 500;
+        for (let i = 0; i < patternIdsToDelete.length; i += BATCH) {
+            const batch = patternIdsToDelete.slice(i, i + BATCH);
+            await db.delete(brainPatterns).where(inArray(brainPatterns.id, batch));
+            patternsDeleted += batch.length;
+        }
+    }
+    console.log(`Patterns deleted (dedup): ${patternsDeleted}`);
+    // =========================================================================
+    // Rule 2: Delete ALL learnings (100% noise)
+    // All learnings are auto-generated "Completed: T..." or dependency notices
+    // =========================================================================
+    // Count before delete using run
+    const learningsRows = await db.select().from(brainLearnings);
+    const learningsDeleted = learningsRows.length;
+    if (learningsDeleted > 0) {
+        // Delete in batches using IDs
+        const ids = learningsRows.map((r) => r.id);
+        const BATCH = 500;
+        for (let i = 0; i < ids.length; i += BATCH) {
+            const batch = ids.slice(i, i + BATCH);
+            await db.delete(brainLearnings).where(inArray(brainLearnings.id, batch));
+        }
+    }
+    console.log(`Learnings deleted (all): ${learningsDeleted}`);
+    // =========================================================================
+    // Rule 3: Delete ALL decisions EXCEPT D-mntpeeer
+    // =========================================================================
+    const decisionsToDelete = await db
+        .select()
+        .from(brainDecisions)
+        .where(ne(brainDecisions.id, 'D-mntpeeer'));
+    const decisionsDeleted = decisionsToDelete.length;
+    if (decisionsDeleted > 0) {
+        const ids = decisionsToDelete.map((r) => r.id);
+        await db.delete(brainDecisions).where(inArray(brainDecisions.id, ids));
+    }
+    console.log(`Decisions deleted (all except D-mntpeeer): ${decisionsDeleted}`);
+    // =========================================================================
+    // Rule 4: Delete noise observations
+    // Keep: real release notes, real codebase analysis, real session handoffs
+    // Delete: task-start, task-complete, session-note, test/junk entries
+    // =========================================================================
+    // Collect all observations to classify them
+    const allObservations = await db.select().from(brainObservations);
+    const obsIdsToDelete = [];
+    for (const obs of allObservations) {
+        const title = obs.title ?? '';
+        const narrative = (obs.narrative ?? '').toLowerCase();
+        const titleLower = title.toLowerCase();
+        // Rule 4a: Task lifecycle noise
+        if (title.startsWith('Task start: T') ||
+            title.startsWith('Task complete: T') ||
+            title.startsWith('Task depended on') ||
+            title.startsWith('Task T') // catch "Task T527 depended on..." etc.
+        ) {
+            obsIdsToDelete.push(obs.id);
+            continue;
+        }
+        // Rule 4b: Session notes (all are noise — real handoffs are in sticky notes)
+        if (title.startsWith('Session note:')) {
+            obsIdsToDelete.push(obs.id);
+            continue;
+        }
+        // Rule 4c: Test/audit/probe/junk observations
+        const testKeywords = [
+            'audit test',
+            'audit probe',
+            'probe observation',
+            'dup test',
+            'provider test',
+            'brain regression',
+            'brain validation',
+            'release test',
+            'functional validation',
+            'test title',
+            'test decision',
+            'test learning',
+            'test pattern',
+            'test observation',
+            'sticky note', // audit test sticky note
+        ];
+        const isTestNoise = testKeywords.some((kw) => titleLower.includes(kw) || narrative.includes(kw));
+        if (isTestNoise) {
+            obsIdsToDelete.push(obs.id);
+        }
+        // Rule 4d: Auto-detection codebase map noise (keep real ones, delete duplicates)
+        // "Codebase Stack Analysis" and "Codebase Integrations" — keep one of each,
+        // but the task asks us to keep ~27 so we apply conservative rules.
+        // Only delete if title exactly matches auto-generated repeated patterns.
+    }
+    let observationsDeleted = 0;
+    if (obsIdsToDelete.length > 0) {
+        const BATCH = 500;
+        for (let i = 0; i < obsIdsToDelete.length; i += BATCH) {
+            const batch = obsIdsToDelete.slice(i, i + BATCH);
+            await db.delete(brainObservations).where(inArray(brainObservations.id, batch));
+            observationsDeleted += batch.length;
+        }
+    }
+    console.log(`Observations deleted: ${observationsDeleted}`);
+    // =========================================================================
+    // Post-purge counts
+    // =========================================================================
+    const afterPatterns = countRowsNative('brain_patterns');
+    const afterLearnings = countRowsNative('brain_learnings');
+    const afterDecisions = countRowsNative('brain_decisions');
+    const afterObservations = countRowsNative('brain_observations');
+    console.log('\nPost-purge counts:');
+    console.log(`  Patterns:     ${afterPatterns} (deleted ${beforePatterns - afterPatterns})`);
+    console.log(`  Learnings:    ${afterLearnings} (deleted ${beforeLearnings - afterLearnings})`);
+    console.log(`  Decisions:    ${afterDecisions} (deleted ${beforeDecisions - afterDecisions})`);
+    console.log(`  Observations: ${afterObservations} (deleted ${beforeObservations - afterObservations})`);
+    // =========================================================================
+    // Rebuild FTS5 indexes after bulk deletes
+    // =========================================================================
+    let fts5Rebuilt = false;
+    const nativeDb = getBrainNativeDb();
+    if (nativeDb) {
+        ensureFts5Tables(nativeDb);
+        try {
+            rebuildFts5Index(nativeDb);
+            fts5Rebuilt = true;
+            console.log('FTS5 indexes rebuilt successfully');
+        }
+        catch (err) {
+            console.warn('FTS5 rebuild failed (non-fatal):', err);
+        }
+    }
+    return {
+        patternsDeleted: beforePatterns - afterPatterns,
+        learningsDeleted: beforeLearnings - afterLearnings,
+        decisionsDeleted: beforeDecisions - afterDecisions,
+        observationsDeleted: beforeObservations - afterObservations,
+        after: {
+            patterns: afterPatterns,
+            learnings: afterLearnings,
+            decisions: afterDecisions,
+            observations: afterObservations,
+        },
+        fts5Rebuilt,
+    };
+}
+//# sourceMappingURL=brain-purge.js.map

package/dist/memory/brain-purge.js.map

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

package/dist/memory/brain-reasoning.js

@@ -0,0 +1,215 @@
+/**
+ * BRAIN Reasoning — causal trace through task dependency chains.
+ *
+ * `reasonWhy(taskId)` walks upstream through a task's blocker chain,
+ * enriching each node with related brain_decisions. Leaf tasks with
+ * no further unresolved blockers are identified as root causes.
+ *
+ * @task T5390
+ * @epic T5149
+ */
+import { getBrainAccessor } from '../store/brain-accessor.js';
+import { getAccessor } from '../store/data-accessor.js';
+import { searchBrain } from './brain-search.js';
+import { searchSimilar } from './brain-similarity.js';
+// ============================================================================
+// Implementation
+// ============================================================================
+const MAX_DEPTH = 10;
+/**
+ * Build a causal trace for why a task is blocked.
+ *
+ * Walks upstream through `depends` fields, collecting unresolved blockers
+ * and their associated brain decisions. Leaf blockers (no further unresolved
+ * deps) are reported as root causes.
+ */
+export async function reasonWhy(taskId, projectRoot, taskAccessor) {
+    const acc = taskAccessor ?? (await getAccessor(projectRoot));
+    const { tasks: reasonTasks } = await acc.queryTasks({});
+    const taskMap = new Map(reasonTasks.map((t) => [t.id, t]));
+    const completedStatuses = new Set(['done', 'cancelled']);
+    let accessor = null;
+    try {
+        accessor = await getBrainAccessor(projectRoot);
+    }
+    catch {
+        // brain.db may not exist — proceed without decisions
+    }
+    const visited = new Set();
+    const blockers = [];
+    let maxDepthReached = 0;
+    async function walk(id, depth) {
+        if (visited.has(id))
+            return;
+        if (depth > MAX_DEPTH)
+            return;
+        visited.add(id);
+        if (depth > maxDepthReached) {
+            maxDepthReached = depth;
+        }
+        const task = taskMap.get(id);
+        if (!task)
+            return;
+        // Collect unresolved dependencies
+        const unresolvedDeps = (task.depends ?? []).filter((depId) => {
+            const dep = taskMap.get(depId);
+            return dep && !completedStatuses.has(dep.status);
+        });
+        if (unresolvedDeps.length === 0 && id !== taskId) {
+            // This is a leaf blocker — no further unresolved deps
+            return;
+        }
+        for (const depId of unresolvedDeps) {
+            if (visited.has(depId))
+                continue;
+            const dep = taskMap.get(depId);
+            // Query brain decisions related to this blocker
+            let decisions = [];
+            if (accessor) {
+                const relatedDecisions = await findDecisionsForTask(accessor, depId);
+                decisions = relatedDecisions.map((d) => ({
+                    id: d.id,
+                    title: d.decision,
+                    rationale: d.rationale,
+                }));
+            }
+            blockers.push({
+                taskId: depId,
+                status: dep.status,
+                reason: dep.blockedBy ?? undefined,
+                decisions,
+            });
+            await walk(depId, depth + 1);
+        }
+    }
+    await walk(taskId, 0);
+    // Root causes: leaf blockers whose own deps are all resolved or absent
+    const blockerIds = new Set(blockers.map((b) => b.taskId));
+    const rootCauses = blockers
+        .filter((b) => {
+        const task = taskMap.get(b.taskId);
+        if (!task?.depends?.length)
+            return true;
+        return task.depends.every((depId) => {
+            const dep = taskMap.get(depId);
+            return !dep || completedStatuses.has(dep.status) || !blockerIds.has(depId);
+        });
+    })
+        .map((b) => b.taskId);
+    return {
+        taskId,
+        blockers,
+        rootCauses,
+        depth: maxDepthReached,
+    };
+}
+/**
+ * Query brain_decisions for a specific task context.
+ */
+async function findDecisionsForTask(accessor, taskId) {
+    return accessor.findDecisions({ contextTaskId: taskId });
+}
+/**
+ * Find entries similar to a given brain.db entry.
+ *
+ * 1. Loads the source entry's text from brain.db.
+ * 2. Calls searchSimilar() for vector-based similarity if embeddings exist.
+ * 3. Falls back to FTS5 keyword search if no embeddings are available.
+ * 4. Filters out the source entry itself.
+ *
+ * @param entryId - ID of the brain.db entry to find similar entries for
+ * @param projectRoot - Project root directory
+ * @param limit - Maximum results to return (default 10)
+ * @returns Array of similar entries ranked by distance/relevance
+ */
+export async function reasonSimilar(entryId, projectRoot, limit) {
+    const maxResults = limit ?? 10;
+    // Load the source entry's text — initialize brain.db before accessor use
+    const { getBrainDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const accessor = await getBrainAccessor(projectRoot);
+    let sourceText = null;
+    if (entryId.startsWith('D-') || /^D\d/.test(entryId)) {
+        const row = await accessor.getDecision(entryId);
+        if (row)
+            sourceText = `${row.decision} ${row.rationale}`;
+    }
+    else if (entryId.startsWith('P-') || /^P\d/.test(entryId)) {
+        const row = await accessor.getPattern(entryId);
+        if (row)
+            sourceText = `${row.pattern} ${row.context}`;
+    }
+    else if (entryId.startsWith('L-') || /^L\d/.test(entryId)) {
+        const row = await accessor.getLearning(entryId);
+        if (row)
+            sourceText = `${row.insight} ${row.source}`;
+    }
+    else {
+        const row = await accessor.getObservation(entryId);
+        if (row)
+            sourceText = row.narrative ?? row.title;
+    }
+    if (!sourceText)
+        return [];
+    // Try vector similarity first
+    const vecResults = await searchSimilar(sourceText, projectRoot, maxResults + 1);
+    if (vecResults.length > 0) {
+        return vecResults.filter((r) => r.id !== entryId).slice(0, maxResults);
+    }
+    // FTS5 fallback: extract key terms and search
+    const terms = sourceText
+        .split(/\s+/)
+        .filter((t) => t.length > 3)
+        .slice(0, 5)
+        .join(' ');
+    if (!terms)
+        return [];
+    const ftsResults = await searchBrain(projectRoot, terms, { limit: maxResults + 5 });
+    const entries = [];
+    for (const d of ftsResults.decisions) {
+        if (d.id === entryId)
+            continue;
+        entries.push({
+            id: d.id,
+            distance: 0,
+            type: 'decision',
+            title: d.decision,
+            text: `${d.decision} — ${d.rationale}`,
+        });
+    }
+    for (const p of ftsResults.patterns) {
+        if (p.id === entryId)
+            continue;
+        entries.push({
+            id: p.id,
+            distance: 0,
+            type: 'pattern',
+            title: p.pattern,
+            text: `${p.pattern} — ${p.context}`,
+        });
+    }
+    for (const l of ftsResults.learnings) {
+        if (l.id === entryId)
+            continue;
+        entries.push({
+            id: l.id,
+            distance: 0,
+            type: 'learning',
+            title: l.insight,
+            text: `${l.insight} (source: ${l.source})`,
+        });
+    }
+    for (const o of ftsResults.observations) {
+        if (o.id === entryId)
+            continue;
+        entries.push({
+            id: o.id,
+            distance: 0,
+            type: 'observation',
+            title: o.title,
+            text: o.narrative ?? o.title,
+        });
+    }
+    return entries.slice(0, maxResults);
+}
+//# sourceMappingURL=brain-reasoning.js.map

package/dist/memory/brain-reasoning.js.map

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

package/dist/memory/brain-retrieval.d.ts

@@ -16,7 +16,7 @@
  * @epic T5149
  */
 import type { NextDirectives } from '../mvi-helpers.js';
-import type { BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_OBSERVATION_TYPES } from '../store/brain-schema.js';
+import type { BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_OBSERVATION_TYPES, BrainSourceConfidence } from '../store/brain-schema.js';
 import type { BrainAnchor } from './brain-row-types.js';
 /** Compact search hit — minimal fields for index-level results. */
 export interface BrainCompactHit {
@@ -92,6 +92,14 @@ export interface ObserveBrainParams {
     sourceType?: BrainObservationSourceType;
     /** T417: agent provenance — the name of the spawned agent producing this observation. */
     agent?: string;
+    /**
+     * T549 Wave 1-A: source reliability level.
+     * Overrides the default routing. If omitted, routing is determined automatically:
+     * - sourceType 'manual' → 'owner'
+     * - sourceType 'session-debrief' → 'task-outcome'
+     * - otherwise → 'agent'
+     */
+    sourceConfidence?: BrainSourceConfidence;
 }
 /** Result from observeBrain. */
 export interface ObserveBrainResult {
@@ -187,4 +195,64 @@ export interface PopulateEmbeddingsOptions {
  * @task T142
  */
 export declare function populateEmbeddings(projectRoot: string, options?: PopulateEmbeddingsOptions): Promise<PopulateEmbeddingsResult>;
+/** Options for budget-aware retrieval. */
+export interface BudgetedRetrievalOptions {
+    /** Filter by cognitive types (semantic / episodic / procedural). */
+    types?: Array<'semantic' | 'episodic' | 'procedural'>;
+    /** Filter by memory tiers (short / medium / long). */
+    tiers?: Array<'short' | 'medium' | 'long'>;
+    /** When true, only return verified entries. Default: false. */
+    verified?: boolean;
+}
+/** A single entry returned by budget-aware retrieval. */
+export interface BudgetedEntry {
+    id: string;
+    type: string;
+    title: string;
+    text: string;
+    /** Fused relevance score: FTS50% + vector40% + graph10% × qualityScore. */
+    score: number;
+    /** Estimated token cost for this entry (~chars/4). */
+    tokensEstimated: number;
+    /** Memory tier for this entry. */
+    memoryTier?: string;
+    /** Cognitive type for this entry. */
+    memoryType?: string;
+}
+/** Result from retrieveWithBudget. */
+export interface BudgetedResult {
+    entries: BudgetedEntry[];
+    /** Total tokens consumed by returned entries. */
+    tokensUsed: number;
+    /** Tokens remaining from the original budget. */
+    tokensRemaining: number;
+    /** Number of entries excluded due to budget constraints. */
+    excluded: number;
+}
+/**
+ * Budget-aware hybrid retrieval combining FTS5, vector KNN, and graph neighbor scores.
+ *
+ * Strategy (parallel where possible):
+ *   A. FTS5 BM25 search (always)  — keyword precision (50% weight)
+ *   B. Vector KNN search (optional) — semantic recall (40% weight, skipped if no embeddings)
+ *   C. Graph neighbors (optional) — associative context (10% weight, skipped if graph empty)
+ *
+ * Score fusion: final = (fts*0.50 + vec*0.40 + graph*0.10) × qualityScore
+ * Recency boost: +0.05 for entries updated in last 7 days.
+ * Type priority: procedural entries get +0.10 (always-useful rules).
+ *
+ * Budget enforcement:
+ *   - Rank top-50 candidates by fused score.
+ *   - Walk list, accumulate token cost (≈ textLen/4), stop at budget.
+ *   - Episodic entries dropped first when budget is tight.
+ *
+ * Citation tracking: increments citationCount for returned entries in background (setImmediate).
+ *
+ * @param projectRoot - Project root directory
+ * @param query - Text to search for
+ * @param tokenBudget - Maximum tokens to spend on results (default 500)
+ * @param options - Optional filters (types, tiers, verified)
+ * @returns Retrieved entries within budget with token accounting
+ */
+export declare function retrieveWithBudget(projectRoot: string, query: string, tokenBudget?: number, options?: BudgetedRetrievalOptions): Promise<BudgetedResult>;
 //# sourceMappingURL=brain-retrieval.d.ts.map

package/dist/memory/brain-retrieval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain-retrieval.d.ts","sourceRoot":"","sources":["../../src/memory/brain-retrieval.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"brain-retrieval.d.ts","sourceRoot":"","sources":["../../src/memory/brain-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,KAAK,EACV,8BAA8B,EAC9B,uBAAuB,EAEvB,qBAAqB,EACtB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,sBAAsB,CAAC;AAU9B,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,CAAC;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qCAAqC;AACrC,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,oCAAoC;AACpC,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,2CAA2C;AAC3C,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzF,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AAED,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAyFnC;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAkH9B;AAMD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAoFlC;AAmCD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CA4L7B;AAwCD,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAuDnC;AAMD,0CAA0C;AAC1C,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,WAAW,SAAM,EACjB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,cAAc,CAAC,CA2RzB"}