<?php

/**
 * JCOGS Image Pro - Parameter Registry Service
 * =============================================
 * Central registry for all parameter categorization and management
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      Parameter Registry Implementation
 */

namespace JCOGSDesign\JCOGSImagePro\Service;

use JCOGSDesign\JCOGSImagePro\Service\Validation\ValidatorInterface;
use JCOGSDesign\JCOGSImagePro\Service\Validation\ValidationResult;
use JCOGSDesign\JCOGSImagePro\Service\Validation\NumericValidator;
use JCOGSDesign\JCOGSImagePro\Service\Validation\EnumValidator;
use JCOGSDesign\JCOGSImagePro\Service\Validation\StringValidator;
use JCOGSDesign\JCOGSImagePro\Service\Validation\CoordinatesValidator;
use JCOGSDesign\JCOGSImagePro\Service\Validation\PercentageValidator;

/**
 * Parameter Registry Service
 * 
 * Single source of truth for parameter categorization in JCOGS Image Pro.
 * Uses Legacy's proven categorization system (control/dimensional/transformational)
 * to eliminate maintenance issues with duplicate parameter lists.
 * 
 * This registry replaces standalone parameter lists in:
 * - CacheKeyGenerator::_initialize_transformational_params()
 * - Future ValidationService parameter categorization
 * - Parameter Package directory organization
 * 
 * Based on Legacy ImageUtilities.php parameter categorization with Pro extensions.
 */
