@psiclawops/hypermem 0.9.1 → 0.9.2

package/dist/metrics-dashboard.d.ts

@@ -0,0 +1,131 @@
+/**
+ * hypermem Metrics Dashboard
+ *
+ * Provides a unified surface for observing system health:
+ * - Memory counts (facts, pages, episodes, vectors)
+ * - Composition performance (avg assembly time, budget utilization)
+ * - Ingestion stats (indexer throughput, promotion rate)
+ * - Embedding stats (cache hit rate, Ollama availability)
+ *
+ * All queries are read-only and safe to call on hot DBs.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface FactMetrics {
+    /** Total facts indexed across all agents */
+    totalFacts: number;
+    /** Facts per agent breakdown */
+    byAgent: Record<string, number>;
+    /** Facts added in the last 24h */
+    recentFacts: number;
+}
+export interface WikiMetrics {
+    /** Total synthesized wiki pages (non-superseded) */
+    totalPages: number;
+    /** Pages per agent */
+    byAgent: Record<string, number>;
+    /** Pages synthesized in the last 24h */
+    recentPages: number;
+    /** Oldest page age in hours (staleness indicator) */
+    oldestPageAgeHours: number | null;
+}
+export interface EpisodeMetrics {
+    /** Total episodes stored */
+    totalEpisodes: number;
+    /** Episodes per agent */
+    byAgent: Record<string, number>;
+    /** Average episode significance score (0-1) */
+    avgSignificance: number | null;
+}
+export interface VectorMetrics {
+    /** Total vectors indexed */
+    totalVectors: number;
+    /** Breakdown by source table */
+    byTable: Record<string, number>;
+    /** Embedding cache hit rate (0-1) for this process lifetime */
+    cacheHitRate: number | null;
+}
+export interface DocChunkMetrics {
+    /** Total doc chunks indexed across all collections */
+    totalDocChunks: number;
+    /** Doc chunks per collection */
+    byCollection: Record<string, number>;
+    /** Doc chunks added in the last 24h */
+    recentDocChunks: number;
+}
+export interface CompositionMetrics {
+    /** Average assembly time in ms (from output_metrics table) */
+    avgAssemblyMs: number | null;
+    /** p95 assembly time in ms */
+    p95AssemblyMs: number | null;
+    /** Average output tokens per turn */
+    avgOutputTokens: number | null;
+    /** Average input tokens per turn (context size) */
+    avgInputTokens: number | null;
+    /** Number of turns recorded */
+    totalTurns: number;
+    /** Average cache read tokens (Anthropic prompt cache utilization) */
+    avgCacheReadTokens: number | null;
+}
+export interface IngestionMetrics {
+    /** Total messages processed by the background indexer */
+    totalMessagesIndexed: number;
+    /** Total facts extracted */
+    totalFactsExtracted: number;
+    /** Noise rejection rate (1 - facts/messages, approximate) */
+    noiseRejectionRate: number | null;
+    /** Total episodes created */
+    totalEpisodesCreated: number;
+    /** Total knowledge items promoted by dreaming promoter */
+    totalKnowledgePromoted: number;
+}
+export interface SystemHealth {
+    /** Whether the main DB is readable */
+    mainDbOk: boolean;
+    /** Whether the library DB is readable */
+    libraryDbOk: boolean;
+    /** Main DB schema version */
+    mainSchemaVersion: number | null;
+    /** Library DB schema version */
+    librarySchemaVersion: number | null;
+    /** hypermem package version */
+    packageVersion: string;
+    /** Resolved embedding provider from the installed config */
+    embeddingProvider: string | null;
+    /** Resolved embedding model from the installed config */
+    embeddingModel: string | null;
+    /** Cache connection status (if provided) */
+    cacheOk: boolean | null;
+    /** Timestamp of this snapshot */
+    snapshotAt: string;
+}
+export interface HyperMemMetrics {
+    facts: FactMetrics;
+    docChunks: DocChunkMetrics;
+    wiki: WikiMetrics;
+    episodes: EpisodeMetrics;
+    vectors: VectorMetrics;
+    composition: CompositionMetrics;
+    ingestion: IngestionMetrics;
+    health: SystemHealth;
+}
+export interface MetricsDashboardOptions {
+    /** Agent IDs to scope to. If omitted, returns fleet-wide metrics. */
+    agentIds?: string[];
+    /** Include per-agent breakdowns. Default: true */
+    includeBreakdowns?: boolean;
+    /** Resolved embedding provider for health display. */
+    embeddingProvider?: string | null;
+    /** Resolved embedding model for health display. */
+    embeddingModel?: string | null;
+}
+/**
+ * Collect all metrics in a single pass.
+ * Safe to call on live DBs — all queries are read-only.
+ */
+export declare function collectMetrics(mainDb: DatabaseSync, libraryDb: DatabaseSync, opts?: MetricsDashboardOptions, vectorDb?: DatabaseSync | null): Promise<HyperMemMetrics>;
+/**
+ * Format metrics as a human-readable summary string.
+ * Suitable for logging or status replies.
+ */
+export declare function formatMetricsSummary(m: HyperMemMetrics): string;
+//# sourceMappingURL=metrics-dashboard.d.ts.map

