omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/runtime/model_handler_contract.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Contract Model for Contract-Driven Discovery.
+
+This module provides ModelHandlerContract, a Pydantic model that represents the
+schema for handler contract YAML files. It replaces manual field extraction in
+HandlerPluginLoader with automatic validation and type coercion.
+
+The model supports dual field names for flexibility:
+- handler_name / name
+- capability_tags / tags
+
+See Also:
+    - HandlerPluginLoader: Uses this model to validate contracts
+    - ModelLoadedHandler: Output model after successful loading
+    - EnumHandlerTypeCategory: Handler behavioral classification
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Handler Plugin Loader implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+logger = logging.getLogger(__name__)
+
+from omnibase_core.models.primitives import ModelSemVer
+from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
+from omnibase_infra.errors import ProtocolConfigurationError
+from omnibase_infra.models.runtime.model_contract_security_config import (
+    ModelContractSecurityConfig,
+)
+
+# Handler type category mapping from contract strings to enum
+_HANDLER_TYPE_CATEGORY_MAP: dict[str, EnumHandlerTypeCategory] = {
+    "compute": EnumHandlerTypeCategory.COMPUTE,
+    "effect": EnumHandlerTypeCategory.EFFECT,
+    "nondeterministic_compute": EnumHandlerTypeCategory.NONDETERMINISTIC_COMPUTE,
+}
+
+
+class ModelHandlerContract(BaseModel):
+    """Pydantic model for handler contract YAML schema.
+
+    Validates and parses handler contract YAML files with automatic type
+    coercion and field aliasing. Supports dual field names for flexibility
+    in contract authoring.
+
+    Field Aliases:
+        - handler_name: Also accepts 'name'
+        - capability_tags: Also accepts 'tags'
+
+    Handler Type Conversion:
+        The handler_type field accepts string values (e.g., 'compute', 'effect',
+        'nondeterministic_compute') and converts them to EnumHandlerTypeCategory
+        enum values. Case-insensitive matching is supported.
+
+    Attributes:
+        handler_name: Unique identifier for the handler. Required field
+            that accepts both 'handler_name' and 'name' keys in YAML.
+        handler_class: Fully qualified class path for the handler
+            (e.g., 'myapp.handlers.AuthHandler'). Required field.
+        handler_type: Behavioral classification of the handler. Required field
+            that accepts string values and converts to EnumHandlerTypeCategory.
+        capability_tags: List of tags for handler discovery and filtering.
+            Optional field that accepts both 'capability_tags' and 'tags' keys.
+
+    Example:
+        >>> from omnibase_infra.models.runtime import ModelHandlerContract
+        >>> # Parse from YAML dict with 'name' alias
+        >>> contract = ModelHandlerContract.model_validate({
+        ...     "name": "auth.handler",
+        ...     "handler_class": "myapp.handlers.AuthHandler",
+        ...     "handler_type": "compute",
+        ...     "tags": ["auth", "validation"],
+        ... })
+        >>> contract.handler_name
+        'auth.handler'
+        >>> contract.handler_type
+        <EnumHandlerTypeCategory.COMPUTE: 'compute'>
+
+        >>> # Parse with canonical field names
+        >>> contract = ModelHandlerContract.model_validate({
+        ...     "handler_name": "db.handler",
+        ...     "handler_class": "myapp.handlers.DbHandler",
+        ...     "handler_type": "effect",
+        ...     "capability_tags": ["database", "postgres"],
+        ... })
+
+    See Also:
+        - :class:`HandlerPluginLoader`: Uses this model for contract validation.
+        - :class:`ModelLoadedHandler`: Output model after successful loading.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+
+    handler_name: str = Field(
+        ...,
+        min_length=1,
+        validation_alias="name",
+        description="Unique identifier for the handler (also accepts 'name')",
+    )
+    handler_class: str = Field(
+        ...,
+        min_length=1,
+        description="Fully qualified handler class path (e.g., 'myapp.handlers.AuthHandler')",
+    )
+    handler_type: EnumHandlerTypeCategory = Field(
+        ...,
+        description="Behavioral classification (compute, effect, nondeterministic_compute)",
+    )
+    capability_tags: list[str] = Field(
+        default_factory=list,
+        validation_alias="tags",
+        description="Tags for handler discovery and filtering (also accepts 'tags')",
+    )
+    protocol_type: str | None = Field(
+        default=None,
+        description=(
+            "Protocol type identifier for registry (e.g., 'db', 'http', 'consul'). "
+            "If not provided, defaults to handler_name with 'handler-' prefix stripped."
+        ),
+    )
+    security: ModelContractSecurityConfig | None = Field(
+        default=None,
+        description="Optional security configuration for the handler",
+    )
+    handler_version: ModelSemVer | None = Field(
+        default=None,
+        description="Handler version in semantic versioning format. If not provided, defaults to 1.0.0",
+    )
+
+    @field_validator("handler_type", mode="before")
+    @classmethod
+    def convert_handler_type(cls, value: object) -> EnumHandlerTypeCategory:
+        """Convert string handler_type to EnumHandlerTypeCategory.
+
+        Accepts case-insensitive string values and converts them to the
+        appropriate enum value. Also accepts EnumHandlerTypeCategory directly.
+
+        Args:
+            value: String handler type name or EnumHandlerTypeCategory.
+
+        Returns:
+            EnumHandlerTypeCategory enum value.
+
+        Raises:
+            ValueError: If the value is not a valid handler type.
+        """
+        # Already an enum
+        if isinstance(value, EnumHandlerTypeCategory):
+            return value
+
+        # Convert string to enum
+        if isinstance(value, str):
+            normalized = value.lower().strip()
+            if normalized in _HANDLER_TYPE_CATEGORY_MAP:
+                return _HANDLER_TYPE_CATEGORY_MAP[normalized]
+
+            valid_types = ", ".join(_HANDLER_TYPE_CATEGORY_MAP.keys())
+            raise ValueError(
+                f"Invalid handler_type '{value}'. Valid types: {valid_types}"
+            )
+
+        raise ValueError(
+            f"handler_type must be a string or EnumHandlerTypeCategory, got {type(value).__name__}"
+        )
+
+    @field_validator("capability_tags", mode="before")
+    @classmethod
+    def normalize_capability_tags(cls, value: object) -> list[str]:
+        """Normalize capability_tags to a list of strings.
+
+        Handles various input formats:
+        - None -> empty list
+        - Single string -> list with one element
+        - List with mixed types -> filter to strings only
+
+        Args:
+            value: Raw value from YAML (None, str, or list).
+
+        Returns:
+            List of string capability tags.
+        """
+        if value is None:
+            return []
+
+        if isinstance(value, str):
+            return [value]
+
+        if isinstance(value, list):
+            # Filter to only string tags, warn about invalid types
+            valid_tags: list[str] = []
+            for tag in value:
+                if isinstance(tag, str):
+                    valid_tags.append(tag)
+                else:
+                    logger.warning(
+                        "Non-string capability tag filtered out: value=%r, type=%s",
+                        tag,
+                        type(tag).__name__,
+                    )
+            return valid_tags
+
+        return []
+
+    @model_validator(mode="after")
+    def set_defaults(self) -> ModelHandlerContract:
+        """Set default values for protocol_type and handler_version.
+
+        Protocol Type:
+            If protocol_type is None, derives it from handler_name by stripping
+            the 'handler-' prefix. If handler_name doesn't have that prefix,
+            uses the full handler_name as protocol_type.
+
+            Guards against empty derived protocol_type which would produce
+            invalid registry keys.
+
+        Handler Version:
+            If handler_version is None, sets it to the default version 1.0.0.
+
+        Returns:
+            Self with protocol_type and handler_version populated.
+
+        Raises:
+            ValueError: If derived protocol_type would be empty (e.g., handler_name
+                is exactly "handler-" with nothing after the prefix).
+
+        Example:
+            >>> contract = ModelHandlerContract(
+            ...     handler_name="handler-db",
+            ...     handler_class="myapp.handlers.DbHandler",
+            ...     handler_type="effect",
+            ... )
+            >>> contract.protocol_type
+            'db'
+            >>> contract.handler_version
+            ModelSemVer(major=1, minor=0, patch=0)
+
+            >>> contract = ModelHandlerContract(
+            ...     handler_name="custom-handler",
+            ...     handler_class="myapp.handlers.Custom",
+            ...     handler_type="compute",
+            ... )
+            >>> contract.protocol_type
+            'custom-handler'
+        """
+        # Set default handler_version if not provided
+        if self.handler_version is None:
+            self.handler_version = ModelSemVer(major=1, minor=0, patch=0)
+
+        if self.protocol_type is None:
+            prefix = "handler-"
+            if self.handler_name.startswith(prefix):
+                derived = self.handler_name[len(prefix) :]
+                if not derived:
+                    raise ProtocolConfigurationError(
+                        f"Cannot derive protocol_type from handler_name '{self.handler_name}': "
+                        f"result would be empty. Either provide an explicit protocol_type "
+                        f"or use a handler_name with content after the 'handler-' prefix."
+                    )
+                self.protocol_type = derived
+            else:
+                self.protocol_type = self.handler_name
+
+        # Final guard: ensure protocol_type is never empty
+        if not self.protocol_type:
+            raise ProtocolConfigurationError(
+                f"protocol_type cannot be empty. handler_name='{self.handler_name}', "
+                f"derived protocol_type='{self.protocol_type}'. "
+                f"Provide a non-empty protocol_type or handler_name."
+            )
+
+        # Log successful contract validation for debugging
+        logger.debug(
+            "Handler contract validated successfully",
+            extra={
+                "handler_name": self.handler_name,
+                "handler_class": self.handler_class,
+                "protocol_type": self.protocol_type,
+                "handler_type": self.handler_type.value,
+                "handler_version": str(self.handler_version),
+            },
+        )
+
+        return self
+
+
+__all__ = ["ModelHandlerContract"]

omnibase_infra/models/runtime/model_loaded_handler.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Loaded Handler Model for Handler Plugin Loader.
+
+This module provides ModelLoadedHandler, which represents a handler that has been
+successfully discovered, validated, and registered by the HandlerPluginLoader.
+
+The model captures essential metadata about loaded handlers for runtime tracking,
+discovery filtering, and diagnostic purposes.
+
+See Also:
+    - HandlerPluginLoader: Loader that creates these descriptors
+    - ModelHandlerDescriptor: Contract-level handler descriptor
+    - EnumHandlerTypeCategory: Handler behavioral classification
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Handler Plugin Loader implementation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.models.primitives import ModelSemVer
+from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
+
+
+class ModelLoadedHandler(BaseModel):
+    """Represents a handler loaded from a contract.
+
+    Tracks metadata about handlers that have been successfully discovered,
+    validated, and registered by the HandlerPluginLoader.
+
+    This model is used for:
+    - Runtime handler registry tracking
+    - Handler discovery and filtering by capability tags
+    - Diagnostics and introspection of loaded handlers
+    - Audit logging of handler loading events
+
+    Attributes:
+        handler_name: Unique identifier for the handler. Used as the primary
+            key for handler registry lookups.
+        handler_type: Behavioral classification of the handler (COMPUTE, EFFECT,
+            or NONDETERMINISTIC_COMPUTE). Determines policy envelope and runtime
+            behavior.
+        handler_class: Fully qualified class name of the handler implementation
+            (e.g., 'myapp.handlers.AuthHandler'). Used for dynamic instantiation.
+        contract_path: Absolute path to the contract YAML file from which this
+            handler was loaded. Used for reloading and validation.
+        capability_tags: List of tags for handler discovery and filtering.
+            Examples: ['auth', 'validation', 'http-client'].
+        loaded_at: Timestamp when the handler was successfully loaded.
+            Used for diagnostics and cache invalidation.
+        handler_version: Semantic version of the handler from the contract.
+            Used for version tracking and compatibility checks.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from pathlib import Path
+        >>> from omnibase_core.models.primitives import ModelSemVer
+        >>> from omnibase_infra.enums import EnumHandlerTypeCategory
+        >>> handler = ModelLoadedHandler(
+        ...     handler_name="auth.validate_token",
+        ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+        ...     handler_class="myapp.handlers.TokenValidator",
+        ...     contract_path=Path("/app/handlers/auth/handler_contract.yaml"),
+        ...     capability_tags=["auth", "validation", "jwt"],
+        ...     loaded_at=datetime.now(UTC),
+        ...     handler_version=ModelSemVer(major=1, minor=0, patch=0),
+        ... )
+        >>> handler.handler_name
+        'auth.validate_token'
+
+    See Also:
+        - :class:`ModelHandlerDescriptor`: Contract-level handler metadata.
+        - :class:`EnumHandlerTypeCategory`: Handler behavioral classification.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    handler_name: str = Field(
+        ...,
+        min_length=1,
+        description="Unique identifier for the handler",
+    )
+    protocol_type: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Protocol type identifier for registry lookup (e.g., 'db', 'http'). "
+            "Used as the key for handler registry registration."
+        ),
+    )
+    handler_type: EnumHandlerTypeCategory = Field(
+        ...,
+        description="Behavioral classification (COMPUTE, EFFECT, NONDETERMINISTIC_COMPUTE)",
+    )
+    handler_class: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified handler class name (e.g., 'myapp.handlers.AuthHandler')",
+    )
+    contract_path: Path = Field(
+        ...,
+        description="Absolute path to the source contract YAML file",
+    )
+    capability_tags: list[str] = Field(
+        default_factory=list,
+        description="Tags for handler discovery and filtering",
+    )
+    loaded_at: datetime = Field(
+        ...,
+        description="Timestamp when the handler was successfully loaded",
+    )
+    handler_version: ModelSemVer = Field(
+        ...,
+        description="Handler semantic version from contract",
+    )
+
+
+__all__ = ["ModelLoadedHandler"]