class ParameterRegistry 
{
    /**
     * Parameter definitions with Legacy categorization
     * 
     * Format: 'parameter_name' => ['category' => 'type', 'package' => 'PackageClass']
     * 
     * Categories (from Legacy ImageUtilities.php):
     * - 'control': Output parameters, cache settings, file paths
     * - 'dimensional': Size and dimension parameters  
     * - 'transformational': Image modification parameters
     * 
     * @var array
     */
    private static array $parameter_definitions = [
        // CONTROL PARAMETERS (Legacy 'control' type)
        // File and output control parameters
        'src' => ['category' => 'control', 'package' => 'SrcParameter'],
        'filename' => [
            'category' => 'control',
            'package' => 'FilenameParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-filename'
        ],
        'filename_prefix' => [
            'category' => 'control',
            'package' => 'FilenameParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-filename-prefix'
        ],
        'filename_suffix' => [
            'category' => 'control',
            'package' => 'FilenameParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-filename-suffix'
        ],
        'hash_filename' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-hash-filename'
        ],
        'cache' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-cache'
        ],
        'cache_dir' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-cache-dir'
        ],
        'overwrite_cache' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-overwrite-cache',
            'accepted_values' => ['yes', 'y', '1', 'no', 'n', '0'],
            'aliases' => ['overwrite', 'force'] // Internal aliases (undocumented)
        ],
        'connection' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage'
        ],
        'debug' => [
            'category' => 'control',
            'package' => 'ControlParameterPackage'
        ],
        'output' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-output'
        ],
        'save_type' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-save-type'
        ],
        'url_only' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-url-only'
        ],
        'lazy' => [
            'category' => 'control',
            'package' => 'LazyParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-background-lazy'
        ],
        'sizes' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-sizes'
        ],
        'srcset' => [
            'category' => 'control',
            'package' => 'SrcsetParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-srcset'
        ],
        'exclude_style' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-exclude-style'
        ],
        'exclude_regex' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-exclude-regex'
        ],
        'image_path_prefix' => [
            'category' => 'control',
            'package' => 'PathParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-image-path-prefix'
        ],
        'use_image_path_prefix' => [
            'category' => 'control',
            'package' => 'PathParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-use-image-path-prefix'
        ],
        'svg_passthrough' => [
            'category' => 'control',
            'package' => 'FormatParameter'
        ],
        'palette_size' => [
            'category' => 'control',
            'package' => 'FormatParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-palette_size'
        ],
        'add_dims' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-add-dims'
        ],
        'fetchpriority' => [
            'category' => 'control',
            'package' => 'OutputParameter',
            'validator' => EnumValidator::class,
            'validation_config' => [
                'allowed_values' => ['high', 'low', 'auto'],
                'case_sensitive' => false,
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-fetchpriority'
        ],
        'attributes' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-attributes'
        ],
        'alt' => [
            'category' => 'control',
            'package' => 'OutputParameter'
        ],
        'title' => [
            'category' => 'control',
            'package' => 'OutputParameter'
        ],
        'class' => [
            'category' => 'control',
            'package' => 'OutputParameter'
        ],
        'id' => [
            'category' => 'control',
            'package' => 'OutputParameter'
        ],
        'add_dimensions' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-add-dimensions'
        ],
        'consolidate_class_style' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-consolidate-class-style'
        ],
        'create_tag' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-create-tag'
        ],
        'disable_browser_checks' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-disable-browser-checks'
        ],
        'exclude_class' => [
            'category' => 'control', 
            'package' => 'OutputParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-exclude-class'
        ],
        
        // DIMENSIONAL PARAMETERS (Legacy 'dimensional' type)
        // Size and dimension parameters only
        'width' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px'],
                'special_values' => ['auto', 'orig']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-width'
        ],
        'height' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px'],
                'special_values' => ['auto', 'orig']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-height'
        ],
        'max' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-max'
        ],
        'max_width' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-max-width'
        ],
        'max_height' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-max-height'
        ],
        'min' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-min'
        ],
        'min_width' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-min-width'
        ],
        'min_height' => [
            'category' => 'dimensional',
            'package' => 'DimensionParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 10000,
                'allow_percentage' => true,
                'allow_units' => ['px']
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-min-height'
        ],
        
        // TRANSFORMATIONAL PARAMETERS (Legacy 'transformational' type)
        // All image modification and enhancement parameters
        
        // Core transformation parameters from Legacy
        'allow_scale_larger' => [
            'category' => 'transformational', 
            'package' => 'BehaviorParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-allow-scale-larger'
        ],
        'aspect_ratio' => [
            'category' => 'transformational',
            'package' => 'AspectRatioParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-aspect-ratio'
        ],
        'auto_sharpen' => [
            'category' => 'transformational',
            'package' => 'SharpenParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-auto-sharpen'
        ],
        'bg_color' => [
            'category' => 'transformational',
            'package' => 'BackgroundParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-bg-color'
        ],
        'border' => [
            'category' => 'transformational', 
            'package' => 'BorderParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-border'
        ],
        'crop' => [
            'category' => 'transformational', 
            'package' => 'CropParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-crop'
        ],
        // Structured crop rectangle (percent-of-source): "left,top,width,height".
        // Used by fieldtype/editor tooling to represent a zoom+pan crop window.
        'crop_rect' => [
            'category' => 'transformational',
            'package' => 'CropParameter'
        ],
        'face_crop_margin' => [
            'category' => 'transformational',
            'package' => 'FaceDetectionParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-face-crop-margin'
        ],
        'face_detect_sensitivity' => [
            'category' => 'transformational',
            'package' => 'FaceDetectionParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-face-detect-sensitivity'
        ],
        'face_detection_quality' => [
            'category' => 'transformational',
            'package' => 'FaceDetectionParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-face-detection-quality'
        ],
        'fallback_src' => [
            'category' => 'transformational',
            'package' => 'FallbackParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-fallback-src'
        ],
        'filter' => [
            'category' => 'transformational', 
            'package' => 'FilterParameter',
            'doc_url' => 'https://jcogs.net/add-ons/image/documentation#filter'
        ],
        'fit' => [
            'category' => 'transformational',
            'package' => 'ResizeParameter',
            'validator' => EnumValidator::class,
            'validation_config' => [
                'allowed_values' => ['contain', 'cover', 'fill', 'scale-down', 'none', 'distort'],
                'case_sensitive' => false
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-fit'
        ],
        'flip' => [
            'category' => 'transformational',
            'package' => 'TransformParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-flip'
        ],
        'interlace' => [
            'category' => 'transformational',
            'package' => 'OptimizationParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-interlace'
        ],
        'png_quality' => [
            'category' => 'transformational',
            'package' => 'QualityParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 0,
                'max' => 9,
                'allow_decimal' => false
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-png-quality'
        ],
        'preload' => [
            'category' => 'transformational',
            'package' => 'OptimizationParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-preload'
        ],
        'quality' => [
            'category' => 'transformational',
            'package' => 'QualityParameter',
            'validator' => NumericValidator::class,
            'validation_config' => [
                'min' => 1,
                'max' => 100,
                'allow_decimal' => false
            ],
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-quality'
        ],
        'reflection' => [
            'category' => 'transformational', 
            'package' => 'ReflectionParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-reflection'
        ],
        'rotate' => [
            'category' => 'transformational',
            'package' => 'TransformParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-rotate'
        ],
        'rounded_corners' => [
            'category' => 'transformational', 
            'package' => 'RoundedCornersParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-rounded-corners'
        ],
                'text' => [
            'category' => 'transformational', 
            'package' => 'TextParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-text'
        ],
        'watermark' => [
            'category' => 'transformational', 
            'package' => 'WatermarkParameter',
            'doc_url' => 'https://jcogs.net/documentation/jcogs_img/jcogs_img-parameters#jcogs-image-parameter-watermark'
        ],
        
        // ============================================================================
        // PLANNED PRO-SPECIFIC PARAMETERS (v2.1.0+)
        // ============================================================================
        // These are architectural placeholders for future Pro features.
        // Uncomment when implementing the corresponding package class.
        
        // COMPANION ADD-ON FEATURES
        // Parameters requiring separate add-on packages
        // 'face_detect_crop_focus' => ['category' => 'transformational', 'package' => 'FaceDetectionParameter'],
        
        // COLOR ADJUSTMENT PARAMETERS  
        // HSL color space adjustments (different from colorize filter)
        // 'hue' => ['category' => 'transformational', 'package' => 'ColorParameter'],
        // 'saturation' => ['category' => 'transformational', 'package' => 'ColorParameter'],
        // 'lightness' => ['category' => 'transformational', 'package' => 'ColorParameter'],
        
        // ADVANCED TRANSFORMATION PARAMETERS
        // Geometric transformations beyond rotate/flip
        // 'perspective' => ['category' => 'transformational', 'package' => 'AdvancedTransformParameter'],
        // 'distort' => ['category' => 'transformational', 'package' => 'AdvancedTransformParameter'],
        // 'skew' => ['category' => 'transformational', 'package' => 'AdvancedTransformParameter'],
        
        // OPTIMIZATION PARAMETERS
        // File size and encoding optimizations
        // 'progressive' => ['category' => 'transformational', 'package' => 'OptimizationParameter'],
        // 'strip_meta' => ['category' => 'transformational', 'package' => 'OptimizationParameter'],
        // 'optimize' => ['category' => 'transformational', 'package' => 'OptimizationParameter'],
        
        // ============================================================================
        // REMOVED: Filter-based parameters (use filter="name" instead)
        // ============================================================================
        // The following were previously listed but are implemented as filters:
        // - sharpen (use filter="sharpen" or filter="sharpen,amount")
        // - contrast (use filter="contrast,level")  
        // - brightness (use filter="brightness,amount")
        // - blur (use filter="blur" or filter="gaussian_blur,amount")
        // - pixelate (use filter="pixelate,size")
        // - emboss (use filter="emboss")
        // - edge_enhance (use filter="edgedetect" or filter="mean_removal")
        // - find_edges (use filter="edgedetect")
    ];
    
    /**
     * Parameter aliases mapping
     * 
     * Maps alternative parameter names to their canonical names.
     * Format: 'alias_name' => 'canonical_parameter_name'
     * 
     * @var array
     */
    private static array $parameter_aliases = [
        'format' => 'save_type',  // Shorter, more intuitive alias for save_type
        'priority' => 'fetchpriority',
    ];
    
    /**
     * Resolve parameter name from alias to canonical name
     * 
     * @param string $parameter Parameter name (may be alias or canonical)
     * @return string Canonical parameter name
     */
    public static function resolveParameterAlias(string $parameter): string
    {
        $normalized = strtolower(trim($parameter));
        return self::$parameter_aliases[$normalized] ?? $normalized;
    }

    /**
     * Normalize parameter keys to canonical names.
     *
     * Aliases are resolved to canonical names and canonical keys are normalized
     * to lowercase. Unknown keys are preserved as provided. When both alias and
     * canonical keys resolve to the same key, the last encountered value wins.
     *
     * @param array $parameters Raw parameter map
     * @return array Canonicalized parameter map
     */
    public static function normalizeParameterNames(array $parameters): array
    {
        if (empty($parameters)) {
            return $parameters;
        }

        $normalized = [];

        foreach ($parameters as $parameter_name => $parameter_value) {
            $raw_name = (string) $parameter_name;
            $lookup_name = strtolower(trim($raw_name));
            $canonical_name = self::resolveParameterAlias($lookup_name);

            if (array_key_exists($canonical_name, self::$parameter_definitions)
                || array_key_exists($lookup_name, self::$parameter_aliases)) {
                $normalized[$canonical_name] = $parameter_value;
                continue;
            }

            $normalized[$raw_name] = $parameter_value;
        }

        return $normalized;
    }
    
    /**
     * Get parameter category using Legacy categorization
     * 
     * @param string $parameter Parameter name (alias or canonical)
     * @return string Category ('control', 'dimensional', 'transformational')
     */
    public static function getParameterCategory(string $parameter): string
    {
        $canonical = self::resolveParameterAlias($parameter);
        return self::$parameter_definitions[$canonical]['category'] ?? 'control';
    }
    
    /**
     * Get all parameters in a specific category
     * 
     * Used by CacheKeyGenerator to get transformational parameters,
     * ValidationService for category-specific validation, and 
     * Parameter Packages for directory organization.
     * 
     * @param string $category Category name ('control', 'dimensional', 'transformational')
     * @return array Array of parameter names in the category
     */
    public static function getParametersByCategory(string $category): array
    {
        return array_keys(array_filter(
            self::$parameter_definitions, 
            fn($definition) => $definition['category'] === $category
        ));
    }
    
    /**
     * Get parameter package class name
     * 
     * @param string $parameter Parameter name
     * @return string|null Package class name or null if not found
     */
    public static function getParameterPackageClass(string $parameter): ?string
    {
        $canonical = self::resolveParameterAlias($parameter);
        return self::$parameter_definitions[$canonical]['package'] ?? null;
    }
    
    /**
     * Get parameter documentation URL
     * 
     * Automatically resolves aliases to canonical parameter names.
     * 
     * @param string $parameter Parameter name (alias or canonical)
     * @return string|null Documentation URL or null if not available
     */
    public static function getParameterDocumentationUrl(string $parameter): ?string
    {
        $canonical = self::resolveParameterAlias($parameter);
        return self::$parameter_definitions[$canonical]['doc_url'] ?? null;
    }
    
    /**
     * Get all defined parameters
     * 
     * @return array Array of all parameter names
     */
    public static function getAllParameters(): array
    {
        return array_keys(self::$parameter_definitions);
    }
    
    /**
     * Check if parameter exists in registry
     * 
     * @param string $parameter Parameter name
     * @return bool True if parameter is registered
     */
    public static function parameterExists(string $parameter): bool
    {
        $canonical = self::resolveParameterAlias($parameter);
        return array_key_exists($canonical, self::$parameter_definitions);
    }
    
    /**
     * Get parameter definition
     * 
     * Automatically resolves aliases to canonical parameter names.
     * 
     * @param string $parameter Parameter name (alias or canonical)
     * @return array|null Parameter definition array or null if not found
     */
    public static function getParameterDefinition(string $parameter): ?array
    {
        $canonical = self::resolveParameterAlias($parameter);
        return self::$parameter_definitions[$canonical] ?? null;
    }
    
    /**
     * Get all categories
     * 
     * @return array Array of available categories
     */
    public static function getCategories(): array
    {
        return ['control', 'dimensional', 'transformational'];
    }
    
    /**
     * Add parameter to registry (for extensions)
     * 
     * Allows third-party extensions to register new parameters
     * 
     * @param string $parameter Parameter name
     * @param string $category Category ('control', 'dimensional', 'transformational')
     * @param string $package_class Package class name
     * @return void
     */
    public static function registerParameter(string $parameter, string $category, string $package_class): void
    {
        self::$parameter_definitions[$parameter] = [
            'category' => $category,
            'package' => $package_class
        ];
    }

    /**
     * Validate a parameter using registry-defined validation rules
     * 
     * Layer 1 Enhancement: Validates simple parameters using their registered validators.
     * Returns ValidationResult for consistent error handling.
     * 
     * @param string $param_name Parameter name
     * @param mixed $value Value to validate
     * @return ValidationResult Validation result object
     */
    public static function validateParameter(string $param_name, $value): ValidationResult
    {
        $definition = self::getParameterDefinition($param_name);
        
        if (!$definition || !isset($definition['validator'])) {
            return ValidationResult::error("No validator defined for parameter '{$param_name}'", $value);
        }
        
        $validator_class = $definition['validator'];
        $config = $definition['validation_config'] ?? [];
        
        $validator = new $validator_class();
        return $validator->validate($value, $config);
    }

    /**
     * Validate a value using a specified validator type
     * 
     * Layer 1 Enhancement: KEY METHOD for hybrid validation pattern.
     * Allows custom packages to leverage primitive validators without duplication.
     * 
     * @param string $type Validator type ('numeric', 'enum', 'string', 'coordinates', 'percentage')
     * @param mixed $value Value to validate
     * @param array $config Validator configuration
     * @return ValidationResult Validation result object
     */
    public static function validateValue(string $type, $value, array $config = []): ValidationResult
    {
        $validator_class = self::getValidatorClass($type);
        
        if (!$validator_class) {
            return ValidationResult::error("Unknown validator type: {$type}", $value);
        }
        
        $validator = new $validator_class();
        return $validator->validate($value, $config);
    }

    /**
     * Check if a parameter has validation rules defined
     * 
     * @param string $param_name Parameter name
     * @return bool True if validation rules exist
     */
    public static function hasValidationRules(string $param_name): bool
    {
        $definition = self::getParameterDefinition($param_name);
        return $definition && isset($definition['validator']);
    }

    /**
     * Get validator class for a given type
     * 
     * @param string $type Validator type
     * @return string|null Fully qualified validator class name or null
     */
    private static function getValidatorClass(string $type): ?string
    {
        $validators = [
            'numeric' => NumericValidator::class,
            'enum' => EnumValidator::class,
            'string' => StringValidator::class,
            'coordinates' => CoordinatesValidator::class,
            'percentage' => PercentageValidator::class,
        ];
        
        return $validators[$type] ?? null;
    }
}
