omnibase_infra 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

omnibase_infra/models/handlers/model_handler_source_config.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Source Configuration Model.
+
+This module provides ModelHandlerSourceConfig, a Pydantic model for
+configuring handler source mode selection at runtime.
+
+The configuration controls how handlers are discovered and loaded:
+    - BOOTSTRAP: Hardcoded handlers from _KNOWN_HANDLERS dict (MVP mode)
+    - CONTRACT: YAML contracts from handler_contract.yaml files (production)
+    - HYBRID: Contract-first with bootstrap fallback per-handler identity
+
+Production hardening features:
+    - Bootstrap expiry enforcement: If bootstrap_expires_at is set and now > expires_at,
+      the runtime will refuse to start in BOOTSTRAP mode (or force CONTRACT mode)
+    - Structured logging of expiry status at startup
+    - Override control for hybrid mode handler resolution
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1095 handler source mode configuration.
+
+See Also:
+    - HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md: Full architecture documentation
+    - EnumHandlerSourceMode: Enum defining valid source modes
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timezone
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums.enum_handler_source_mode import EnumHandlerSourceMode
+
+
+class ModelHandlerSourceConfig(BaseModel):
+    """Configuration for handler source mode selection.
+
+    Controls how handlers are discovered and loaded at runtime. This model
+    is used by RuntimeHostProcess and related components to determine the
+    handler loading strategy.
+
+    Configuration Options:
+        - handler_source_mode: Selects the loading strategy (BOOTSTRAP, CONTRACT, HYBRID)
+        - allow_bootstrap_override: Controls handler resolution in HYBRID mode
+        - bootstrap_expires_at: Production safety - forces CONTRACT after expiry
+
+    Production Hardening:
+        When bootstrap_expires_at is set and the current time exceeds it:
+        - BOOTSTRAP mode: Runtime refuses to start (safety mechanism)
+        - HYBRID mode: Bootstrap fallback disabled, contract-only resolution
+        - CONTRACT mode: No effect (already contract-only)
+
+        This prevents accidental deployment with hardcoded handlers in production.
+
+    Attributes:
+        handler_source_mode: Handler loading source mode.
+            - BOOTSTRAP: Load from hardcoded _KNOWN_HANDLERS dict (MVP)
+            - CONTRACT: Load from handler_contract.yaml files (production)
+            - HYBRID: Contract-first with bootstrap fallback per-handler identity
+            Defaults to HYBRID as recommended for gradual migration.
+
+        allow_bootstrap_override: If True, bootstrap handlers can override
+            contract handlers in HYBRID mode. Default is False, meaning
+            contract handlers take precedence (inverse of naive HYBRID).
+            Has no effect in BOOTSTRAP or CONTRACT modes.
+            When parsing from environment or config, string values "true",
+            "yes", "1", "on" (case-insensitive) are accepted as truthy.
+
+        bootstrap_expires_at: If set and expired, refuse BOOTSTRAP mode and
+            force CONTRACT. This is a production safety mechanism to ensure
+            hardcoded handlers are not accidentally deployed to production
+            after a migration deadline. Set to None to disable expiry checking.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> from omnibase_infra.models.handlers import ModelHandlerSourceConfig
+        >>> from omnibase_infra.enums import EnumHandlerSourceMode
+        >>>
+        >>> # Production configuration (recommended)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.CONTRACT,
+        ... )
+        >>>
+        >>> # Migration configuration with safety expiry (must be timezone-aware)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.HYBRID,
+        ...     bootstrap_expires_at=datetime(2025, 3, 1, 0, 0, 0, tzinfo=timezone.utc),
+        ... )
+        >>>
+        >>> # Check if bootstrap is expired
+        >>> if config.is_bootstrap_expired:
+        ...     print("Bootstrap mode has expired - must use CONTRACT")
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+    )
+
+    handler_source_mode: EnumHandlerSourceMode = Field(
+        default=EnumHandlerSourceMode.HYBRID,
+        description="Handler loading source mode: BOOTSTRAP, CONTRACT, or HYBRID. "
+        "Defaults to HYBRID (contract-first with bootstrap fallback).",
+    )
+
+    allow_bootstrap_override: bool = Field(
+        default=False,
+        description=(
+            "If True, bootstrap handlers can override contract handlers in HYBRID mode. "
+            "Default is False (contract handlers take precedence). "
+            "When parsing from config, string values 'true', 'yes', '1', 'on' "
+            "(case-insensitive) are accepted as truthy."
+        ),
+    )
+
+    bootstrap_expires_at: datetime | None = Field(
+        default=None,
+        description=(
+            "If set and expired, refuse BOOTSTRAP mode and force CONTRACT. "
+            "Production safety mechanism for migration deadlines. "
+            "Must be timezone-aware (UTC recommended); naive datetimes are rejected."
+        ),
+    )
+
+    @field_validator("allow_bootstrap_override", mode="before")
+    @classmethod
+    def _coerce_allow_bootstrap_override(cls, value: object) -> bool:
+        """Coerce string and numeric values to boolean for config file compatibility.
+
+        Environment variables and YAML/JSON config files often represent booleans
+        as strings. This validator handles common truthy string representations
+        before Pydantic's strict type validation.
+
+        Args:
+            value: The raw value to coerce (may be str, bool, int, float, None, or other).
+
+        Returns:
+            True if value is a truthy string ("true", "yes", "1", "on") or
+            a truthy boolean, False otherwise.
+
+        Type Handling:
+            - bool: Passed through unchanged.
+            - str: Case-insensitive check for "true", "yes", "1", "on".
+            - int/float: 0 and 0.0 are False, all other numbers are True.
+            - None: Returns False.
+            - Unknown types: Default to False for safety.
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.lower() in ("true", "yes", "1", "on")
+        if isinstance(value, (int, float)):
+            # Explicit: 0/0.0 = False, any other number = True
+            return bool(value)
+        # Unknown types default to False for safety
+        return False
+
+    @field_validator("bootstrap_expires_at")
+    @classmethod
+    def _validate_expires_at_timezone(cls, value: datetime | None) -> datetime | None:
+        """Validate and normalize bootstrap_expires_at to UTC.
+
+        Args:
+            value: The datetime value to validate.
+
+        Returns:
+            None if value is None, otherwise the datetime normalized to UTC.
+
+        Raises:
+            ValueError: If the datetime is naive (no timezone info).
+        """
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError(
+                "bootstrap_expires_at must be timezone-aware (UTC recommended). "
+                "Use datetime.now(timezone.utc) or datetime(..., tzinfo=timezone.utc)."
+            )
+        return value.astimezone(UTC)
+
+    @property
+    def is_bootstrap_expired(self) -> bool:
+        """Check if bootstrap mode has expired.
+
+        Returns:
+            True if bootstrap_expires_at is set and current time exceeds it,
+            False otherwise.
+
+        Note:
+            Uses UTC-aware comparison. The bootstrap_expires_at field is
+            validated and normalized to UTC at construction time.
+        """
+        if self.bootstrap_expires_at is None:
+            return False
+        return datetime.now(UTC) > self.bootstrap_expires_at
+
+    @property
+    def effective_mode(self) -> EnumHandlerSourceMode:
+        """Get the effective handler source mode after expiry check.
+
+        If bootstrap_expires_at is set and expired, returns CONTRACT
+        regardless of the configured handler_source_mode. Otherwise
+        returns the configured mode.
+
+        Returns:
+            The effective handler source mode to use at runtime.
+
+        Note:
+            This property should be used by runtime components instead of
+            directly accessing handler_source_mode to ensure expiry
+            enforcement is applied.
+        """
+        if self.is_bootstrap_expired:
+            return EnumHandlerSourceMode.CONTRACT
+        return self.handler_source_mode
+
+
+__all__ = ["ModelHandlerSourceConfig"]