package/dist/metrics-dashboard.d.ts.map

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

package/dist/metrics-dashboard.js

@@ -0,0 +1,298 @@
+/**
+ * hypermem Metrics Dashboard
+ *
+ * Provides a unified surface for observing system health:
+ * - Memory counts (facts, pages, episodes, vectors)
+ * - Composition performance (avg assembly time, budget utilization)
+ * - Ingestion stats (indexer throughput, promotion rate)
+ * - Embedding stats (cache hit rate, Ollama availability)
+ *
+ * All queries are read-only and safe to call on hot DBs.
+ */
+import { HYPERMEM_COMPAT_VERSION } from './version.js';
+function safeQuery(db, sql, params = []) {
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.get(...params);
+    }
+    catch {
+        return null;
+    }
+}
+function safeQueryAll(db, sql, params = []) {
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.all(...params);
+    }
+    catch {
+        return [];
+    }
+}
+function buildAgentFilter(agentIds) {
+    if (!agentIds || agentIds.length === 0)
+        return { clause: '', params: [] };
+    const placeholders = agentIds.map(() => '?').join(', ');
+    return { clause: `AND agent_id IN (${placeholders})`, params: agentIds };
+}
+/**
+ * Collect fact metrics from the library DB.
+ */
+function collectFactMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, params);
+    const recent = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE created_at > ? ${clause}`, [cutoff, ...params]);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM facts WHERE 1=1 ${clause} GROUP BY agent_id`, params)
+        : [];
+    return {
+        totalFacts: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        recentFacts: recent?.count ?? 0,
+    };
+}
+/**
+ * Collect doc chunk metrics from the library DB.
+ */
+function collectDocChunkMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM doc_chunks WHERE 1=1 ${clause}`, params);
+    const recent = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM doc_chunks WHERE created_at > ? ${clause}`, [cutoff, ...params]);
+    const byCollectionRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT collection, COUNT(*) AS count FROM doc_chunks WHERE 1=1 ${clause} GROUP BY collection`, params)
+        : [];
+    return {
+        totalDocChunks: total?.count ?? 0,
+        byCollection: Object.fromEntries(byCollectionRows.map(r => [r.collection, r.count])),
+        recentDocChunks: recent?.count ?? 0,
+    };
+}
+/**
+ * Collect wiki page metrics from the library DB (knowledge table, topic-synthesis domain).
+ */
+function collectWikiMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause}`, params);
+    const recent = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL AND created_at > ? ${clause}`, [cutoff, ...params]);
+    const oldest = safeQuery(libraryDb, `SELECT created_at FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause} ORDER BY created_at ASC LIMIT 1`, params);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause} GROUP BY agent_id`, params)
+        : [];
+    let oldestPageAgeHours = null;
+    if (oldest?.created_at) {
+        const diffMs = Date.now() - new Date(oldest.created_at).getTime();
+        oldestPageAgeHours = Math.round(diffMs / (1000 * 60 * 60));
+    }
+    return {
+        totalPages: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        recentPages: recent?.count ?? 0,
+        oldestPageAgeHours,
+    };
+}
+/**
+ * Collect episode metrics from the library DB.
+ */
+function collectEpisodeMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM episodes WHERE 1=1 ${clause}`, params);
+    const avgSig = safeQuery(libraryDb, `SELECT AVG(significance) AS avg FROM episodes WHERE significance IS NOT NULL ${clause}`, params);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM episodes WHERE 1=1 ${clause} GROUP BY agent_id`, params)
+        : [];
+    return {
+        totalEpisodes: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        avgSignificance: avgSig?.avg ?? null,
+    };
+}
+/**
+ * Collect vector index metrics from the shared vectors DB.
+ */
+function collectVectorMetrics(vectorDb) {
+    if (!vectorDb) {
+        return {
+            totalVectors: 0,
+            byTable: {},
+            cacheHitRate: null,
+        };
+    }
+    const total = safeQuery(vectorDb, 'SELECT COUNT(*) as cnt FROM vec_index_map');
+    const byTableRows = safeQueryAll(vectorDb, 'SELECT source_table, COUNT(*) as cnt FROM vec_index_map GROUP BY source_table');
+    return {
+        totalVectors: total?.cnt ?? 0,
+        byTable: Object.fromEntries(byTableRows.map(r => [r.source_table, r.cnt])),
+        cacheHitRate: null, // process-lifetime stat, not persisted
+    };
+}
+/**
+ * Collect composition performance metrics from the output_metrics table (library DB).
+ */
+function collectCompositionMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const agg = safeQuery(libraryDb, `SELECT
+       AVG(latency_ms) AS avg_latency,
+       AVG(output_tokens) AS avg_output,
+       AVG(input_tokens) AS avg_input,
+       AVG(cache_read_tokens) AS avg_cache,
+       COUNT(*) AS total
+     FROM output_metrics WHERE 1=1 ${clause.replace(/agent_id/g, 'agent_id')}`, params);
+    // p95: sort latency_ms and pick the 95th percentile row
+    let p95 = null;
+    if ((agg?.total ?? 0) > 0) {
+        const p95Row = safeQuery(libraryDb, `SELECT latency_ms FROM output_metrics WHERE latency_ms IS NOT NULL ${clause}
+       ORDER BY latency_ms ASC
+       LIMIT 1 OFFSET MAX(0, CAST(COUNT(*) * 0.95 AS INT) - 1)`, params);
+        // Fallback: approximate p95 with a subquery
+        if (!p95Row) {
+            const p95Approx = safeQuery(libraryDb, `SELECT latency_ms FROM output_metrics WHERE latency_ms IS NOT NULL ${clause}
+         ORDER BY latency_ms DESC
+         LIMIT 1 OFFSET (SELECT MAX(0, CAST(COUNT(*) * 0.05 AS INT)) FROM output_metrics WHERE latency_ms IS NOT NULL ${clause})`, [...params, ...params]);
+            p95 = p95Approx?.latency_ms ?? null;
+        }
+        else {
+            p95 = p95Row.latency_ms;
+        }
+    }
+    return {
+        avgAssemblyMs: agg?.avg_latency ? Math.round(agg.avg_latency) : null,
+        p95AssemblyMs: p95 ? Math.round(p95) : null,
+        avgOutputTokens: agg?.avg_output ? Math.round(agg.avg_output) : null,
+        avgInputTokens: agg?.avg_input ? Math.round(agg.avg_input) : null,
+        totalTurns: agg?.total ?? 0,
+        avgCacheReadTokens: agg?.avg_cache ? Math.round(agg.avg_cache) : null,
+    };
+}
+/**
+ * Collect ingestion pipeline metrics from the library DB.
+ */
+function collectIngestionMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const facts = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, params);
+    const episodes = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM episodes WHERE 1=1 ${clause}`, params);
+    const knowledge = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE superseded_by IS NULL ${clause}`, params);
+    const totalFacts = facts?.count ?? 0;
+    const totalEpisodes = episodes?.count ?? 0;
+    // Noise rejection: approximate from fact vs message ratio if messages available
+    const messages = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, // placeholder — we'd need message count from main
+    params);
+    return {
+        totalMessagesIndexed: 0, // requires main DB join — surfaced separately
+        totalFactsExtracted: totalFacts,
+        noiseRejectionRate: null, // requires cross-DB join
+        totalEpisodesCreated: totalEpisodes,
+        totalKnowledgePromoted: knowledge?.count ?? 0,
+    };
+}
+/**
+ * Collect system health from both DBs.
+ */
+function collectHealth(mainDb, libraryDb, opts) {
+    let mainSchemaVersion = null;
+    let librarySchemaVersion = null;
+    let mainDbOk = false;
+    let libraryDbOk = false;
+    try {
+        const row = safeQuery(mainDb, 'SELECT schema_version FROM _meta LIMIT 1');
+        mainSchemaVersion = row?.schema_version ?? null;
+        mainDbOk = true;
+    }
+    catch { /* empty */ }
+    try {
+        const row = safeQuery(libraryDb, 'SELECT schema_version FROM _library_meta LIMIT 1');
+        librarySchemaVersion = row?.schema_version ?? null;
+        libraryDbOk = true;
+    }
+    catch { /* empty */ }
+    return {
+        mainDbOk,
+        libraryDbOk,
+        mainSchemaVersion,
+        librarySchemaVersion,
+        packageVersion: HYPERMEM_COMPAT_VERSION,
+        embeddingProvider: opts.embeddingProvider ?? null,
+        embeddingModel: opts.embeddingModel ?? null,
+        cacheOk: null, // caller must inject cache status
+        snapshotAt: new Date().toISOString(),
+    };
+}
+/**
+ * Collect all metrics in a single pass.
+ * Safe to call on live DBs — all queries are read-only.
+ */
+export async function collectMetrics(mainDb, libraryDb, opts = {}, vectorDb = null) {
+    return {
+        facts: collectFactMetrics(libraryDb, opts),
+        docChunks: collectDocChunkMetrics(libraryDb, opts),
+        wiki: collectWikiMetrics(libraryDb, opts),
+        episodes: collectEpisodeMetrics(libraryDb, opts),
+        vectors: collectVectorMetrics(vectorDb),
+        composition: collectCompositionMetrics(libraryDb, opts),
+        ingestion: collectIngestionMetrics(libraryDb, opts),
+        health: collectHealth(mainDb, libraryDb, opts),
+    };
+}
+/**
+ * Format metrics as a human-readable summary string.
+ * Suitable for logging or status replies.
+ */
+export function formatMetricsSummary(m) {
+    const lines = [];
+    lines.push(`hypermem ${m.health.packageVersion} — metrics snapshot ${m.health.snapshotAt}`);
+    lines.push('');
+    lines.push('## Memory');
+    lines.push(`  facts:    ${m.facts.totalFacts.toLocaleString()} total, ${m.facts.recentFacts} added last 24h`);
+    lines.push(`  doc chunks: ${m.docChunks.totalDocChunks.toLocaleString()} total, ${m.docChunks.recentDocChunks} added last 24h`);
+    if (Object.keys(m.docChunks.byCollection).length > 0) {
+        for (const [collection, count] of Object.entries(m.docChunks.byCollection)) {
+            lines.push(`    ${collection}: ${count.toLocaleString()}`);
+        }
+    }
+    lines.push(`  wiki:     ${m.wiki.totalPages} pages, ${m.wiki.recentPages} synthesized last 24h${m.wiki.oldestPageAgeHours !== null ? `, oldest ${m.wiki.oldestPageAgeHours}h` : ''}`);
+    lines.push(`  episodes: ${m.episodes.totalEpisodes.toLocaleString()}${m.episodes.avgSignificance !== null ? `, avg significance ${m.episodes.avgSignificance.toFixed(2)}` : ''}`);
+    lines.push(`  vectors:  ${m.vectors.totalVectors.toLocaleString()} indexed`);
+    if (Object.keys(m.vectors.byTable).length > 0) {
+        for (const [table, count] of Object.entries(m.vectors.byTable)) {
+            lines.push(`    ${table}: ${count.toLocaleString()}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Embedding');
+    lines.push(`  provider: ${m.health.embeddingProvider ?? 'unknown'}`);
+    lines.push(`  model:    ${m.health.embeddingModel ?? 'unknown'}`);
+    lines.push('');
+    lines.push('## Composition');
+    if (m.composition.totalTurns > 0) {
+        lines.push(`  turns:    ${m.composition.totalTurns.toLocaleString()}`);
+        if (m.composition.avgAssemblyMs !== null)
+            lines.push(`  avg time: ${m.composition.avgAssemblyMs}ms`);
+        if (m.composition.p95AssemblyMs !== null)
+            lines.push(`  p95 time: ${m.composition.p95AssemblyMs}ms`);
+        if (m.composition.avgOutputTokens !== null)
+            lines.push(`  avg out:  ${m.composition.avgOutputTokens} tokens`);
+        if (m.composition.avgInputTokens !== null)
+            lines.push(`  avg in:   ${m.composition.avgInputTokens} tokens`);
+        if (m.composition.avgCacheReadTokens !== null)
+            lines.push(`  cache rd: ${m.composition.avgCacheReadTokens} tokens/turn`);
+    }
+    else {
+        lines.push('  no turn data yet');
+    }
+    lines.push('');
+    lines.push('## Ingestion');
+    lines.push(`  facts extracted:    ${m.ingestion.totalFactsExtracted.toLocaleString()}`);
+    lines.push(`  episodes created:   ${m.ingestion.totalEpisodesCreated.toLocaleString()}`);
+    lines.push(`  knowledge promoted: ${m.ingestion.totalKnowledgePromoted.toLocaleString()}`);
+    lines.push('');
+    lines.push('## Health');
+    lines.push(`  embedding: ${m.health.embeddingProvider ?? 'unknown'}${m.health.embeddingModel ? ` / ${m.health.embeddingModel}` : ''}`);
+    lines.push(`  main db:    ${m.health.mainDbOk ? '✅' : '❌'}${m.health.mainSchemaVersion !== null ? ` (schema v${m.health.mainSchemaVersion})` : ''}`);
+    lines.push(`  library db: ${m.health.libraryDbOk ? '✅' : '❌'}${m.health.librarySchemaVersion !== null ? ` (schema v${m.health.librarySchemaVersion})` : ''}`);
+    if (m.health.cacheOk !== null) {
+        lines.push(`  cache:      ${m.health.cacheOk ? '✅' : '❌'}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=metrics-dashboard.js.map

package/dist/obsidian-exporter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * obsidian-exporter.ts
+ *
+ * Exports hypermem facts and wiki pages to an Obsidian vault.
+ * Complements obsidian-watcher.ts (import direction).
+ *
+ * Output format:
+ *   - Wiki pages → one .md file per topic, with frontmatter + [[wikilinks]]
+ *   - Facts → grouped by domain into .md files, frontmatter-tagged
+ *   - Index note → _hypermem-index.md with TOC and stats
+ *
+ * Safe to run repeatedly — existing files are overwritten only if content changed.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ObsidianExportConfig {
+    /** Absolute path to target Obsidian vault directory */
+    vaultPath: string;
+    /** Sub-folder inside vault to write hypermem exports. Default: 'hypermem' */
+    vaultFolder?: string;
+    /** Agent ID to scope export to. If omitted, exports all agents */
+    agentId?: string;
+    /** Include raw facts (not just wiki pages). Default: true */
+    includeFacts?: boolean;
+    /** Include synthesized wiki pages. Default: true */
+    includeWikiPages?: boolean;
+    /** Include an index note. Default: true */
+    includeIndex?: boolean;
+    /** Tag prefix added to all exported notes. Default: 'hypermem' */
+    tagPrefix?: string;
+    /** Skip files whose content hasn't changed. Default: true */
+    skipUnchanged?: boolean;
+}
+export interface ObsidianExportResult {
+    written: number;
+    skipped: number;
+    errors: string[];
+    outputDir: string;
+    files: string[];
+}
+/**
+ * Export hypermem memories to an Obsidian vault.
+ *
+ * @param mainDb - hypermem main DB (facts, episodes)
+ * @param libraryDb - hypermem library DB (knowledge, wiki pages)
+ * @param config - export config
+ * @returns ObsidianExportResult with counts and file list
+ *
+ * @example
+ * const result = await exportToVault(mainDb, libraryDb, {
+ *   vaultPath: '/Users/me/obsidian/my-vault',
+ *   agentId: 'main',
+ *   tagPrefix: 'hypermem',
+ * });
+ * console.log(`Wrote ${result.written} files to ${result.outputDir}`);
+ */
+export declare function exportToVault(mainDb: DatabaseSync, libraryDb: DatabaseSync, config: ObsidianExportConfig): ObsidianExportResult;
+//# sourceMappingURL=obsidian-exporter.d.ts.map

package/dist/obsidian-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obsidian-exporter.d.ts","sourceRoot":"","sources":["../src/obsidian-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA8SD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAiCtB"}