omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/enums/enum_dedupe_strategy.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Deduplication strategy enum for corpus capture.
+
+Defines how duplicate executions are detected and handled.
+
+.. versionadded:: 0.5.0
+    Added for CorpusCapture (OMN-1203)
+"""
+
+from enum import Enum
+
+
+class EnumDedupeStrategy(str, Enum):
+    """
+    Deduplication strategies for corpus capture.
+
+    When capturing executions, duplicates can be detected and filtered
+    using different strategies based on what constitutes a "duplicate".
+
+    .. versionadded:: 0.5.0
+        Added for CorpusCapture (OMN-1203)
+    """
+
+    NONE = "none"
+    """No deduplication. All executions are captured."""
+
+    INPUT_HASH = "input_hash"
+    """
+    Deduplicate based on input hash.
+
+    Two executions with the same handler and input data are considered
+    duplicates. This is useful for capturing unique test cases without
+    redundant variations.
+    """
+
+    FULL_MANIFEST_HASH = "full_manifest_hash"
+    """
+    Deduplicate based on full manifest hash.
+
+    Only exact duplicates (same handler, input, output, timing, etc.)
+    are filtered. This preserves executions that had different outcomes
+    even with the same input.
+    """

omnibase_infra/enums/enum_dispatch_status.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Dispatch Status Enumeration.
+
+Defines status values for message dispatch operations in the runtime dispatch engine.
+Used to track the outcome of routing and handler execution.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumDispatchStatus(str, Enum):
+    """
+    Status values for dispatch operations.
+
+    Represents the outcome of a message dispatch operation, from initial
+    routing through handler execution and result publishing.
+
+    Values:
+        SUCCESS: Message was successfully routed, handled, and outputs published
+        ROUTED: Message was successfully routed to a dispatcher (not yet executed)
+        NO_DISPATCHER: No dispatcher was registered for the message type/topic
+        HANDLER_ERROR: Dispatcher execution failed with an exception
+        TIMEOUT: Dispatcher execution exceeded the configured timeout
+        INVALID_MESSAGE: Message failed validation before dispatch
+        PUBLISH_FAILED: Dispatcher succeeded but output publishing failed
+        SKIPPED: Message was intentionally skipped (e.g., filtered, deduplicated)
+        INTERNAL_ERROR: Internal error during dispatch result construction
+
+    Example:
+        >>> status = EnumDispatchStatus.SUCCESS
+        >>> status.is_terminal()
+        True
+        >>> EnumDispatchStatus.ROUTED.is_successful()
+        False
+        >>> str(EnumDispatchStatus.HANDLER_ERROR)
+        'handler_error'
+    """
+
+    SUCCESS = "success"
+    """Message was successfully routed, handled, and outputs published."""
+
+    ROUTED = "routed"
+    """Message was successfully routed to a dispatcher (pending execution)."""
+
+    NO_DISPATCHER = "no_dispatcher"
+    """No dispatcher was registered for the message type/topic."""
+
+    HANDLER_ERROR = "handler_error"
+    """Dispatcher execution failed with an exception."""
+
+    TIMEOUT = "timeout"
+    """Dispatcher execution exceeded the configured timeout."""
+
+    INVALID_MESSAGE = "invalid_message"
+    """Message failed validation before dispatch."""
+
+    PUBLISH_FAILED = "publish_failed"
+    """Dispatcher succeeded but output publishing failed."""
+
+    SKIPPED = "skipped"
+    """Message was intentionally skipped (e.g., filtered, deduplicated)."""
+
+    INTERNAL_ERROR = "internal_error"
+    """Internal error during dispatch result construction (e.g., Pydantic ValidationError)."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def is_terminal(self) -> bool:
+        """
+        Check if this status represents a terminal state.
+
+        Terminal states indicate the dispatch operation has completed
+        (either successfully or with a failure).
+
+        Returns:
+            True if the status represents a terminal state, False otherwise
+
+        Example:
+            >>> EnumDispatchStatus.SUCCESS.is_terminal()
+            True
+            >>> EnumDispatchStatus.ROUTED.is_terminal()
+            False
+        """
+        return self in {
+            EnumDispatchStatus.SUCCESS,
+            EnumDispatchStatus.NO_DISPATCHER,
+            EnumDispatchStatus.HANDLER_ERROR,
+            EnumDispatchStatus.TIMEOUT,
+            EnumDispatchStatus.INVALID_MESSAGE,
+            EnumDispatchStatus.PUBLISH_FAILED,
+            EnumDispatchStatus.SKIPPED,
+            EnumDispatchStatus.INTERNAL_ERROR,
+        }
+
+    def is_successful(self) -> bool:
+        """
+        Check if this status represents a successful dispatch.
+
+        Returns:
+            True only if status is SUCCESS, False otherwise
+
+        Example:
+            >>> EnumDispatchStatus.SUCCESS.is_successful()
+            True
+            >>> EnumDispatchStatus.ROUTED.is_successful()
+            False
+        """
+        return self == EnumDispatchStatus.SUCCESS
+
+    def is_error(self) -> bool:
+        """
+        Check if this status represents an error condition.
+
+        Returns:
+            True if the status represents an error, False otherwise
+
+        Example:
+            >>> EnumDispatchStatus.HANDLER_ERROR.is_error()
+            True
+            >>> EnumDispatchStatus.SUCCESS.is_error()
+            False
+        """
+        return self in {
+            EnumDispatchStatus.NO_DISPATCHER,
+            EnumDispatchStatus.HANDLER_ERROR,
+            EnumDispatchStatus.TIMEOUT,
+            EnumDispatchStatus.INVALID_MESSAGE,
+            EnumDispatchStatus.PUBLISH_FAILED,
+            EnumDispatchStatus.INTERNAL_ERROR,
+        }
+
+    def requires_retry(self) -> bool:
+        """
+        Check if this status indicates the operation should be retried.
+
+        Only transient failures (timeout, publish_failed) should be retried.
+        Permanent failures (no_dispatcher, invalid_message) should not be retried.
+
+        Returns:
+            True if the operation should be retried, False otherwise
+
+        Example:
+            >>> EnumDispatchStatus.TIMEOUT.requires_retry()
+            True
+            >>> EnumDispatchStatus.NO_DISPATCHER.requires_retry()
+            False
+        """
+        return self in {
+            EnumDispatchStatus.TIMEOUT,
+            EnumDispatchStatus.PUBLISH_FAILED,
+        }
+
+    @classmethod
+    def get_description(cls, status: "EnumDispatchStatus") -> str:
+        """
+        Get a human-readable description of the dispatch status.
+
+        Args:
+            status: The dispatch status to describe
+
+        Returns:
+            A human-readable description of the status
+
+        Example:
+            >>> EnumDispatchStatus.get_description(EnumDispatchStatus.SUCCESS)
+            'Message was successfully routed, handled, and outputs published'
+        """
+        descriptions = {
+            cls.SUCCESS: "Message was successfully routed, handled, and outputs published",
+            cls.ROUTED: "Message was successfully routed to a dispatcher (pending execution)",
+            cls.NO_DISPATCHER: "No dispatcher was registered for the message type/topic",
+            cls.HANDLER_ERROR: "Dispatcher execution failed with an exception",
+            cls.TIMEOUT: "Dispatcher execution exceeded the configured timeout",
+            cls.INVALID_MESSAGE: "Message failed validation before dispatch",
+            cls.PUBLISH_FAILED: "Dispatcher succeeded but output publishing failed",
+            cls.SKIPPED: "Message was intentionally skipped",
+            cls.INTERNAL_ERROR: "Internal error during dispatch result construction",
+        }
+        return descriptions.get(status, "Unknown dispatch status")
+
+
+__all__ = ["EnumDispatchStatus"]

