sxng-cli 1.0.9 → 1.1.0

package/dist/deep/graph-obfuscate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Entity obfuscation (MTG-inspired) for knowledge graph.
+ *
+ * Primary flow: Agent (LLM) generates obfuscated labels.
+ * Fallback flow: simple rule-based obfuscation (experimental).
+ *
+ * The `graph-obfuscate` command outputs candidate entities for obfuscation,
+ * then the Agent uses LLM to produce obfuscated labels and writes them
+ * back via `graph-add`.
+ *
+ * Fallback rules are intentionally weak — they preserve too many
+ * identifying cues. Marked as experimental, not for production use.
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+export interface ObfuscationCandidate {
+    id: string;
+    label: string;
+    entityType?: string;
+    score?: number;
+    hasObfuscatedLabel: boolean;
+    obfuscatedLabel?: string;
+}
+export interface FallbackRuleResult {
+    original: string;
+    obfuscated: string;
+    rule: string;
+}
+export interface ObfuscationResult {
+    mode: 'list' | 'fallback_rules';
+    candidates: ObfuscationCandidate[];
+    fallbackResults?: FallbackRuleResult[];
+    stats: {
+        totalEntities: number;
+        alreadyObfuscated: number;
+        needObfuscation: number;
+    };
+}
+export interface ObfuscationConfig {
+    mode: 'list' | 'fallback_rules';
+    /** Entity types to skip during obfuscation (e.g. "concept" may be too vague) */
+    skipEntityTypes?: string[];
+}
+/** List entities that are candidates for obfuscation (those without obfuscatedLabel). */
+export declare function listObfuscationCandidates(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config?: ObfuscationConfig): ObfuscationResult;
+/** Apply fallback rules to all entities without obfuscatedLabel and write results to graph.
+ *  Returns the list of applied rules. */
+export declare function applyFallbackRules(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config?: ObfuscationConfig): ObfuscationResult;
+/** Run entity obfuscation on a graph. */
+export declare function runGraphObfuscate(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config: ObfuscationConfig): ObfuscationResult;
+//# sourceMappingURL=graph-obfuscate.d.ts.map

package/dist/deep/graph-obfuscate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-obfuscate.d.ts","sourceRoot":"","sources":["../../src/deep/graph-obfuscate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAY,MAAM,YAAY,CAAC;AAItE,MAAM,WAAW,oBAAoB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChC,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,KAAK,EAAE;QACH,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;KAC3B,CAAC;CACL;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChC,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAID,yFAAyF;AACzF,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,CAAC,EAAE,iBAAiB,GAC3B,iBAAiB,CAkCnB;AAgHD;yCACyC;AACzC,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,CAAC,EAAE,iBAAiB,GAC3B,iBAAiB,CA+DnB;AAID,yCAAyC;AACzC,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,EAAE,iBAAiB,GAC1B,iBAAiB,CAanB"}

package/dist/deep/graph-obfuscate.js

