codehere 0.1.0 → 0.2.0

package/dist/infrastructure/xai/cot-visualizer.js

@@ -0,0 +1,239 @@
+/**
+ * Infrastructure: Chain-of-Thought (CoT) Visualizer
+ *
+ * Visualizes AI reasoning steps in a human-readable format (Cursor Plan Mode style)
+ * Research: Chain-of-Thought (CoT) reasoning essential for transparency
+ *
+ * Features:
+ * - Step-by-step reasoning visualization
+ * - Tool selection rationale
+ * - Decision point explanations
+ * - Progress tracking
+ */
+/**
+ * Chain-of-Thought Visualizer
+ * Formats reasoning steps for human-readable display
+ */
+export class CoTVisualizer {
+    /**
+     * Create new CoT trajectory
+     */
+    createTrajectory(query) {
+        return {
+            trajectoryId: `cot-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            query,
+            steps: [],
+            currentStep: 0,
+            status: 'in_progress',
+            startedAt: Date.now(),
+        };
+    }
+    /**
+     * Add thought step
+     */
+    addThought(trajectory, thought, metadata) {
+        const stepId = `step-${Date.now()}-thought`;
+        const step = {
+            stepId,
+            stepNumber: trajectory.steps.length + 1,
+            type: 'thought',
+            content: thought,
+            timestamp: Date.now(),
+            metadata,
+        };
+        trajectory.steps.push(step);
+        trajectory.currentStep = trajectory.steps.length;
+        return stepId;
+    }
+    /**
+     * Add action step (tool call, edit, etc.)
+     */
+    addAction(trajectory, action, metadata) {
+        const stepId = `step-${Date.now()}-action`;
+        const step = {
+            stepId,
+            stepNumber: trajectory.steps.length + 1,
+            type: 'action',
+            content: action,
+            timestamp: Date.now(),
+            metadata,
+        };
+        trajectory.steps.push(step);
+        trajectory.currentStep = trajectory.steps.length;
+        return stepId;
+    }
+    /**
+     * Add observation step (tool result, file content, etc.)
+     */
+    addObservation(trajectory, observation, metadata) {
+        const stepId = `step-${Date.now()}-observation`;
+        const step = {
+            stepId,
+            stepNumber: trajectory.steps.length + 1,
+            type: 'observation',
+            content: observation,
+            timestamp: Date.now(),
+            metadata,
+        };
+        trajectory.steps.push(step);
+        trajectory.currentStep = trajectory.steps.length;
+        return stepId;
+    }
+    /**
+     * Add decision step (choice point, branching)
+     */
+    addDecision(trajectory, decision, options, chosen, rationale) {
+        const stepId = `step-${Date.now()}-decision`;
+        const step = {
+            stepId,
+            stepNumber: trajectory.steps.length + 1,
+            type: 'decision',
+            content: decision,
+            timestamp: Date.now(),
+            metadata: {
+                options,
+                chosen,
+                reasoning: rationale,
+            },
+        };
+        trajectory.steps.push(step);
+        trajectory.currentStep = trajectory.steps.length;
+        return stepId;
+    }
+    /**
+     * Add error step
+     */
+    addError(trajectory, error, errorDetails) {
+        const stepId = `step-${Date.now()}-error`;
+        const step = {
+            stepId,
+            stepNumber: trajectory.steps.length + 1,
+            type: 'error',
+            content: error,
+            timestamp: Date.now(),
+            metadata: {
+                errorDetails,
+            },
+        };
+        trajectory.steps.push(step);
+        trajectory.currentStep = trajectory.steps.length;
+        trajectory.status = 'failed';
+        return stepId;
+    }
+    /**
+     * Mark trajectory as completed
+     */
+    completeTrajectory(trajectory) {
+        trajectory.status = 'completed';
+        trajectory.completedAt = Date.now();
+    }
+    /**
+     * Format trajectory for console output (human-readable)
+     */
+    formatForConsole(trajectory, options) {
+        const { showMetadata = false, maxSteps, compact = false } = options || {};
+        const steps = maxSteps ? trajectory.steps.slice(0, maxSteps) : trajectory.steps;
+        let output = '';
+        if (!compact) {
+            output += `\n${'═'.repeat(80)}\n`;
+            output += `Chain of Thought: ${trajectory.query.substring(0, 60)}${trajectory.query.length > 60 ? '...' : ''}\n`;
+            output += `${'═'.repeat(80)}\n\n`;
+        }
+        for (const step of steps) {
+            output += this.formatStep(step, { showMetadata, compact });
+        }
+        if (trajectory.status === 'completed' && !compact) {
+            output += `\n${'─'.repeat(80)}\n`;
+            output += `✓ Completed in ${trajectory.steps.length} steps`;
+            if (trajectory.completedAt && trajectory.startedAt) {
+                const duration = ((trajectory.completedAt - trajectory.startedAt) / 1000).toFixed(2);
+                output += ` (${duration}s)\n`;
+            }
+            output += `${'─'.repeat(80)}\n`;
+        }
+        return output;
+    }
+    /**
+     * Format trajectory for JSON export
+     */
+    formatForJSON(trajectory) {
+        return JSON.stringify(trajectory, null, 2);
+    }
+    /**
+     * Format trajectory for interactive UI (structured data)
+     */
+    formatForUI(trajectory) {
+        return {
+            query: trajectory.query,
+            status: trajectory.status,
+            steps: trajectory.steps.map(step => ({
+                number: step.stepNumber,
+                type: step.type,
+                content: step.content,
+                timestamp: step.timestamp,
+                metadata: step.metadata,
+            })),
+            duration: trajectory.completedAt && trajectory.startedAt
+                ? trajectory.completedAt - trajectory.startedAt
+                : undefined,
+        };
+    }
+    // Private helpers
+    formatStep(step, options) {
+        const { showMetadata = false, compact = false } = options;
+        let output = '';
+        const prefix = compact ? '' : `[Step ${step.stepNumber}] `;
+        const icon = this.getStepIcon(step.type);
+        switch (step.type) {
+            case 'thought':
+                output += `${prefix}${icon} Thought: ${step.content}\n`;
+                break;
+            case 'action':
+                output += `${prefix}${icon} Action: ${step.content}\n`;
+                if (showMetadata && step.metadata?.tool) {
+                    output += `   └─ Tool: ${step.metadata.tool}\n`;
+                    if (step.metadata.reasoning) {
+                        output += `   └─ Reasoning: ${step.metadata.reasoning}\n`;
+                    }
+                }
+                break;
+            case 'observation':
+                output += `${prefix}${icon} Observation: ${step.content.substring(0, 100)}${step.content.length > 100 ? '...' : ''}\n`;
+                break;
+            case 'decision':
+                output += `${prefix}${icon} Decision: ${step.content}\n`;
+                if (showMetadata && step.metadata?.options) {
+                    output += `   └─ Options: ${step.metadata.options.join(', ')}\n`;
+                    output += `   └─ Chosen: ${step.metadata.chosen}\n`;
+                    if (step.metadata.reasoning) {
+                        output += `   └─ Reasoning: ${step.metadata.reasoning}\n`;
+                    }
+                }
+                break;
+            case 'error':
+                output += `${prefix}${icon} Error: ${step.content}\n`;
+                break;
+        }
+        if (!compact) {
+            output += '\n';
+        }
+        return output;
+    }
+    getStepIcon(type) {
+        switch (type) {
+            case 'thought':
+                return '💭';
+            case 'action':
+                return '⚡';
+            case 'observation':
+                return '👁️';
+            case 'decision':
+                return '🔀';
+            case 'error':
+                return '❌';
+            default:
+                return '•';
+        }
+    }
+}
+//# sourceMappingURL=cot-visualizer.js.map

package/dist/infrastructure/xai/cot-visualizer.js.map

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

package/dist/infrastructure/xai/decision-tree-log.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Infrastructure: Decision Tree Log (Execution Trace)
+ * Complete audit trail for multi-step agentic workflows
+ *
+ * Research Finding: Required for multi-step agent auditability
+ * Essential for fault attribution and regulatory compliance
+ *
+ * Based on research: Explainable AI (XAI) for Code Generation Agents
+ * - Goal Interpretation Logging (parsed intent, constraints, dependencies)
+ * - Tool Rationale Logging (why tool chosen, parameters, reasoning)
+ * - Raw Output Capture (unaltered tool results)
+ * - Integration Step Logging (how LLM processed external data)
+ * - External Data Provenance (source, freshness, trust)
+ */
+export interface DecisionNode {
+    id: string;
+    type: 'goal' | 'plan' | 'tool' | 'synthesis' | 'error';
+    timestamp: number;
+    description: string;
+    metadata: Record<string, any>;
+    children?: DecisionNode[];
+    childNodeIds?: string[];
+    parentId?: string;
+}
+export interface GoalInterpretation {
+    parsedIntent: string;
+    constraints: string[];
+    dependencies: string[];
+    confidence: number;
+}
+export interface ToolRationale {
+    toolName: string;
+    parameters: Record<string, any>;
+    reasoning: string;
+    alternativeTools?: string[];
+    executionTime?: number;
+    rawOutput?: any;
+}
+export interface ExternalDataProvenance {
+    source: string;
+    timestamp: number;
+    freshness: number;
+    trustLevel: 'high' | 'medium' | 'low';
+    url?: string;
+}
+export interface IntegrationStep {
+    inputData: any;
+    processingDescription: string;
+    outputData: any;
+    transformations: string[];
+}
+/**
+ * Decision Tree Log
+ * Maintains complete execution trace for agentic workflows
+ */
+export declare class DecisionTreeLog {
+    private nodes;
+    private rootNodeId;
+    /**
+     * Log goal interpretation
+     */
+    logGoalInterpretation(goalId: string, interpretation: GoalInterpretation, parentId?: string): string;
+    /**
+     * Log plan step
+     */
+    logPlanStep(planId: string, stepDescription: string, metadata: Record<string, any>, parentId: string): string;
+    /**
+     * Log tool execution with rationale
+     */
+    logToolExecution(toolId: string, rationale: ToolRationale, parentId: string): string;
+    /**
+     * Log external data provenance
+     */
+    logExternalData(dataId: string, provenance: ExternalDataProvenance, parentId: string): string;
+    /**
+     * Log integration step (how LLM processed external data)
+     */
+    logIntegrationStep(integrationId: string, step: IntegrationStep, parentId: string): string;
+    /**
+     * Log error
+     */
+    logError(errorId: string, error: Error, context: Record<string, any>, parentId: string): string;
+    /**
+     * Get complete execution tree
+     */
+    getExecutionTree(): DecisionNode | null;
+    /**
+     * Build tree structure recursively
+     */
+    private buildTree;
+    /**
+     * Add child node to parent
+     */
+    private addChild;
+    /**
+     * Get trace for fault attribution
+     */
+    getErrorTrace(errorId: string): DecisionNode[];
+    /**
+     * Clear log
+     */
+    clear(): void;
+}
+//# sourceMappingURL=decision-tree-log.d.ts.map

package/dist/infrastructure/xai/decision-tree-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-tree-log.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/xai/decision-tree-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,GAAG,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,GAAG,CAAC;IACf,qBAAqB,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,GAAG,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,UAAU,CAAuB;IAEzC;;OAEG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,kBAAkB,EAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM;IAuBT;;OAEG;IACH,WAAW,CACT,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM;IAeT;;OAEG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,MAAM,GACf,MAAM;IAsBT;;OAEG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,sBAAsB,EAClC,QAAQ,EAAE,MAAM,GACf,MAAM;IAsBT;;OAEG;IACH,kBAAkB,CAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,eAAe,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM;IAmBT;;OAEG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,QAAQ,EAAE,MAAM,GACf,MAAM;IAmBT;;OAEG;IACH,gBAAgB,IAAI,YAAY,GAAG,IAAI;IAQvC;;OAEG;IACH,OAAO,CAAC,SAAS;IAsBjB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAYhB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE;IAiB9C;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/infrastructure/xai/decision-tree-log.js

@@ -0,0 +1,216 @@
+/**
+ * Infrastructure: Decision Tree Log (Execution Trace)
+ * Complete audit trail for multi-step agentic workflows
+ *
+ * Research Finding: Required for multi-step agent auditability
+ * Essential for fault attribution and regulatory compliance
+ *
+ * Based on research: Explainable AI (XAI) for Code Generation Agents
+ * - Goal Interpretation Logging (parsed intent, constraints, dependencies)
+ * - Tool Rationale Logging (why tool chosen, parameters, reasoning)
+ * - Raw Output Capture (unaltered tool results)
+ * - Integration Step Logging (how LLM processed external data)
+ * - External Data Provenance (source, freshness, trust)
+ */
+/**
+ * Decision Tree Log
+ * Maintains complete execution trace for agentic workflows
+ */
+export class DecisionTreeLog {
+    nodes = new Map();
+    rootNodeId = null;
+    /**
+     * Log goal interpretation
+     */
+    logGoalInterpretation(goalId, interpretation, parentId) {
+        if (!this.rootNodeId) {
+            this.rootNodeId = goalId;
+        }
+        const node = {
+            id: goalId,
+            type: 'goal',
+            timestamp: Date.now(),
+            description: `Goal: ${interpretation.parsedIntent}`,
+            metadata: {
+                parsedIntent: interpretation.parsedIntent,
+                constraints: interpretation.constraints,
+                dependencies: interpretation.dependencies,
+                confidence: interpretation.confidence,
+            },
+            parentId,
+        };
+        this.nodes.set(goalId, node);
+        return goalId;
+    }
+    /**
+     * Log plan step
+     */
+    logPlanStep(planId, stepDescription, metadata, parentId) {
+        const node = {
+            id: planId,
+            type: 'plan',
+            timestamp: Date.now(),
+            description: stepDescription,
+            metadata,
+            parentId,
+        };
+        this.nodes.set(planId, node);
+        this.addChild(parentId, planId);
+        return planId;
+    }
+    /**
+     * Log tool execution with rationale
+     */
+    logToolExecution(toolId, rationale, parentId) {
+        const node = {
+            id: toolId,
+            type: 'tool',
+            timestamp: Date.now(),
+            description: `Tool: ${rationale.toolName}`,
+            metadata: {
+                toolName: rationale.toolName,
+                parameters: rationale.parameters,
+                reasoning: rationale.reasoning,
+                alternativeTools: rationale.alternativeTools,
+                executionTime: rationale.executionTime,
+                rawOutput: rationale.rawOutput, // Unaltered tool result for provenance
+            },
+            parentId,
+        };
+        this.nodes.set(toolId, node);
+        this.addChild(parentId, toolId);
+        return toolId;
+    }
+    /**
+     * Log external data provenance
+     */
+    logExternalData(dataId, provenance, parentId) {
+        const node = {
+            id: dataId,
+            type: 'tool', // External data comes via tools
+            timestamp: Date.now(),
+            description: `External Data: ${provenance.source}`,
+            metadata: {
+                source: provenance.source,
+                timestamp: provenance.timestamp,
+                freshness: provenance.freshness,
+                trustLevel: provenance.trustLevel,
+                url: provenance.url,
+                dataAge: Date.now() - provenance.timestamp, // Age in milliseconds
+            },
+            parentId,
+        };
+        this.nodes.set(dataId, node);
+        this.addChild(parentId, dataId);
+        return dataId;
+    }
+    /**
+     * Log integration step (how LLM processed external data)
+     */
+    logIntegrationStep(integrationId, step, parentId) {
+        const node = {
+            id: integrationId,
+            type: 'synthesis',
+            timestamp: Date.now(),
+            description: step.processingDescription,
+            metadata: {
+                inputData: step.inputData,
+                outputData: step.outputData,
+                transformations: step.transformations,
+            },
+            parentId,
+        };
+        this.nodes.set(integrationId, node);
+        this.addChild(parentId, integrationId);
+        return integrationId;
+    }
+    /**
+     * Log error
+     */
+    logError(errorId, error, context, parentId) {
+        const node = {
+            id: errorId,
+            type: 'error',
+            timestamp: Date.now(),
+            description: `Error: ${error.message}`,
+            metadata: {
+                error: error.message,
+                stack: error.stack,
+                context,
+            },
+            parentId,
+        };
+        this.nodes.set(errorId, node);
+        this.addChild(parentId, errorId);
+        return errorId;
+    }
+    /**
+     * Get complete execution tree
+     */
+    getExecutionTree() {
+        if (!this.rootNodeId) {
+            return null;
+        }
+        return this.buildTree(this.rootNodeId);
+    }
+    /**
+     * Build tree structure recursively
+     */
+    buildTree(nodeId) {
+        const node = this.nodes.get(nodeId);
+        if (!node) {
+            return null;
+        }
+        const children = [];
+        if (node.childNodeIds && node.childNodeIds.length > 0) {
+            for (const childId of node.childNodeIds) {
+                const childNode = this.buildTree(childId);
+                if (childNode) {
+                    children.push(childNode);
+                }
+            }
+        }
+        return {
+            ...node,
+            children: children.length > 0 ? children : undefined,
+        };
+    }
+    /**
+     * Add child node to parent
+     */
+    addChild(parentId, childId) {
+        const parent = this.nodes.get(parentId);
+        if (parent) {
+            if (!parent.childNodeIds) {
+                parent.childNodeIds = [];
+            }
+            if (!parent.childNodeIds.includes(childId)) {
+                parent.childNodeIds.push(childId);
+            }
+        }
+    }
+    /**
+     * Get trace for fault attribution
+     */
+    getErrorTrace(errorId) {
+        const trace = [];
+        let currentId = errorId;
+        while (currentId) {
+            const node = this.nodes.get(currentId);
+            if (!node) {
+                break;
+            }
+            trace.unshift(node);
+            currentId = node.parentId;
+        }
+        return trace;
+    }
+    /**
+     * Clear log
+     */
+    clear() {
+        this.nodes.clear();
+        this.rootNodeId = null;
+    }
+}
+//# sourceMappingURL=decision-tree-log.js.map

package/dist/infrastructure/xai/decision-tree-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-tree-log.js","sourceRoot":"","sources":["../../../src/infrastructure/xai/decision-tree-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4CH;;;GAGG;AACH,MAAM,OAAO,eAAe;IAClB,KAAK,GAA8B,IAAI,GAAG,EAAE,CAAC;IAC7C,UAAU,GAAkB,IAAI,CAAC;IAEzC;;OAEG;IACH,qBAAqB,CACnB,MAAc,EACd,cAAkC,EAClC,QAAiB;QAEjB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;QAC3B,CAAC;QAED,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,SAAS,cAAc,CAAC,YAAY,EAAE;YACnD,QAAQ,EAAE;gBACR,YAAY,EAAE,cAAc,CAAC,YAAY;gBACzC,WAAW,EAAE,cAAc,CAAC,WAAW;gBACvC,YAAY,EAAE,cAAc,CAAC,YAAY;gBACzC,UAAU,EAAE,cAAc,CAAC,UAAU;aACtC;YACD,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,WAAW,CACT,MAAc,EACd,eAAuB,EACvB,QAA6B,EAC7B,QAAgB;QAEhB,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,eAAe;YAC5B,QAAQ;YACR,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,gBAAgB,CACd,MAAc,EACd,SAAwB,EACxB,QAAgB;QAEhB,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,SAAS,SAAS,CAAC,QAAQ,EAAE;YAC1C,QAAQ,EAAE;gBACR,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,UAAU,EAAE,SAAS,CAAC,UAAU;gBAChC,SAAS,EAAE,SAAS,CAAC,SAAS;gBAC9B,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;gBAC5C,aAAa,EAAE,SAAS,CAAC,aAAa;gBACtC,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,uCAAuC;aACxE;YACD,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,eAAe,CACb,MAAc,EACd,UAAkC,EAClC,QAAgB;QAEhB,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,MAAM,EAAE,gCAAgC;YAC9C,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,kBAAkB,UAAU,CAAC,MAAM,EAAE;YAClD,QAAQ,EAAE;gBACR,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,UAAU,EAAE,UAAU,CAAC,UAAU;gBACjC,GAAG,EAAE,UAAU,CAAC,GAAG;gBACnB,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,SAAS,EAAE,sBAAsB;aACnE;YACD,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,kBAAkB,CAChB,aAAqB,EACrB,IAAqB,EACrB,QAAgB;QAEhB,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,aAAa;YACjB,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,IAAI,CAAC,qBAAqB;YACvC,QAAQ,EAAE;gBACR,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,eAAe,EAAE,IAAI,CAAC,eAAe;aACtC;YACD,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QACvC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,QAAQ,CACN,OAAe,EACf,KAAY,EACZ,OAA4B,EAC5B,QAAgB;QAEhB,MAAM,IAAI,GAAiB;YACzB,EAAE,EAAE,OAAO;YACX,IAAI,EAAE,OAAO;YACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,UAAU,KAAK,CAAC,OAAO,EAAE;YACtC,QAAQ,EAAE;gBACR,KAAK,EAAE,KAAK,CAAC,OAAO;gBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,OAAO;aACR;YACD,QAAQ;SACT,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,MAAc;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,QAAQ,GAAmB,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACxC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;gBAC1C,IAAI,SAAS,EAAE,CAAC;oBACd,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,GAAG,IAAI;YACP,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACrD,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,QAAgB,EAAE,OAAe;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;gBACzB,MAAM,CAAC,YAAY,GAAG,EAAE,CAAC;YAC3B,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3C,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAAe;QAC3B,MAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,IAAI,SAAS,GAAuB,OAAO,CAAC;QAE5C,OAAO,SAAS,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM;YACR,CAAC;YAED,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACpB,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC5B,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;CACF"}