omnibase_infra/models/runtime/model_plugin_load_context.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Plugin Load Context Model for Summary Logging.
+
+This module provides ModelPluginLoadContext which groups the parameters needed
+for logging a plugin load summary.
+
+See Also:
+    - PluginLoader: Uses this model to pass context to _log_load_summary
+    - ModelPluginLoadSummary: The summary model created from this context
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader observability logging.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.runtime.model_failed_plugin_load import (
+    ModelFailedPluginLoad,
+)
+from omnibase_infra.models.runtime.model_loaded_handler import ModelLoadedHandler
+
+
+class ModelPluginLoadContext(BaseModel):
+    """Context for logging a plugin load summary.
+
+    Groups related parameters needed to create a load summary, reducing
+    the number of function parameters.
+
+    Attributes:
+        operation: The type of load operation (e.g., 'load_from_directory').
+        source: The source path or patterns used for discovery.
+        total_discovered: Total number of contract files discovered.
+        handlers: List of successfully loaded handlers.
+        failed_plugins: List of plugins that failed to load.
+        duration_seconds: Total operation time in seconds.
+        correlation_id: Correlation ID for distributed tracing (UUID for models).
+        original_correlation_id: Original correlation ID string for logging.
+            Preserves the exact string passed by the caller, even if it's not
+            a valid UUID format. Used in log extra fields for traceability.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Type of load operation performed",
+    )
+    source: str = Field(
+        ...,
+        description="Source path or patterns used for discovery",
+    )
+    total_discovered: int = Field(
+        ...,
+        ge=0,
+        description="Total number of contract files discovered",
+    )
+    handlers: list[ModelLoadedHandler] = Field(
+        default_factory=list,
+        description="List of successfully loaded handlers",
+    )
+    failed_plugins: list[ModelFailedPluginLoad] = Field(
+        default_factory=list,
+        description="List of plugins that failed to load",
+    )
+    duration_seconds: float = Field(
+        ...,
+        ge=0.0,
+        description="Total operation time in seconds",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing (UUID for models)",
+    )
+    # NOTE: This field intentionally uses str (not UUID) to preserve the exact
+    # caller-provided value for logging. The caller may provide a non-UUID format
+    # correlation ID (e.g., 'test-correlation-12345' or OpenTelemetry trace IDs).
+    # The UUID-typed 'correlation_id' field is used for model validation.
+    caller_correlation_string: str = Field(
+        ...,
+        min_length=1,
+        description="Original correlation string from caller for logging (may be non-UUID)",
+    )
+
+
+__all__ = ["ModelPluginLoadContext"]

omnibase_infra/models/runtime/model_plugin_load_summary.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Plugin Load Summary Model for Observability Logging.
+
+This module provides ModelPluginLoadSummary which tracks the results of batch
+plugin loading operations for observability purposes.
+
+The summary captures:
+- Total plugins discovered and loaded
+- Details of any failed loads
+- Load duration for performance monitoring
+- Correlation ID for distributed tracing
+
+See Also:
+    - PluginLoader: Uses this model for summary logging
+    - ModelLoadedHandler: Individual plugin metadata
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader observability logging.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.runtime.model_failed_plugin_load import (
+    ModelFailedPluginLoad,
+)
+
+
+class ModelPluginLoadSummary(BaseModel):
+    """Summary of a batch plugin loading operation.
+
+    Captures comprehensive metrics about a batch loading operation for
+    observability, debugging, and performance monitoring.
+
+    Attributes:
+        operation: The type of load operation (e.g., 'load_from_directory',
+            'discover_and_load').
+        source: The source path or patterns used for discovery.
+        total_discovered: Total number of contract files discovered.
+        total_loaded: Number of plugins successfully loaded.
+        total_failed: Number of plugins that failed to load.
+        loaded_plugins: List of successfully loaded plugin details (name, class, module).
+        failed_plugins: List of failed plugin details with error information.
+        duration_seconds: Total time taken for the operation in seconds.
+        correlation_id: Correlation ID for distributed tracing.
+        completed_at: Timestamp when the operation completed.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> summary = ModelPluginLoadSummary(
+        ...     operation="load_from_directory",
+        ...     source="/app/plugins",
+        ...     total_discovered=5,
+        ...     total_loaded=4,
+        ...     total_failed=1,
+        ...     loaded_plugins=[
+        ...         {"name": "auth.plugin", "class": "AuthPlugin", "module": "app.plugins.auth"},
+        ...     ],
+        ...     failed_plugins=[ModelFailedPluginLoad(...)],
+        ...     duration_seconds=0.23,
+        ...     correlation_id=uuid4(),
+        ...     completed_at=datetime.now(UTC),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Type of load operation performed",
+    )
+    source: str = Field(
+        ...,
+        description="Source path or patterns used for discovery",
+    )
+    total_discovered: int = Field(
+        ...,
+        ge=0,
+        description="Total number of contract files discovered",
+    )
+    total_loaded: int = Field(
+        ...,
+        ge=0,
+        description="Number of plugins successfully loaded",
+    )
+    total_failed: int = Field(
+        ...,
+        ge=0,
+        description="Number of plugins that failed to load",
+    )
+    loaded_plugins: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="List of loaded plugin details (name, class, module)",
+    )
+    failed_plugins: list[ModelFailedPluginLoad] = Field(
+        default_factory=list,
+        description="List of failed plugin details with error information",
+    )
+    duration_seconds: float = Field(
+        ...,
+        ge=0.0,
+        description="Total operation time in seconds",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    completed_at: datetime = Field(
+        ...,
+        description="Timestamp when the operation completed",
+    )
+
+
+__all__ = ["ModelPluginLoadSummary"]

omnibase_infra/models/security/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security models for handler policy validation.
+
+This module exports security-related models for the two-layer handler
+security validation system (OMN-1098). These models define:
+
+1. Handler-declared security policies (what a handler needs)
+2. Environment-level constraints (what an environment permits)
+3. Validation results with errors and warnings (OMN-1137)
+
+The security validation system uses these models to:
+- Validate handler security requirements at registration time
+- Enforce security constraints at invocation time
+- Provide structured error reporting for violations
+
+See Also:
+    - EnumSecurityRuleId: Security validation rule identifiers
+    - docs/design/HANDLER_SECURITY_VALIDATION.md: Full design documentation
+"""
+
+from omnibase_infra.models.security.classification_levels import (
+    CLASSIFICATION_SECURITY_LEVELS,
+    get_security_level,
+)
+from omnibase_infra.models.security.model_environment_policy import (
+    ModelEnvironmentPolicy,
+)
+from omnibase_infra.models.security.model_handler_security_policy import (
+    ModelHandlerSecurityPolicy,
+)
+from omnibase_infra.models.security.model_security_error import (
+    ModelSecurityError,
+)
+from omnibase_infra.models.security.model_security_validation_result import (
+    ModelSecurityValidationResult,
+)
+from omnibase_infra.models.security.model_security_warning import (
+    ModelSecurityWarning,
+)
+
+__all__ = [
+    "CLASSIFICATION_SECURITY_LEVELS",
+    "ModelEnvironmentPolicy",
+    "ModelHandlerSecurityPolicy",
+    "ModelSecurityError",
+    "ModelSecurityValidationResult",
+    "ModelSecurityWarning",
+    "get_security_level",
+]