omnibase_infra/enums/enum_environment.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Environment enumeration for deployment target classification.
+
+This module defines the deployment environment types used for security policy
+validation and configuration management. Environment-aware security policies
+can enforce different constraints based on the deployment target.
+
+Usage:
+    The EnumEnvironment is used in security policy models to define
+    environment-specific constraints and in configuration to specify
+    the current deployment target.
+
+See Also:
+    - ModelEnvironmentPolicy: Uses this enum for environment-specific constraints
+    - ModelHandlerSecurityPolicy: Handler-declared security requirements
+"""
+
+from enum import Enum
+
+
+class EnumEnvironment(str, Enum):
+    """Deployment environment classification.
+
+    Defines the deployment environments for security policy enforcement
+    and configuration management. Each environment has different security
+    postures and permitted capabilities.
+
+    Attributes:
+        DEVELOPMENT: Local development environment.
+            Most permissive, allows debugging features and relaxed security.
+        STAGING: Pre-production testing environment.
+            Production-like but allows some testing features.
+        PRODUCTION: Live production environment.
+            Most restrictive, enforces all security constraints.
+        CI: Continuous integration environment.
+            Automated testing, may have elevated permissions for test execution.
+    """
+
+    DEVELOPMENT = "development"
+    STAGING = "staging"
+    PRODUCTION = "production"
+    CI = "ci"
+
+
+__all__ = ["EnumEnvironment"]

omnibase_infra/enums/enum_execution_shape_violation.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execution Shape Violation Enumeration.
+
+Defines the canonical violation types for the ONEX execution shape validator.
+These violations represent constraint breaches in the ONEX 4-node architecture
+that would compromise system integrity or determinism guarantees.
+
+Violation Categories:
+    - Return Type Violations: Handler returning forbidden output types
+    - Direct Publish Violations: Handler bypassing event bus routing
+    - Determinism Violations: Handler accessing non-deterministic resources
+    - Topic Mismatch Violations: Handler subscribed to wrong topic category
+
+Note on PROJECTION Violations:
+    PROJECTION is a valid node output type (EnumNodeOutputType.PROJECTION) that
+    ONLY REDUCERs may produce. It is NOT a message routing category (not in
+    EnumMessageCategory). This distinction is critical:
+
+    - EnumNodeOutputType: Defines what a node CAN produce (includes PROJECTION)
+    - EnumMessageCategory: Defines how messages are ROUTED (excludes PROJECTION)
+
+    Projections represent aggregated state from REDUCER nodes. They are not
+    routed via Kafka topics like EVENTs, COMMANDs, and INTENTs. Violations like
+    ORCHESTRATOR_RETURNS_PROJECTIONS or EFFECT_RETURNS_PROJECTIONS indicate a
+    non-REDUCER node is incorrectly trying to produce aggregated state output.
+
+See Also:
+    - EnumNodeOutputType: Defines valid node output types (includes PROJECTION)
+    - EnumMessageCategory: Defines message categories for routing (excludes PROJECTION)
+    - EnumHandlerType: Defines the 4-node architecture handler types
+"""
+
+from enum import Enum
+
+
+class EnumExecutionShapeViolation(str, Enum):
+    """Execution shape violation types for ONEX architecture compliance.
+
+    These represent constraint violations detected during static analysis
+    of ONEX handlers. Each violation type indicates a specific breach of
+    the 4-node architecture rules.
+
+    Return Type Violations:
+        FORBIDDEN_RETURN_TYPE: Generic violation for handler returning forbidden type.
+            Used as fallback when no specific violation type is mapped.
+        REDUCER_RETURNS_EVENTS: Reducer handlers cannot emit events.
+            Reducers manage state; event emission is an effect operation.
+        ORCHESTRATOR_RETURNS_INTENTS: Orchestrators cannot emit intents.
+            Intents originate from external systems, not orchestration.
+        ORCHESTRATOR_RETURNS_PROJECTIONS: Orchestrators cannot produce projections.
+            PROJECTION is a node output type (EnumNodeOutputType.PROJECTION), NOT a
+            message routing category (EnumMessageCategory). Projections represent
+            aggregated state and are ONLY valid for REDUCER node output types.
+            Orchestrators coordinate workflows and should return COMMANDs or EVENTs.
+        EFFECT_RETURNS_PROJECTIONS: Effect handlers cannot produce projections.
+            PROJECTION is a node output type (EnumNodeOutputType.PROJECTION), NOT a
+            message routing category (EnumMessageCategory). Projections represent
+            aggregated state and are ONLY valid for REDUCER node output types.
+            Effect handlers interact with external systems and should return
+            EVENTs or COMMANDs.
+
+    Operation Violations:
+        HANDLER_DIRECT_PUBLISH: Handler bypasses event bus for direct publish.
+            All message routing must go through the event bus abstraction.
+        REDUCER_ACCESSES_SYSTEM_TIME: Reducer accesses non-deterministic time.
+            Reducers must be deterministic for replay consistency.
+
+    Topic Violations:
+        TOPIC_CATEGORY_MISMATCH: Handler subscribed to wrong topic category.
+            Event handlers should subscribe to event topics, etc.
+
+    Routing Violations:
+        UNMAPPED_MESSAGE_ROUTE: Message type is not registered in routing.
+            All message types must have explicit route registrations.
+
+    Syntax/Parse Violations:
+        SYNTAX_ERROR: File contains invalid Python syntax.
+            File could not be parsed for analysis due to syntax errors.
+    """
+
+    # Return type violations
+    FORBIDDEN_RETURN_TYPE = "forbidden_return_type"
+    REDUCER_RETURNS_EVENTS = "reducer_returns_events"
+    ORCHESTRATOR_RETURNS_INTENTS = "orchestrator_returns_intents"
+    ORCHESTRATOR_RETURNS_PROJECTIONS = "orchestrator_returns_projections"
+    EFFECT_RETURNS_PROJECTIONS = "effect_returns_projections"
+
+    # Operation violations
+    HANDLER_DIRECT_PUBLISH = "handler_direct_publish"
+    REDUCER_ACCESSES_SYSTEM_TIME = "reducer_accesses_system_time"
+
+    # Topic violations
+    TOPIC_CATEGORY_MISMATCH = "topic_category_mismatch"
+
+    # Routing violations
+    UNMAPPED_MESSAGE_ROUTE = "unmapped_message_route"
+
+    # Syntax/parse violations
+    SYNTAX_ERROR = "syntax_error"
+
+
+__all__ = ["EnumExecutionShapeViolation"]