omnibase_infra/models/mcp/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP models for Model Context Protocol integration."""
+
+from omnibase_infra.models.mcp.model_mcp_contract_config import ModelMCPContractConfig
+from omnibase_infra.models.mcp.model_mcp_server_config import ModelMCPServerConfig
+from omnibase_infra.models.mcp.model_mcp_tool_definition import ModelMCPToolDefinition
+from omnibase_infra.models.mcp.model_mcp_tool_parameter import ModelMCPToolParameter
+
+__all__ = [
+    "ModelMCPContractConfig",
+    "ModelMCPServerConfig",
+    "ModelMCPToolDefinition",
+    "ModelMCPToolParameter",
+]

omnibase_infra/models/mcp/model_mcp_contract_config.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP contract configuration model for enabling nodes as MCP tools.
+
+This model defines the `mcp` field that can be added to ONEX contracts to expose
+orchestrator nodes as MCP tools for AI agent integration.
+
+Example contract.yaml:
+    node_type: ORCHESTRATOR_GENERIC
+    mcp:
+      expose: true
+      tool_name: "workflow_execute"
+      description: "Execute a workflow"
+      timeout_seconds: 30
+
+Enforcement Rule:
+    The `mcp.expose` field is ONLY valid for ORCHESTRATOR_GENERIC nodes.
+    Non-orchestrator nodes with `mcp.expose: true` will be ignored during
+    registration - the MCP tags will not be added to Consul.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPContractConfig(BaseModel):
+    """MCP configuration for exposing a node as an MCP tool.
+
+    This configuration is embedded in a node's contract.yaml to enable
+    AI agents to discover and invoke the node as an MCP tool.
+
+    Attributes:
+        expose: Whether to expose this node as an MCP tool. When True and
+            the node is an orchestrator, it will be registered with Consul
+            using MCP-specific tags for tool discovery.
+        tool_name: Optional stable name for the MCP tool. If not provided,
+            defaults to the node's name. Use this to provide a consistent
+            tool name across node version changes.
+        description: Optional AI-friendly description of what this tool does.
+            If not provided, the node's description from the contract is used.
+        timeout_seconds: Optional execution timeout in seconds. Defaults to 30.
+            This is enforced when AI agents invoke the tool.
+
+    Example:
+        >>> config = ModelMCPContractConfig(
+        ...     expose=True,
+        ...     tool_name="my_workflow",
+        ...     description="Execute my custom workflow",
+        ...     timeout_seconds=60,
+        ... )
+        >>> config.expose
+        True
+    """
+
+    expose: bool = Field(
+        default=False,
+        description="Whether to expose this node as an MCP tool. "
+        "Only valid for ORCHESTRATOR_GENERIC nodes.",
+    )
+    tool_name: str | None = Field(
+        default=None,
+        description="Optional stable name for the MCP tool. "
+        "Defaults to the node's name if not specified.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional AI-friendly description of what this tool does. "
+        "If not provided, the node's description from the contract is used.",
+    )
+    timeout_seconds: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Execution timeout in seconds for tool invocations. "
+        "Minimum: 1, Maximum: 300 (5 minutes).",
+    )
+
+
+__all__ = ["ModelMCPContractConfig"]

omnibase_infra/models/mcp/model_mcp_server_config.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP server configuration model.
+
+This model defines the configuration for the MCP server lifecycle,
+including Consul discovery, Kafka hot reload, and HTTP server settings.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPServerConfig(BaseModel):
+    """Configuration for the MCP server lifecycle.
+
+    This model captures all configuration needed for the MCP server:
+    - Consul connection settings for service discovery
+    - Kafka settings for hot reload
+    - HTTP server binding
+    - Execution defaults
+
+    Attributes:
+        consul_host: Consul server hostname for service discovery.
+        consul_port: Consul server port.
+        consul_scheme: HTTP scheme for Consul (http/https).
+        consul_token: Optional ACL token for Consul authentication.
+        kafka_enabled: Whether to enable Kafka for hot reload.
+        http_host: Host to bind the MCP HTTP server.
+        http_port: Port for the MCP HTTP server.
+        default_timeout: Default execution timeout for tools.
+        dev_mode: Whether to run in development mode (local contracts).
+        contracts_dir: Directory for contract scanning in dev mode.
+    """
+
+    consul_host: str = Field(default="localhost", description="Consul server hostname")
+    consul_port: int = Field(
+        default=8500, ge=1, le=65535, description="Consul server port"
+    )
+    consul_scheme: str = Field(
+        default="http", pattern="^https?$", description="HTTP scheme for Consul"
+    )
+    consul_token: str | None = Field(
+        default=None, description="Optional ACL token for Consul authentication"
+    )
+    kafka_enabled: bool = Field(
+        default=True, description="Whether to enable Kafka for hot reload"
+    )
+    http_host: str = Field(
+        default="0.0.0.0",  # noqa: S104 - Intentional bind-all for server
+        description="Host to bind the MCP HTTP server",
+    )
+    http_port: int = Field(
+        default=8090, ge=1, le=65535, description="Port for the MCP HTTP server"
+    )
+    default_timeout: float = Field(
+        default=30.0, gt=0, le=300, description="Default execution timeout for tools"
+    )
+    dev_mode: bool = Field(
+        default=False, description="Whether to run in development mode"
+    )
+    contracts_dir: str | None = Field(
+        default=None, description="Directory for contract scanning in dev mode"
+    )
+
+
+__all__ = ["ModelMCPServerConfig"]

omnibase_infra/models/mcp/model_mcp_tool_definition.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool definition model for representing ONEX nodes as MCP tools.
+
+This model is used by the MCP adapter layer to:
+1. Cache discovered tools in the registry
+2. Generate MCP tool schemas for AI agents
+3. Route tool invocations to ONEX orchestrators
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from omnibase_infra.models.mcp.model_mcp_tool_parameter import ModelMCPToolParameter
+
+
+class ModelMCPToolDefinition(BaseModel):
+    """Complete MCP tool definition derived from an ONEX orchestrator node.
+
+    This model captures all information needed to:
+    - Expose the tool to AI agents via MCP protocol
+    - Route invocations to the correct ONEX orchestrator
+    - Enforce execution constraints (timeout, etc.)
+
+    Attributes:
+        name: Stable tool name for AI agent invocation. This is derived from
+            contract.mcp.tool_name or falls back to the node name.
+        description: AI-friendly description of tool functionality.
+        version: Tool version from the node contract.
+        parameters: List of input parameters with type information.
+        input_schema: JSON Schema for input validation.
+        orchestrator_node_id: UUID of the ONEX orchestrator node.
+        orchestrator_service_id: Consul service ID for routing.
+        endpoint: HTTP endpoint for direct invocation (if available).
+        timeout_seconds: Execution timeout for tool invocations.
+        metadata: Additional metadata for routing and observability.
+    """
+
+    name: str = Field(description="Stable tool name for MCP invocation")
+    description: str = Field(description="AI-friendly tool description")
+    version: str = Field(default="1.0.0", description="Tool version")
+    parameters: list[ModelMCPToolParameter] = Field(
+        default_factory=list, description="Input parameters"
+    )
+    input_schema: dict[str, object] = Field(
+        default_factory=lambda: dict[str, object]({"type": "object", "properties": {}}),
+        description="JSON Schema for input validation",
+    )
+    orchestrator_node_id: str | None = Field(
+        default=None, description="UUID of the source orchestrator node"
+    )
+    orchestrator_service_id: str | None = Field(
+        default=None, description="Consul service ID for routing"
+    )
+    endpoint: str | None = Field(
+        default=None, description="HTTP endpoint for direct invocation"
+    )
+    timeout_seconds: int = Field(
+        default=30, ge=1, le=300, description="Execution timeout in seconds"
+    )
+    metadata: dict[str, object] = Field(
+        default_factory=dict,
+        description="Additional metadata (tags, input_model module, etc.)",
+    )
+
+    @property
+    def tool_type(self) -> str:
+        """Return the MCP tool type. Always 'function' for ONEX nodes."""
+        return "function"
+
+
+__all__ = ["ModelMCPToolDefinition"]

omnibase_infra/models/mcp/model_mcp_tool_parameter.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool parameter model for representing tool input parameters."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPToolParameter(BaseModel):
+    """Parameter definition for an MCP tool.
+
+    Represents a single parameter that can be passed to an MCP tool,
+    including its type, validation constraints, and documentation.
+    """
+
+    name: str = Field(description="Parameter name")
+    parameter_type: str = Field(
+        default="string",
+        description="JSON Schema type: string, number, boolean, array, object",
+    )
+    description: str = Field(default="", description="Human-readable description")
+    required: bool = Field(
+        default=True, description="Whether this parameter is required"
+    )
+    default_value: object | None = Field(
+        default=None, description="Default value if not provided"
+    )
+    json_schema: dict[str, object] | None = Field(
+        default=None,
+        description="Additional JSON Schema constraints (enum, format, etc.)",
+    )
+
+
+__all__ = ["ModelMCPToolParameter"]

omnibase_infra/models/registration/model_node_capabilities.py

@@ -12,9 +12,12 @@ Note:
     would not correctly handle this distinction.
 """
 
