claude-cognitive 0.3.2 → 0.4.0

package/dist/feedback/index.js

@@ -0,0 +1,194 @@
+/**
+ * Memory Feedback Loop Module
+ *
+ * Provides a closed-loop feedback system that:
+ * 1. Tracks which recalled facts Claude actually uses
+ * 2. Scores facts based on usefulness signals
+ * 3. Prepares feedback for Hindsight API
+ *
+ * @module feedback
+ */
+import { DEFAULT_FEEDBACK_CONFIG } from "./constants.js";
+import { trackRecall, loadRecallSession, getSessionStats, } from "./tracker.js";
+import { runDetectionPipeline } from "./detector.js";
+import { aggregateDetections, summarizeFeedback, prepareFeedback, } from "./scorer.js";
+// =============================================================================
+// Re-exports
+// =============================================================================
+// Constants
+export { EXPLICIT_CONFIDENCE, SEMANTIC_THRESHOLD, SEMANTIC_MAX_CONFIDENCE, BEHAVIORAL_CONFIDENCE_BASE, USED_THRESHOLD, IGNORED_THRESHOLD, EXPLICIT_TRIGGERS, FILE_REFERENCE_PATTERNS, DEFAULT_FEEDBACK_CONFIG, SESSION_DATA_RETENTION_DAYS, } from "./constants.js";
+// Tracker
+export { createRecallSession, addRecalledFacts, saveRecallSession, loadRecallSession, trackRecall, cleanupOldSessions, getSessionStats, getRecallSessionPath, getSessionActivityDir, } from "./tracker.js";
+// Detector
+export { detectExplicitReferences, detectSemanticMatches, detectBehavioralSignals, detectNegativeSignals, runDetectionPipeline, extractFileReferences, extractTopics, } from "./detector.js";
+// Scorer
+export { aggregateDetections, calculateVerdict, prepareFeedback, summarizeFeedback, filterHighConfidence, getDetectionBreakdown, } from "./scorer.js";
+// Similarity
+export { calculateSimilarity, jaccardSimilarity } from "./similarity.js";
+/**
+ * FeedbackService - Main facade class for the feedback loop
+ *
+ * Provides a high-level interface for:
+ * - Tracking recall sessions
+ * - Processing feedback at session end
+ * - Viewing statistics and patterns
+ */
+export class FeedbackService {
+    projectDir;
+    config;
+    /**
+     * Create a new FeedbackService
+     */
+    constructor(config, projectDir) {
+        this.projectDir = projectDir;
+        this.config = { ...DEFAULT_FEEDBACK_CONFIG, ...config };
+    }
+    /**
+     * Check if feedback loop is enabled
+     */
+    isEnabled() {
+        return this.config.enabled === true;
+    }
+    /**
+     * Track a recall operation
+     */
+    async trackRecall(sessionId, query, facts) {
+        if (!this.isEnabled()) {
+            return { success: false, reason: "Feedback loop disabled" };
+        }
+        try {
+            const session = await trackRecall({
+                sessionId,
+                projectDir: this.projectDir,
+                query,
+                facts,
+            });
+            return {
+                success: true,
+                sessionId: session.sessionId,
+                factsTracked: session.totalFacts,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Process feedback for a session
+     */
+    async processFeedback(sessionId, options = {}) {
+        if (!this.isEnabled()) {
+            return {
+                success: false,
+                sessionId,
+                reason: "Feedback loop disabled",
+                summary: createEmptySummary(),
+                factScores: [],
+                feedback: [],
+            };
+        }
+        try {
+            // Load recall session
+            const recallSession = await loadRecallSession(sessionId, this.projectDir);
+            if (!recallSession) {
+                return {
+                    success: false,
+                    sessionId,
+                    reason: "No recall session found for this session ID",
+                    summary: createEmptySummary(),
+                    factScores: [],
+                    feedback: [],
+                };
+            }
+            // Run detection pipeline
+            const detections = runDetectionPipeline(options.conversationText || null, options.sessionActivity || null, recallSession.factsRecalled, this.config.detection || {});
+            // Aggregate scores
+            const factScores = aggregateDetections(detections);
+            // Get summary
+            const summary = summarizeFeedback(factScores);
+            // Prepare feedback for API (if enabled)
+            let feedback = [];
+            if (this.config.hindsight?.sendFeedback) {
+                feedback = prepareFeedback(factScores, recallSession.recall.query);
+            }
+            return {
+                success: true,
+                sessionId,
+                summary,
+                factScores,
+                feedback,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+                summary: createEmptySummary(),
+                factScores: [],
+                feedback: [],
+            };
+        }
+    }
+    /**
+     * Get feedback statistics for the project
+     */
+    async getStats() {
+        try {
+            const sessionStats = await getSessionStats(this.projectDir);
+            return {
+                success: true,
+                enabled: this.isEnabled(),
+                ...sessionStats,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                enabled: this.isEnabled(),
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+function createEmptySummary() {
+    return {
+        total: 0,
+        used: 0,
+        ignored: 0,
+        uncertain: 0,
+        usageRate: 0,
+        avgUsedConfidence: 0,
+        avgIgnoredConfidence: 0,
+        topUsed: [],
+        topIgnored: [],
+    };
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a new FeedbackService instance
+ */
+export function createFeedbackService(config, projectDir) {
+    return new FeedbackService(config, projectDir);
+}
+//# sourceMappingURL=index.js.map

package/dist/feedback/index.js.map

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

package/dist/feedback/offline-queue.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Offline feedback signal queue for degraded mode.
+ * Stores feedback signals locally when Hindsight is unavailable.
+ * Auto-syncs to Hindsight when connection is restored.
+ * @module feedback/offline-queue
+ */
+import type { SignalItem } from "../types.js";
+/**
+ * A feedback signal stored offline with queue metadata.
+ */
+export interface OfflineSignal extends SignalItem {
+    /** Local queue ID */
+    id: string;
+    /** When queued (ISO 8601) */
+    queuedAt: string;
+    /** Whether this has been synced to Hindsight */
+    synced: boolean;
+}
+/**
+ * Options for OfflineFeedbackQueue.
+ */
+export interface OfflineFeedbackQueueOptions {
+    /** Project root directory */
+    projectPath: string;
+    /** Custom storage file path (default: .claude/offline-feedback.json) */
+    storagePath?: string;
+}
+/**
+ * Queue statistics.
+ */
+export interface QueueStats {
+    /** Total signals in queue */
+    total: number;
+    /** Signals pending sync */
+    pending: number;
+    /** Signals already synced */
+    synced: number;
+    /** Last sync attempt */
+    lastSyncAttempt?: string;
+    /** Last successful sync */
+    lastSyncSuccess?: string;
+}
+/**
+ * Local file-based feedback signal queue for offline/degraded mode.
+ */
+export declare class OfflineFeedbackQueue {
+    private readonly filePath;
+    private store;
+    constructor(options: OfflineFeedbackQueueOptions);
+    /**
+     * Get the storage file path.
+     */
+    getFilePath(): string;
+    /**
+     * Load the store from disk.
+     */
+    private load;
+    /**
+     * Save the store to disk.
+     */
+    private save;
+    /**
+     * Generate a unique ID for queued signals.
+     */
+    private generateId;
+    /**
+     * Queue a single feedback signal.
+     * @returns The queue ID assigned to this signal
+     */
+    enqueue(signal: SignalItem): Promise<string>;
+    /**
+     * Queue multiple feedback signals atomically.
+     * @returns Array of queue IDs assigned to the signals
+     */
+    enqueueBatch(signals: SignalItem[]): Promise<string[]>;
+    /**
+     * Get all unsynced signals.
+     */
+    getUnsynced(): Promise<OfflineSignal[]>;
+    /**
+     * Mark signals as synced.
+     */
+    markSynced(ids: string[]): Promise<void>;
+    /**
+     * Record a sync attempt (even if it failed).
+     */
+    recordSyncAttempt(): Promise<void>;
+    /**
+     * Clear all synced signals to save space.
+     * @returns Number of signals cleared
+     */
+    clearSynced(): Promise<number>;
+    /**
+     * Get signal count.
+     */
+    count(): Promise<number>;
+    /**
+     * Get queue statistics.
+     */
+    getStats(): Promise<QueueStats>;
+    /**
+     * Clear all signals.
+     */
+    clear(): Promise<void>;
+    /**
+     * Convert OfflineSignal to SignalItem (strip queue metadata).
+     */
+    static toSignalItem(offline: OfflineSignal): SignalItem;
+}
+//# sourceMappingURL=offline-queue.d.ts.map

package/dist/feedback/offline-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-queue.d.ts","sourceRoot":"","sources":["../../src/feedback/offline-queue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;CACjB;AAgBD;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAkC;gBAEnC,OAAO,EAAE,2BAA2B;IAMhD;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;YACW,IAAI;IAmBlB;;OAEG;YACW,IAAI;IAalB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBlD;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuB5D;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAK7C;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxC;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAQpC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAsBrC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU;CAKxD"}

package/dist/feedback/offline-queue.js

@@ -0,0 +1,188 @@
+/**
+ * Offline feedback signal queue for degraded mode.
+ * Stores feedback signals locally when Hindsight is unavailable.
+ * Auto-syncs to Hindsight when connection is restored.
+ * @module feedback/offline-queue
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Local file-based feedback signal queue for offline/degraded mode.
+ */
+export class OfflineFeedbackQueue {
+    filePath;
+    store = null;
+    constructor(options) {
+        this.filePath =
+            options.storagePath ??
+                join(options.projectPath, ".claude", "offline-feedback.json");
+    }
+    /**
+     * Get the storage file path.
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+    /**
+     * Load the store from disk.
+     */
+    async load() {
+        if (this.store) {
+            return this.store;
+        }
+        try {
+            const content = await readFile(this.filePath, "utf-8");
+            this.store = JSON.parse(content);
+        }
+        catch {
+            // File doesn't exist or is invalid - create empty store
+            this.store = {
+                version: 1,
+                signals: [],
+            };
+        }
+        return this.store;
+    }
+    /**
+     * Save the store to disk.
+     */
+    async save() {
+        if (!this.store)
+            return;
+        // Ensure directory exists
+        await mkdir(dirname(this.filePath), { recursive: true });
+        await writeFile(this.filePath, JSON.stringify(this.store, null, 2), "utf-8");
+    }
+    /**
+     * Generate a unique ID for queued signals.
+     */
+    generateId() {
+        return `signal-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    }
+    /**
+     * Queue a single feedback signal.
+     * @returns The queue ID assigned to this signal
+     */
+    async enqueue(signal) {
+        const store = await this.load();
+        const offlineSignal = {
+            ...signal,
+            id: this.generateId(),
+            queuedAt: new Date().toISOString(),
+            synced: false,
+        };
+        store.signals.push(offlineSignal);
+        await this.save();
+        return offlineSignal.id;
+    }
+    /**
+     * Queue multiple feedback signals atomically.
+     * @returns Array of queue IDs assigned to the signals
+     */
+    async enqueueBatch(signals) {
+        if (signals.length === 0) {
+            return [];
+        }
+        const store = await this.load();
+        const ids = [];
+        for (const signal of signals) {
+            const offlineSignal = {
+                ...signal,
+                id: this.generateId(),
+                queuedAt: new Date().toISOString(),
+                synced: false,
+            };
+            store.signals.push(offlineSignal);
+            ids.push(offlineSignal.id);
+        }
+        await this.save();
+        return ids;
+    }
+    /**
+     * Get all unsynced signals.
+     */
+    async getUnsynced() {
+        const store = await this.load();
+        return store.signals.filter((s) => !s.synced);
+    }
+    /**
+     * Mark signals as synced.
+     */
+    async markSynced(ids) {
+        const store = await this.load();
+        const idSet = new Set(ids);
+        for (const signal of store.signals) {
+            if (idSet.has(signal.id)) {
+                signal.synced = true;
+            }
+        }
+        store.lastSyncSuccess = new Date().toISOString();
+        await this.save();
+    }
+    /**
+     * Record a sync attempt (even if it failed).
+     */
+    async recordSyncAttempt() {
+        const store = await this.load();
+        store.lastSyncAttempt = new Date().toISOString();
+        await this.save();
+    }
+    /**
+     * Clear all synced signals to save space.
+     * @returns Number of signals cleared
+     */
+    async clearSynced() {
+        const store = await this.load();
+        const before = store.signals.length;
+        store.signals = store.signals.filter((s) => !s.synced);
+        await this.save();
+        return before - store.signals.length;
+    }
+    /**
+     * Get signal count.
+     */
+    async count() {
+        const store = await this.load();
+        return store.signals.length;
+    }
+    /**
+     * Get queue statistics.
+     */
+    async getStats() {
+        const store = await this.load();
+        const pending = store.signals.filter((s) => !s.synced).length;
+        const synced = store.signals.filter((s) => s.synced).length;
+        const stats = {
+            total: store.signals.length,
+            pending,
+            synced,
+        };
+        // Only include optional properties if they have values
+        if (store.lastSyncAttempt !== undefined) {
+            stats.lastSyncAttempt = store.lastSyncAttempt;
+        }
+        if (store.lastSyncSuccess !== undefined) {
+            stats.lastSyncSuccess = store.lastSyncSuccess;
+        }
+        return stats;
+    }
+    /**
+     * Clear all signals.
+     */
+    async clear() {
+        this.store = {
+            version: 1,
+            signals: [],
+        };
+        await this.save();
+    }
+    /**
+     * Convert OfflineSignal to SignalItem (strip queue metadata).
+     */
+    static toSignalItem(offline) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { id, queuedAt, synced, ...signal } = offline;
+        return signal;
+    }
+}
+//# sourceMappingURL=offline-queue.js.map

package/dist/feedback/offline-queue.js.map

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

package/dist/feedback/scorer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Feedback Scorer
+ *
+ * Aggregates detection results into final fact scores and prepares
+ * feedback for storage/API submission.
+ *
+ * @module feedback/scorer
+ */
+import type { Detection, DetectionResults } from "./detector.js";
+import type { SignalItem } from "../types.js";
+export type Verdict = "used" | "ignored" | "uncertain";
+export interface FactScore {
+    factId: string;
+    verdict: Verdict;
+    confidence: number;
+    scores: {
+        used: number;
+        ignored: number;
+    };
+    detections: Array<Detection | {
+        detectionType: string;
+        confidence: number;
+        evidence: unknown;
+    }>;
+}
+export interface FeedbackSummary {
+    total: number;
+    used: number;
+    ignored: number;
+    uncertain: number;
+    usageRate: number;
+    avgUsedConfidence: number;
+    avgIgnoredConfidence: number;
+    topUsed: Array<{
+        factId: string;
+        confidence: number;
+        detectionTypes: string[];
+    }>;
+    topIgnored: Array<{
+        factId: string;
+        confidence: number;
+    }>;
+}
+export interface FeedbackResult {
+    success: boolean;
+    sessionId: string;
+    summary: FeedbackSummary;
+    factScores: FactScore[];
+    feedback: SignalItem[];
+    error?: string;
+    reason?: string;
+}
+/**
+ * Aggregate all detections into final fact scores
+ */
+export declare function aggregateDetections(detections: DetectionResults): FactScore[];
+/**
+ * Calculate verdict for a fact based on used and ignored scores
+ */
+export declare function calculateVerdict(usedScore: number, ignoredScore: number): {
+    verdict: Verdict;
+    confidence: number;
+};
+/**
+ * Prepare feedback for Hindsight API submission
+ * Sanitizes data to ensure no sensitive information is included
+ */
+export declare function prepareFeedback(factScores: FactScore[], query: string): SignalItem[];
+/**
+ * Create a summary of feedback results
+ */
+export declare function summarizeFeedback(factScores: FactScore[]): FeedbackSummary;
+/**
+ * Filter feedback to only high-confidence results
+ */
+export declare function filterHighConfidence(factScores: FactScore[], minConfidence?: number): FactScore[];
+/**
+ * Get detection type breakdown
+ */
+export declare function getDetectionBreakdown(factScores: FactScore[]): Record<string, number>;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/feedback/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../src/feedback/scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,KAAK,CAAC,SAAS,GAAG;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACjG;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC,CAAC;IACH,UAAU,EAAE,KAAK,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,EAAE,CAiE7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAkB1C;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,SAAS,EAAE,EACvB,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CASd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,eAAe,CAgE1E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,EAAE,EACvB,aAAa,SAAM,GAClB,SAAS,EAAE,CAIb;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBrF"}