omnibase_infra/enums/enum_handler_error_type.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Error Type Enumeration.
+
+Defines the canonical error types for handler validation and lifecycle management.
+These error types represent failures that can occur during handler registration,
+validation, configuration, and execution within the ONEX infrastructure.
+
+Error Categories:
+    - Contract Errors: YAML parsing and schema validation failures
+    - Validation Errors: Descriptor and constraint validation failures
+    - Configuration Errors: Handler configuration and setup failures
+    - Registration Errors: Handler registration and lifecycle failures
+    - Type Errors: Handler type mismatches and compatibility issues
+    - Security Errors: Security constraint violations
+    - Architecture Errors: ONEX architecture pattern violations
+    - Execution Errors: Runtime execution shape violations
+
+These error types provide structured classification for handler-related failures,
+enabling precise error reporting, debugging, and recovery strategies.
+
+See Also:
+    - EnumExecutionShapeViolation: Specific execution shape violations
+    - EnumHandlerType: Defines the 4-node architecture handler types
+    - ModelHandlerValidationError: Structured error reporting model
+"""
+
+from enum import Enum
+
+
+class EnumHandlerErrorType(str, Enum):
+    """Handler error types for validation and lifecycle management.
+
+    These represent structured error classifications for failures that occur
+    during handler validation, registration, configuration, and execution.
+    Each error type indicates a specific category of failure.
+
+    Contract Errors:
+        CONTRACT_PARSE_ERROR: Contract YAML parsing failed.
+            The handler's contract.yaml file could not be parsed due to
+            invalid YAML syntax or structure.
+        CONTRACT_VALIDATION_ERROR: Contract field validation failed.
+            The parsed contract contains invalid field values or violates
+            schema constraints defined in the ONEX contract specification.
+
+    Validation Errors:
+        DESCRIPTOR_VALIDATION_ERROR: Handler descriptor validation failed.
+            The handler descriptor (metadata, annotations, signature) does not
+            meet ONEX requirements for the declared handler type.
+        SECURITY_VALIDATION_ERROR: Security constraint violated.
+            The handler violates security policies such as introspection
+            restrictions, input validation requirements, or secret handling.
+        ARCHITECTURE_VALIDATION_ERROR: Architecture pattern violated.
+            The handler violates ONEX architectural patterns such as layering,
+            dependency injection, or node archetype responsibilities.
+
+    Execution Errors:
+        EXECUTION_SHAPE_VIOLATION: ONEX execution shape violated.
+            The handler violates execution shape constraints defined by the
+            4-node architecture (e.g., REDUCER returning events, direct publish).
+            See EnumExecutionShapeViolation for specific violation types.
+
+    Configuration Errors:
+        CONFIGURATION_ERROR: Handler configuration invalid.
+            The handler's configuration (environment variables, service endpoints,
+            container dependencies) is invalid or incomplete.
+
+    Registration Errors:
+        REGISTRATION_ERROR: Handler registration failed.
+            The handler could not be registered with the handler registry due to
+            duplicate registration, missing dependencies, or lifecycle failures.
+
+    Type Errors:
+        TYPE_MISMATCH_ERROR: Handler type doesn't match expected.
+            The handler's declared type (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)
+            does not match the contract specification or runtime behavior.
+    """
+
+    # Contract errors
+    CONTRACT_PARSE_ERROR = "contract_parse_error"
+    CONTRACT_VALIDATION_ERROR = "contract_validation_error"
+
+    # Validation errors
+    DESCRIPTOR_VALIDATION_ERROR = "descriptor_validation_error"
+    SECURITY_VALIDATION_ERROR = "security_validation_error"
+    ARCHITECTURE_VALIDATION_ERROR = "architecture_validation_error"
+
+    # Execution errors
+    EXECUTION_SHAPE_VIOLATION = "execution_shape_violation"
+
+    # Configuration errors
+    CONFIGURATION_ERROR = "configuration_error"
+
+    # Registration errors
+    REGISTRATION_ERROR = "registration_error"
+
+    # Type errors
+    TYPE_MISMATCH_ERROR = "type_mismatch_error"
+
+
+__all__ = ["EnumHandlerErrorType"]

omnibase_infra/enums/enum_handler_loader_error.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Loader Error Code Enumeration.
+
+Defines structured error codes for the HandlerPluginLoader system. These codes
+enable precise error classification, debugging, and programmatic error handling
+for handler contract discovery and loading operations.
+
+Error Code Ranges:
+    - 001-009: File-level errors (load_from_contract)
+    - 010-019: Import errors (handler class loading)
+    - 020-029: Directory-level errors (load_from_directory)
+    - 030-039: Pattern errors (discover_and_load)
+    - 040-049: Configuration errors (ambiguous configurations)
+
+Usage:
+    >>> from omnibase_infra.enums import EnumHandlerLoaderError
+    >>> error_code = EnumHandlerLoaderError.FILE_NOT_FOUND
+    >>> print(f"Error: {error_code.value}")
+    Error: HANDLER_LOADER_001
+
+    >>> # Check error code in exception handling
+    >>> try:
+    ...     loader.load_from_contract(path)
+    ... except ProtocolConfigurationError as e:
+    ...     if e.model.context.get("loader_error") == EnumHandlerLoaderError.NOT_A_FILE.value:
+    ...         print("Path exists but is not a file")
+
+See Also:
+    - HandlerPluginLoader: Implementation using these error codes
+    - ProtocolHandlerPluginLoader: Protocol defining error code contracts
+"""
+
+from enum import Enum
+
+
+class EnumHandlerLoaderError(str, Enum):
+    """Error codes for handler plugin loader operations.
+
+    These codes provide structured classification for failures during
+    handler contract discovery, parsing, validation, and class loading.
+
+    File-Level Errors (001-009):
+        FILE_NOT_FOUND: Contract file path does not exist.
+            The specified contract file path does not exist on the filesystem.
+            Verify the path is correct and the file has not been moved/deleted.
+
+        INVALID_YAML_SYNTAX: Contract file contains invalid YAML.
+            The contract file could not be parsed due to YAML syntax errors.
+            Check for proper indentation, quoting, and YAML structure.
+
+        SCHEMA_VALIDATION_FAILED: Contract fails schema validation.
+            The parsed YAML does not conform to the handler contract schema.
+            This includes empty files or files with only comments.
+
+        MISSING_REQUIRED_FIELDS: Contract is missing required fields.
+            Required fields (handler_name, handler_class, handler_type) are missing.
+            Add the missing fields to the contract file.
+
+        FILE_SIZE_EXCEEDED: Contract file exceeds size limit.
+            The contract file exceeds the maximum allowed size (10MB).
+            Contract files should be small configuration files.
+
+        PROTOCOL_NOT_IMPLEMENTED: Handler does not implement protocol.
+            The handler class does not implement the required ProtocolHandler
+            interface (missing required methods like describe, initialize, etc.).
+
+        NOT_A_FILE: Path exists but is not a regular file.
+            The specified path exists but is a directory, symlink, or other
+            non-regular file type. Only regular files can be loaded as contracts.
+
+        FILE_READ_ERROR: Failed to read contract file.
+            An I/O error occurred while reading the contract file contents.
+            Check file permissions and filesystem accessibility.
+
+        FILE_STAT_ERROR: Failed to stat contract file.
+            An I/O error occurred while checking file metadata (size, type).
+            Check file permissions and filesystem accessibility.
+
+    Import Errors (010-019):
+        MODULE_NOT_FOUND: Handler module not found.
+            The module specified in handler_class cannot be found.
+            Verify the module path and ensure it's installed/accessible.
+
+        CLASS_NOT_FOUND: Handler class not found in module.
+            The module exists but does not contain the specified class.
+            Verify the class name matches exactly (case-sensitive).
+
+        IMPORT_ERROR: Import error loading handler module.
+            The module exists but failed to import due to syntax errors,
+            missing dependencies, or circular imports.
+
+        NAMESPACE_NOT_ALLOWED: Handler module namespace not in allowed list.
+            The handler module's namespace (package prefix) is not in the
+            configured allowed_namespaces list. This is a security control to
+            prevent loading handlers from untrusted packages. Add the module's
+            namespace prefix to allowed_namespaces or remove the restriction.
+
+    Directory Errors (020-029):
+        DIRECTORY_NOT_FOUND: Directory does not exist.
+            The specified directory path does not exist on the filesystem.
+
+        PERMISSION_DENIED: Permission denied accessing directory.
+            Insufficient permissions to read the directory contents.
+
+        NOT_A_DIRECTORY: Path exists but is not a directory.
+            The specified path exists but is a file or other non-directory.
+
+    Pattern Errors (030-039):
+        EMPTY_PATTERNS_LIST: Patterns list cannot be empty.
+            The discover_and_load method requires at least one glob pattern.
+
+        INVALID_GLOB_PATTERN: Invalid glob pattern syntax.
+            The provided glob pattern has invalid syntax.
+
+    Configuration Errors (040-049):
+        AMBIGUOUS_CONTRACT_CONFIGURATION: Both handler_contract.yaml and contract.yaml
+            exist in the same directory. This is an ambiguous configuration that could
+            lead to duplicate handler registrations or unexpected behavior. Use only
+            ONE contract file per handler directory to avoid this error.
+    """
+
+    # File-level errors (001-009)
+    FILE_NOT_FOUND = "HANDLER_LOADER_001"
+    INVALID_YAML_SYNTAX = "HANDLER_LOADER_002"
+    SCHEMA_VALIDATION_FAILED = "HANDLER_LOADER_003"
+    MISSING_REQUIRED_FIELDS = "HANDLER_LOADER_004"
+    FILE_SIZE_EXCEEDED = "HANDLER_LOADER_005"
+    PROTOCOL_NOT_IMPLEMENTED = "HANDLER_LOADER_006"
+    NOT_A_FILE = "HANDLER_LOADER_007"
+    FILE_READ_ERROR = "HANDLER_LOADER_008"
+    FILE_STAT_ERROR = "HANDLER_LOADER_009"
+
+    # Import errors (010-019)
+    MODULE_NOT_FOUND = "HANDLER_LOADER_010"
+    CLASS_NOT_FOUND = "HANDLER_LOADER_011"
+    IMPORT_ERROR = "HANDLER_LOADER_012"
+    NAMESPACE_NOT_ALLOWED = "HANDLER_LOADER_013"
+
+    # Directory errors (020-029)
+    DIRECTORY_NOT_FOUND = "HANDLER_LOADER_020"
+    PERMISSION_DENIED = "HANDLER_LOADER_021"
+    NOT_A_DIRECTORY = "HANDLER_LOADER_022"
+
+    # Pattern errors (030-039)
+    EMPTY_PATTERNS_LIST = "HANDLER_LOADER_030"
+    INVALID_GLOB_PATTERN = "HANDLER_LOADER_031"
+
+    # Configuration errors (040-049)
+    AMBIGUOUS_CONTRACT_CONFIGURATION = "HANDLER_LOADER_040"
+
+    @property
+    def is_file_error(self) -> bool:
+        """Check if this is a file-level error (001-009)."""
+        return self.value.startswith("HANDLER_LOADER_00")
+
+    @property
+    def is_import_error(self) -> bool:
+        """Check if this is an import error (010-019)."""
+        return self.value.startswith("HANDLER_LOADER_01")
+
+    @property
+    def is_directory_error(self) -> bool:
+        """Check if this is a directory error (020-029)."""
+        return self.value.startswith("HANDLER_LOADER_02")
+
+    @property
+    def is_pattern_error(self) -> bool:
+        """Check if this is a pattern error (030-039)."""
+        return self.value.startswith("HANDLER_LOADER_03")
+
+    @property
+    def is_configuration_error(self) -> bool:
+        """Check if this is a configuration error (040-049)."""
+        return self.value.startswith("HANDLER_LOADER_04")
+
+
+__all__ = ["EnumHandlerLoaderError"]