@@ -0,0 +1,226 @@
+/**
+ * Entity obfuscation (MTG-inspired) for knowledge graph.
+ *
+ * Primary flow: Agent (LLM) generates obfuscated labels.
+ * Fallback flow: simple rule-based obfuscation (experimental).
+ *
+ * The `graph-obfuscate` command outputs candidate entities for obfuscation,
+ * then the Agent uses LLM to produce obfuscated labels and writes them
+ * back via `graph-add`.
+ *
+ * Fallback rules are intentionally weak — they preserve too many
+ * identifying cues. Marked as experimental, not for production use.
+ */
+// ── List candidates ───────────────────────────────────────────────
+/** List entities that are candidates for obfuscation (those without obfuscatedLabel). */
+export function listObfuscationCandidates(graph, config) {
+    const candidates = [];
+    let totalEntities = 0;
+    let alreadyObfuscated = 0;
+    const skipTypes = new Set(config?.skipEntityTypes ?? []);
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'entity')
+            return;
+        totalEntities++;
+        if (skipTypes.has(attrs.entityType ?? ''))
+            return;
+        const hasObfuscated = !!attrs.obfuscatedLabel;
+        if (hasObfuscated) {
+            alreadyObfuscated++;
+        }
+        candidates.push({
+            id: node,
+            label: attrs.label,
+            entityType: attrs.entityType,
+            score: attrs.score,
+            hasObfuscatedLabel: hasObfuscated,
+            obfuscatedLabel: attrs.obfuscatedLabel,
+        });
+    });
+    const needObfuscation = totalEntities - alreadyObfuscated;
+    return {
+        mode: 'list',
+        candidates,
+        stats: { totalEntities, alreadyObfuscated, needObfuscation },
+    };
+}
+// ── Fallback rules (experimental) ────────────────────────────────
+/** Version number removal: "TypeScript 5.8" → "TypeScript latest"
+ *  Matches trailing version patterns like "5.8", "19", "v3.2.1"
+ *  Excludes 4-digit years (dates) which are handled by generalizeDate. */
+function removeVersion(label) {
+    // Match labels ending with version-like suffixes, but NOT bare 4-digit years
+    const versionPattern = /^(.+?)\s+v?(\d+\.\d+(?:\.\d+)*|\d{1,3})$/;
+    const match = label.match(versionPattern);
+    if (match) {
+        return {
+            original: label,
+            obfuscated: `${match[1].trim()} latest`,
+            rule: 'remove_version',
+        };
+    }
+    return null;
+}
+/** Category replacement: known software/framework names → generic category.
+ *  Uses entityType if available, otherwise heuristics. */
+function replaceWithCategory(label, entityType) {
+    const CATEGORY_MAP = {
+        runtime: 'a runtime',
+        library: 'a library',
+        framework: 'a framework',
+        language: 'a programming language',
+        tool: 'a development tool',
+        database: 'a database',
+        protocol: 'a protocol',
+        platform: 'a platform',
+        service: 'a service',
+        organization: 'an organization',
+        person: 'a person',
+    };
+    if (entityType && CATEGORY_MAP[entityType]) {
+        return {
+            original: label,
+            obfuscated: CATEGORY_MAP[entityType],
+            rule: 'category_replacement',
+        };
+    }
+    return null;
+}
+/** Date generalization: "February 2026" → "early 2026", "Q3 2025" → "mid 2025"
+ *  Matches month names, quarters, and specific date patterns. */
+function generalizeDate(label) {
+    const MONTH_QUARTER_MAP = {
+        'january': 'early', 'february': 'early', 'march': 'early',
+        'april': 'mid', 'may': 'mid', 'june': 'mid',
+        'july': 'late', 'august': 'late', 'september': 'late',
+        'october': 'late', 'november': 'late', 'december': 'late',
+        'q1': 'early', 'q2': 'mid', 'q3': 'late', 'q4': 'late',
+    };
+    // "February 2026" or "Feb 2026"
+    const monthYearPattern = /^(january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|jun|jul|aug|sep|oct|nov|dec)\s+(\d{4})$/i;
+    const match = label.match(monthYearPattern);
+    if (match) {
+        const month = match[1].toLowerCase().slice(0, 3);
+        const year = match[2];
+        // Normalize abbreviated months
+        const fullMonth = {
+            jan: 'january', feb: 'february', mar: 'march', apr: 'april',
+            jun: 'june', jul: 'july', aug: 'august', sep: 'september',
+            oct: 'october', nov: 'november', dec: 'december',
+        };
+        const normalized = fullMonth[month] || month;
+        const period = MONTH_QUARTER_MAP[normalized];
+        if (period) {
+            return {
+                original: label,
+                obfuscated: `${period} ${year}`,
+                rule: 'date_generalization',
+            };
+        }
+    }
+    // "Q3 2025" pattern
+    const quarterPattern = /^(q[1-4])\s+(\d{4})$/i;
+    const qMatch = label.match(quarterPattern);
+    if (qMatch) {
+        const quarter = qMatch[1].toLowerCase();
+        const year = qMatch[2];
+        const period = MONTH_QUARTER_MAP[quarter];
+        if (period) {
+            return {
+                original: label,
+                obfuscated: `${period} ${year}`,
+                rule: 'date_generalization',
+            };
+        }
+    }
+    return null;
+}
+/** Apply fallback obfuscation rules in priority order:
+ *  1. Date generalization (before version removal to avoid "February 2026" → "February latest")
+ *  2. Version removal
+ *  3. Category replacement
+ *
+ *  ⚠️ Fallback rules are experimental — they preserve too many
+ *  identifying cues for true MTG-style obfuscation. */
+function applyFallbackRule(label, entityType) {
+    return generalizeDate(label) || removeVersion(label) || replaceWithCategory(label, entityType);
+}
+/** Apply fallback rules to all entities without obfuscatedLabel and write results to graph.
+ *  Returns the list of applied rules. */
+export function applyFallbackRules(graph, config) {
+    const skipTypes = new Set(config?.skipEntityTypes ?? []);
+    const fallbackResults = [];
+    let totalEntities = 0;
+    let alreadyObfuscated = 0;
+    let needObfuscation = 0;
+    const candidates = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'entity')
+            return;
+        totalEntities++;
+        if (skipTypes.has(attrs.entityType ?? ''))
+            return;
+        if (attrs.obfuscatedLabel) {
+            alreadyObfuscated++;
+            candidates.push({
+                id: node,
+                label: attrs.label,
+                entityType: attrs.entityType,
+                score: attrs.score,
+                hasObfuscatedLabel: true,
+                obfuscatedLabel: attrs.obfuscatedLabel,
+            });
+            return;
+        }
+        needObfuscation++;
+        const result = applyFallbackRule(attrs.label, attrs.entityType);
+        if (result) {
+            // Write obfuscatedLabel back to graph node
+            graph.mergeNode(node, {
+                ...attrs,
+                obfuscatedLabel: result.obfuscated,
+            });
+            fallbackResults.push(result);
+            candidates.push({
+                id: node,
+                label: attrs.label,
+                entityType: attrs.entityType,
+                score: attrs.score,
+                hasObfuscatedLabel: true,
+                obfuscatedLabel: result.obfuscated,
+            });
+        }
+        else {
+            candidates.push({
+                id: node,
+                label: attrs.label,
+                entityType: attrs.entityType,
+                score: attrs.score,
+                hasObfuscatedLabel: false,
+            });
+        }
+    });
+    return {
+        mode: 'fallback_rules',
+        candidates,
+        fallbackResults,
+        stats: { totalEntities, alreadyObfuscated, needObfuscation },
+    };
+}
+// ── Main dispatch ─────────────────────────────────────────────────
+/** Run entity obfuscation on a graph. */
+export function runGraphObfuscate(graph, config) {
+    switch (config.mode) {
+        case 'list':
+            return listObfuscationCandidates(graph, config);
+        case 'fallback_rules':
+            return applyFallbackRules(graph, config);
+        default:
+            return {
+                mode: config.mode,
+                candidates: [],
+                stats: { totalEntities: 0, alreadyObfuscated: 0, needObfuscation: 0 },
+            };
+    }
+}
+//# sourceMappingURL=graph-obfuscate.js.map