+from __future__ import annotations
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from omnibase_core.types import JsonType
+from omnibase_infra.models.mcp.model_mcp_contract_config import ModelMCPContractConfig
 
 
 class ModelNodeCapabilities(BaseModel):
@@ -94,6 +97,14 @@ class ModelNodeCapabilities(BaseModel):
         description="Nested configuration (JSON-serializable values)",
     )
 
+    # MCP configuration for exposing node as AI agent tool
+    # Only valid for ORCHESTRATOR nodes - ignored for other node types
+    mcp: ModelMCPContractConfig | None = Field(
+        default=None,
+        description="MCP configuration for exposing node as AI agent tool. "
+        "Only valid for ORCHESTRATOR_GENERIC nodes.",
+    )
+
     def __getitem__(self, key: str) -> object:
         """Enable dict-like access to capabilities.
 

omnibase_infra/models/registration/model_node_introspection_event.py

@@ -14,6 +14,7 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.capabilities import ModelContractCapabilities
 from omnibase_core.models.primitives.model_semver import ModelSemVer
 from omnibase_infra.enums import EnumIntrospectionReason
 from omnibase_infra.models.discovery.model_discovered_capabilities import (
@@ -49,6 +50,8 @@ class ModelNodeIntrospectionEvent(BaseModel):
         node_version: Semantic version of the node.
         declared_capabilities: Contract-declared capabilities (feature flags).
         discovered_capabilities: Runtime-discovered capabilities (reflection).
+        contract_capabilities: Contract-derived capabilities (design-time truth).
+            Populated from the node's contract when available, None otherwise.
         endpoints: Dictionary of exposed endpoints (name -> URL).
         current_state: Current FSM state if the node has state management.
         reason: Why this introspection event was emitted.
@@ -98,6 +101,12 @@ class ModelNodeIntrospectionEvent(BaseModel):
         default_factory=ModelDiscoveredCapabilities,
         description="Capabilities discovered via runtime reflection",
     )
+    contract_capabilities: ModelContractCapabilities | None = Field(
+        default=None,
+        description="Contract-derived capabilities (design-time truth, deterministic). "
+        "Populated by ContractCapabilityExtractor from the node's contract. "
+        "None when contract is not available or extraction fails.",
+    )
 
     # Endpoints and state
     endpoints: dict[str, str] = Field(

omnibase_infra/models/runtime/model_handler_contract.py

@@ -27,6 +27,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 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 (
@@ -131,6 +132,10 @@ class ModelHandlerContract(BaseModel):
         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
@@ -207,18 +212,22 @@ class ModelHandlerContract(BaseModel):
         return []
 
     @model_validator(mode="after")
-    def set_default_protocol_type(self) -> ModelHandlerContract:
-        """Set protocol_type from handler_name if not explicitly provided.
+    def set_defaults(self) -> ModelHandlerContract:
+        """Set default values for protocol_type and handler_version.
 
-        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.
+        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.
+            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 populated.
+            Self with protocol_type and handler_version populated.
 
         Raises:
             ValueError: If derived protocol_type would be empty (e.g., handler_name
@@ -232,6 +241,8 @@ class ModelHandlerContract(BaseModel):
             ... )
             >>> contract.protocol_type
             'db'
+            >>> contract.handler_version
+            ModelSemVer(major=1, minor=0, patch=0)
 
             >>> contract = ModelHandlerContract(
             ...     handler_name="custom-handler",
@@ -241,6 +252,10 @@ class ModelHandlerContract(BaseModel):
             >>> 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):
@@ -263,7 +278,7 @@ class ModelHandlerContract(BaseModel):
                 f"Provide a non-empty protocol_type or handler_name."
             )
 
-        # Log successful protocol_type derivation for debugging
+        # Log successful contract validation for debugging
         logger.debug(
             "Handler contract validated successfully",
             extra={
@@ -271,6 +286,7 @@ class ModelHandlerContract(BaseModel):
                 "handler_class": self.handler_class,
                 "protocol_type": self.protocol_type,
                 "handler_type": self.handler_type.value,
+                "handler_version": str(self.handler_version),
             },
         )
 

omnibase_infra/models/runtime/model_loaded_handler.py

@@ -24,6 +24,7 @@ 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
 
 
@@ -53,10 +54,13 @@ class ModelLoadedHandler(BaseModel):
             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",
@@ -65,6 +69,7 @@ class ModelLoadedHandler(BaseModel):
         ...     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'
@@ -115,6 +120,10 @@ class ModelLoadedHandler(BaseModel):
         ...,
         description="Timestamp when the handler was successfully loaded",
     )
+    handler_version: ModelSemVer = Field(
+        ...,
+        description="Handler semantic version from contract",
+    )
 
 
 __all__ = ["ModelLoadedHandler"]