package/dist/deep/graph-obfuscate.js.map

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

package/dist/deep/graph-preprocess.d.ts

@@ -0,0 +1,41 @@
+/**
+ * graph-preprocess: Preprocess session data to produce TF-IDF terms,
+ * co-occurrence pairs, and existing entity context for Agent consumption.
+ */
+export interface PreprocessResult {
+    tfidfTerms: Array<{
+        term: string;
+        tf: number;
+        idf: number;
+        tfidf: number;
+        docFreq: number;
+    }>;
+    coOccurrences: Array<{
+        term1: string;
+        term2: string;
+        count: number;
+    }>;
+    existingEntities: Array<{
+        id: string;
+        label: string;
+        degree: number;
+        entityType?: string;
+    }>;
+    termFrequencies: Array<{
+        term: string;
+        count: number;
+    }>;
+    roundsCovered: number;
+    totalResults: number;
+    resultsWithContent: number;
+    tokenizationStrategy: string;
+    coOccurrenceTruncated: boolean;
+}
+export interface PreprocessOptions {
+    top?: number;
+    coOccurrenceThreshold?: number;
+    maxTermsForCoOccurrence?: number;
+}
+/** Run full preprocessing pipeline on a session directory. */
+export declare function graphPreprocess(sessionDir: string, opts?: PreprocessOptions): PreprocessResult;
+//# sourceMappingURL=graph-preprocess.d.ts.map

package/dist/deep/graph-preprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-preprocess.d.ts","sourceRoot":"","sources":["../../src/deep/graph-preprocess.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7F,aAAa,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,gBAAgB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5F,eAAe,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC3B,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,iBAAiB,GACzB,gBAAgB,CAwBlB"}

package/dist/deep/graph-preprocess.js

@@ -0,0 +1,32 @@
+/**
+ * graph-preprocess: Preprocess session data to produce TF-IDF terms,
+ * co-occurrence pairs, and existing entity context for Agent consumption.
+ */
+import { computeTfIdf } from './tfidf.js';
+import { buildCoOccurrence, computeCrossResultFrequency, getExistingEntityContext } from './co-occurrence.js';
+import { loadSessionResults, loadSessionGraph, loadSessionRounds } from './session.js';
+/** Run full preprocessing pipeline on a session directory. */
+export function graphPreprocess(sessionDir, opts) {
+    const results = loadSessionResults(sessionDir);
+    const graph = loadSessionGraph(sessionDir);
+    const rounds = loadSessionRounds(sessionDir);
+    const tfidf = computeTfIdf(results, { top: opts?.top });
+    const coOcc = buildCoOccurrence(results, {
+        threshold: opts?.coOccurrenceThreshold,
+        maxTerms: opts?.maxTermsForCoOccurrence,
+    });
+    const termFreqs = computeCrossResultFrequency(results, { top: opts?.top ?? 50 });
+    const entities = getExistingEntityContext(graph);
+    return {
+        tfidfTerms: tfidf.terms,
+        coOccurrences: coOcc.pairs,
+        existingEntities: entities,
+        termFrequencies: termFreqs,
+        roundsCovered: rounds,
+        totalResults: results.length,
+        resultsWithContent: tfidf.resultsWithContent,
+        tokenizationStrategy: tfidf.tokenizationStrategy,
+        coOccurrenceTruncated: coOcc.truncated,
+    };
+}
+//# sourceMappingURL=graph-preprocess.js.map

package/dist/deep/graph-preprocess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-preprocess.js","sourceRoot":"","sources":["../../src/deep/graph-preprocess.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAqBvF,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAC3B,UAAkB,EAClB,IAAwB;IAExB,MAAM,OAAO,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAkD,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE;QACrC,SAAS,EAAE,IAAI,EAAE,qBAAqB;QACtC,QAAQ,EAAE,IAAI,EAAE,uBAAuB;KAC1C,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAEjD,OAAO;QACH,UAAU,EAAE,KAAK,CAAC,KAAK;QACvB,aAAa,EAAE,KAAK,CAAC,KAAK;QAC1B,gBAAgB,EAAE,QAAQ;QAC1B,eAAe,EAAE,SAAS;QAC1B,aAAa,EAAE,MAAM;QACrB,YAAY,EAAE,OAAO,CAAC,MAAM;QAC5B,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;QAChD,qBAAqB,EAAE,KAAK,CAAC,SAAS;KACzC,CAAC;AACN,CAAC"}

package/dist/deep/graph-sampling.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Graph sampling strategies for knowledge graph exploration.
+ *
+ * Given a graph, seed entities, and a strategy, produces a sampled subgraph
+ * focused on the most relevant structures for reasoning.
+ *
+ * Strategies:
+ * - augmented_chain: sequential entity chain with attribute enrichment
+ * - dual_core_bridge: two seed entities converging on a shared target
+ * - community_core_path: high-degree hub → peripheral entities
+ * - deep_chain: depth-limited DFS (max 5-8 hops)
+ * - mixed: randomly pick one of the above
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+export type SamplingStrategy = 'augmented_chain' | 'dual_core_bridge' | 'community_core_path' | 'deep_chain' | 'mixed';
+export interface SamplingConfig {
+    strategy: SamplingStrategy;
+    seedEntities: string[];
+    maxHops: number;
+    degreeRange?: {
+        min?: number;
+        max?: number;
+        maxDegreeCap?: number;
+    };
+    /** Random seed for deterministic output. Used by mixed strategy. */
+    rngSeed?: number;
+}
+export interface SampledEntity {
+    id: string;
+    label: string;
+    entityType?: string;
+    score?: number;
+    degree: number;
+}
+export interface SampledEdge {
+    source: string;
+    target: string;
+    relation: string;
+    weight: number;
+}
+export interface SamplingResult {
+    strategy: SamplingStrategy;
+    entities: SampledEntity[];
+    edges: SampledEdge[];
+    hopsCovered: number;
+    metadata: Record<string, unknown>;
+}
+/** Sample a knowledge graph using the specified strategy. */
+export declare function sampleGraph(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config: SamplingConfig): SamplingResult;
+//# sourceMappingURL=graph-sampling.d.ts.map

package/dist/deep/graph-sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-sampling.d.ts","sourceRoot":"","sources":["../../src/deep/graph-sampling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAY,MAAM,YAAY,CAAC;AAKtE,MAAM,MAAM,gBAAgB,GACtB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,YAAY,GACZ,OAAO,CAAC;AAEd,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAwcD,6DAA6D;AAC7D,wBAAgB,WAAW,CACvB,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,EAAE,cAAc,GACvB,cAAc,CAehB"}