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

omnibase_infra/handlers/handler_intent.py

@@ -0,0 +1,387 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Intent Handler - Temporary demo wiring for intent graph operations.
+
+Wraps HandlerGraph to provide intent-specific graph operations for the demo.
+This is temporary hardcoded routing that will be replaced by contract-driven
+handler routing in production.
+
+Supported Operations:
+    - intent.store: Store an intent as a graph node with label "Intent"
+    - intent.query_session: Query intents by session_id property
+    - intent.query_distribution: Get intent count/statistics
+
+Note:
+    This is TEMPORARY demo wiring. Keep it simple and focused on the demo use case.
+    Production implementation should use contract-driven handler routing.
+"""
+
+# TODO(OMN-1515): Remove demo wiring after intent routing is contract-driven
+
+from __future__ import annotations
+
+import logging
+from uuid import UUID, uuid4
+
+from omnibase_core.container import ModelONEXContainer
+from omnibase_core.types import JsonType
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import (
+    ModelInfraErrorContext,
+    RuntimeHostError,
+)
+from omnibase_infra.handlers.handler_graph import HandlerGraph
+from omnibase_infra.mixins import MixinEnvelopeExtraction
+
+logger = logging.getLogger(__name__)
+
+HANDLER_ID_INTENT: str = "intent-handler"
+_SUPPORTED_OPERATIONS: frozenset[str] = frozenset(
+    {
+        "intent.store",
+        "intent.query_session",
+        "intent.query_distribution",
+    }
+)
+
+
+class HandlerIntent(MixinEnvelopeExtraction):  # DEMO ONLY
+    """Intent handler wrapping HandlerGraph for intent-specific operations.
+
+    This handler provides a simplified interface for storing and querying
+    intents in the graph database. It wraps HandlerGraph and translates
+    intent-specific operations to graph operations.
+
+    Note:
+        This is temporary demo wiring. The handler assumes HandlerGraph
+        is already initialized and passed via config during initialize().
+
+    Idempotency:
+        - intent.store: NOT idempotent (creates new node each call)
+        - intent.query_session: Idempotent (read-only query)
+        - intent.query_distribution: Idempotent (read-only aggregation)
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize HandlerIntent with ONEX container for dependency injection.
+
+        Args:
+            container: ONEX container for dependency injection.
+        """
+        self._container = container
+        self._graph_handler: HandlerGraph | None = None
+        self._initialized: bool = False
+
+    async def initialize(self, config: dict[str, object]) -> None:
+        """Initialize the intent handler.
+
+        Args:
+            config: Configuration dict containing:
+                - graph_handler: Pre-initialized HandlerGraph instance (required)
+
+        Raises:
+            RuntimeHostError: If graph_handler is missing or invalid.
+        """
+        init_correlation_id = uuid4()
+
+        logger.info(
+            "Initializing %s",
+            self.__class__.__name__,
+            extra={
+                "handler": self.__class__.__name__,
+                "correlation_id": str(init_correlation_id),
+            },
+        )
+
+        graph_handler = config.get("graph_handler")
+        if not isinstance(graph_handler, HandlerGraph):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="initialize",
+                target_name="intent_handler",
+                correlation_id=init_correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'graph_handler' in config - "
+                "must be an initialized HandlerGraph instance",
+                context=ctx,
+            )
+
+        self._graph_handler = graph_handler
+        self._initialized = True
+
+        logger.info(
+            "%s initialized successfully",
+            self.__class__.__name__,
+            extra={
+                "handler": self.__class__.__name__,
+                "correlation_id": str(init_correlation_id),
+            },
+        )
+
+    async def shutdown(self) -> None:
+        """Shutdown the intent handler.
+
+        Note:
+            This handler does not own the graph handler, so we do not
+            shut it down here. The caller is responsible for managing
+            the graph handler lifecycle.
+        """
+        self._graph_handler = None
+        self._initialized = False
+        logger.info("HandlerIntent shutdown complete")
+
+    async def execute(self, envelope: dict[str, object]) -> dict[str, object]:
+        """Execute intent operation from envelope.
+
+        Args:
+            envelope: Request envelope containing:
+                - operation: Intent operation (intent.store, intent.query_session, etc.)
+                - payload: dict with operation-specific parameters
+                - correlation_id: Optional correlation ID for tracing
+                - envelope_id: Optional envelope ID for causality tracking
+
+        Returns:
+            dict containing operation result with:
+                - success: bool indicating operation success
+                - data: Operation-specific result data
+                - correlation_id: UUID string for tracing
+
+        Raises:
+            RuntimeHostError: If handler not initialized or invalid input.
+        """
+        correlation_id = self._extract_correlation_id(envelope)
+
+        if not self._initialized or self._graph_handler is None:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="execute",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "HandlerIntent not initialized. Call initialize() first.",
+                context=ctx,
+            )
+
+        operation = envelope.get("operation")
+        if not isinstance(operation, str):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="execute",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'operation' in envelope",
+                context=ctx,
+            )
+
+        if operation not in _SUPPORTED_OPERATIONS:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation=operation,
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                f"Operation '{operation}' not supported. "
+                f"Available: {', '.join(sorted(_SUPPORTED_OPERATIONS))}",
+                context=ctx,
+            )
+
+        payload = envelope.get("payload")
+        if not isinstance(payload, dict):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation=operation,
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'payload' in envelope",
+                context=ctx,
+            )
+
+        # Route to appropriate handler method
+        if operation == "intent.store":
+            return await self._store_intent(payload, correlation_id)
+        elif operation == "intent.query_session":
+            return await self._query_session(payload, correlation_id)
+        else:  # intent.query_distribution
+            return await self._query_distribution(correlation_id)
+
+    async def _store_intent(
+        self, payload: dict[str, object], correlation_id: UUID
+    ) -> dict[str, object]:
+        """Store an intent as a graph node.
+
+        Args:
+            payload: Intent data to store. Should contain:
+                - intent_type: Type of intent (required)
+                - session_id: Session identifier (optional)
+                - Additional properties as needed
+
+        Returns:
+            dict with created node details.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        # Extract intent properties - use JsonType for graph compatibility
+        properties: dict[str, JsonType] = {
+            "correlation_id": str(correlation_id),
+        }
+
+        # Copy all payload properties to node properties
+        for key, value in payload.items():
+            # Convert non-primitive types to strings for graph storage
+            # NOTE: Using tuple form for isinstance to avoid union validator flag
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                properties[key] = value
+            else:
+                properties[key] = str(value)
+
+        # Create the intent node
+        node = await self._graph_handler.create_node(
+            labels=["Intent"],
+            properties=properties,
+        )
+
+        return {
+            "success": True,
+            "data": {
+                "node_id": node.id,
+                "element_id": node.element_id,
+                "labels": node.labels,
+                "properties": node.properties,
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    async def _query_session(
+        self, payload: dict[str, object], correlation_id: UUID
+    ) -> dict[str, object]:
+        """Query intents by session_id.
+
+        Args:
+            payload: Query parameters. Should contain:
+                - session_id: Session identifier to filter by (required)
+
+        Returns:
+            dict with matching intent nodes.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        session_id = payload.get("session_id")
+        if not session_id:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="intent.query_session",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing 'session_id' in payload",
+                context=ctx,
+            )
+
+        # Query intents by session_id
+        # SECURITY: Using parameterized query ($session_id) to prevent Cypher injection
+        query = """
+        MATCH (i:Intent {session_id: $session_id})
+        RETURN i, elementId(i) as eid, id(i) as nid
+        ORDER BY i.created_at DESC
+        """
+
+        result = await self._graph_handler.execute_query(
+            query=query,
+            parameters={"session_id": str(session_id)},
+        )
+
+        # Transform records to intent data
+        intents = []
+        for record in result.records:
+            node = record.get("i")
+            if node:
+                intents.append(
+                    {
+                        "node_id": str(record.get("nid", "")),
+                        "element_id": str(record.get("eid", "")),
+                        "properties": dict(node) if isinstance(node, dict) else {},
+                    }
+                )
+
+        return {
+            "success": True,
+            "data": {
+                "session_id": str(session_id),
+                "intents": intents,
+                "count": len(intents),
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    async def _query_distribution(self, correlation_id: UUID) -> dict[str, object]:
+        """Query intent distribution/statistics.
+
+        Returns:
+            dict with intent statistics including counts by intent_type.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        # Query total count
+        count_query = "MATCH (i:Intent) RETURN count(i) as total"
+        count_result = await self._graph_handler.execute_query(query=count_query)
+
+        total_count = 0
+        if count_result.records:
+            raw_total = count_result.records[0].get("total", 0)
+            total_count = int(raw_total) if isinstance(raw_total, int | float) else 0
+
+        # Query distribution by intent_type
+        distribution_query = """
+        MATCH (i:Intent)
+        RETURN i.intent_type as intent_type, count(i) as count
+        ORDER BY count DESC
+        """
+        distribution_result = await self._graph_handler.execute_query(
+            query=distribution_query
+        )
+
+        # Build distribution dict
+        distribution: dict[str, int] = {}
+        for record in distribution_result.records:
+            intent_type = record.get("intent_type")
+            raw_count = record.get("count", 0)
+            if intent_type:
+                count_val = int(raw_count) if isinstance(raw_count, int | float) else 0
+                distribution[str(intent_type)] = count_val
+
+        return {
+            "success": True,
+            "data": {
+                "total_count": total_count,
+                "distribution": distribution,
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    def describe(self) -> dict[str, object]:
+        """Return handler metadata and capabilities.
+
+        Returns:
+            dict containing handler information.
+        """
+        return {
+            "handler_id": HANDLER_ID_INTENT,
+            "handler_type": "intent_handler",
+            "supported_operations": sorted(_SUPPORTED_OPERATIONS),
+            "initialized": self._initialized,
+            "version": "0.1.0-demo",
+        }
+
+
+__all__: list[str] = ["HandlerIntent", "HANDLER_ID_INTENT"]

omnibase_infra/handlers/handler_mcp.py

@@ -569,7 +569,16 @@ class HandlerMCP(MixinEnvelopeExtraction, MixinAsyncCircuitBreaker):
                 # - Resource leaks from partial initialization
                 try:
                     # Create and start MCPServerLifecycle for tool discovery
-                    self._lifecycle = MCPServerLifecycle(config=server_config, bus=None)
+                    # Container is required for lifecycle initialization
+                    if self._container is None:
+                        raise ValueError(
+                            "Container required for MCPServerLifecycle initialization"
+                        )
+                    self._lifecycle = MCPServerLifecycle(
+                        container=self._container,
+                        config=server_config,
+                        bus=None,
+                    )
                     await self._lifecycle.start()
 
                     # Update MCP registry and executor references from lifecycle

omnibase_infra/handlers/handler_vault.py

@@ -27,6 +27,7 @@ from uuid import uuid4
 
 import hvac
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.models.dispatch import ModelHandlerOutput
 from omnibase_infra.enums import (
     EnumHandlerType,
@@ -122,13 +123,18 @@ class HandlerVault(
         - MixinVaultToken: Token management and renewal
     """
 
-    def __init__(self) -> None:
-        """Initialize HandlerVault in uninitialized state.
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize HandlerVault with ONEX container for dependency injection.
 
-        Note: Circuit breaker is initialized during initialize() call when
-        configuration is available. The mixin's _init_circuit_breaker() method
-        is called there with the actual config values.
+        Args:
+            container: ONEX container for dependency injection.
+
+        Note:
+            Circuit breaker is initialized during initialize() call when
+            configuration is available. The mixin's _init_circuit_breaker() method
+            is called there with the actual config values.
         """
+        self._container = container
         self._client: hvac.Client | None = None
         self._config: ModelVaultHandlerConfig | None = None
         self._initialized: bool = False

omnibase_infra/handlers/registration_storage/handler_registration_storage_postgres.py

@@ -48,6 +48,7 @@ from uuid import UUID, uuid4
 # Import asyncpg at module level to avoid redundant imports inside methods
 import asyncpg
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.enums.enum_node_kind import EnumNodeKind
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import (
@@ -152,7 +153,10 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
         handler_type: Returns "postgresql" identifier.
 
     Example:
+        >>> from omnibase_core.container import ModelONEXContainer
+        >>> container = ModelONEXContainer(...)
         >>> handler = HandlerRegistrationStoragePostgres(
+        ...     container=container,
         ...     postgres_adapter=postgres_adapter,
         ...     circuit_breaker_config={"threshold": 5, "reset_timeout": 30.0},
         ... )
@@ -161,6 +165,7 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         postgres_adapter: ProtocolPostgresAdapter | None = None,
         dsn: str | None = None,
         host: str = "localhost",
@@ -178,6 +183,7 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
         """Initialize HandlerRegistrationStoragePostgres.
 
         Args:
+            container: ONEX dependency injection container (required).
             postgres_adapter: Optional existing PostgreSQL adapter (ProtocolPostgresAdapter).
                 If not provided, a new asyncpg connection pool will be created.
             dsn: Optional PostgreSQL connection DSN (overrides host/port/etc).
@@ -197,6 +203,7 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
                 table on first connection. Default is False. Production deployments
                 should use database migrations instead of auto-creation.
         """
+        self._container = container
         # Normalize circuit breaker config to ModelCircuitBreakerConfig
         if isinstance(circuit_breaker_config, ModelCircuitBreakerConfig):
             cb_config = circuit_breaker_config

omnibase_infra/handlers/service_discovery/handler_service_discovery_consul.py

@@ -30,6 +30,7 @@ from uuid import NAMESPACE_DNS, UUID, uuid4, uuid5
 
 import consul
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import (
     InfraConnectionError,
@@ -91,7 +92,10 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
         handler_type: Returns "consul" identifier.
 
     Example:
+        >>> from unittest.mock import MagicMock
+        >>> container = MagicMock(spec=ModelONEXContainer)
         >>> handler = HandlerServiceDiscoveryConsul(
+        ...     container=container,
         ...     consul_client=consul_client,
         ...     circuit_breaker_config=ModelCircuitBreakerConfig(threshold=5),
         ... )
@@ -100,6 +104,7 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         consul_client: ProtocolConsulClient | None = None,
         consul_host: str = "localhost",
         consul_port: int = 8500,
@@ -114,6 +119,7 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
         """Initialize HandlerServiceDiscoveryConsul.
 
         Args:
+            container: ONEX container for dependency injection and service resolution.
             consul_client: Optional existing Consul client (ProtocolConsulClient).
                 If not provided, a new python-consul client will be created.
             consul_host: Consul server hostname (default: "localhost").
@@ -129,6 +135,7 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
             max_workers: Thread pool max workers (default: 10).
             timeout_seconds: Operation timeout in seconds (default: 30.0).
         """
+        self._container = container
         # Parse circuit breaker configuration using ModelCircuitBreakerConfig
         if isinstance(circuit_breaker_config, ModelCircuitBreakerConfig):
             cb_config = circuit_breaker_config

omnibase_infra/mixins/mixin_node_introspection.py

@@ -209,6 +209,7 @@ from uuid import UUID, uuid4
 from omnibase_core.enums import EnumNodeKind
 from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
 from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.capabilities import ContractCapabilityExtractor
 from omnibase_infra.enums import EnumInfraTransportType, EnumIntrospectionReason
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
 from omnibase_infra.models.discovery import (
@@ -228,6 +229,7 @@ from omnibase_infra.models.registration.model_node_introspection_event import (
 )
 
 if TYPE_CHECKING:
+    from omnibase_core.models.contracts import ModelContractBase
     from omnibase_core.protocols.event_bus.protocol_event_bus import ProtocolEventBus
     from omnibase_core.protocols.event_bus.protocol_event_message import (
         ProtocolEventMessage,
@@ -246,6 +248,9 @@ PERF_THRESHOLD_DISCOVER_CAPABILITIES_MS = 30.0
 PERF_THRESHOLD_GET_INTROSPECTION_DATA_MS = 50.0
 PERF_THRESHOLD_CACHE_HIT_MS = 1.0
 
+# Module-level capability extractor instance (stateless, can be shared)
+_CAPABILITY_EXTRACTOR = ContractCapabilityExtractor()
+
 
 class PerformanceMetricsCacheDict(TypedDict, total=False):
     """TypedDict for JSON-serialized ModelIntrospectionPerformanceMetrics.
@@ -458,6 +463,7 @@ class MixinNodeIntrospection:
     _introspection_event_bus: ProtocolEventBus | None
     _introspection_version: str
     _introspection_start_time: float | None
+    _introspection_contract: ModelContractBase | None
 
     # Capability discovery configuration
     _introspection_operation_keywords: frozenset[str]
@@ -650,6 +656,9 @@ class MixinNodeIntrospection:
         self._heartbeat_topic = config.heartbeat_topic
         self._request_introspection_topic = config.request_introspection_topic
 
+        # Contract for capability extraction (may be None for legacy nodes)
+        self._introspection_contract = config.contract
+
         # State
         self._introspection_cache = None
         self._introspection_cached_at = None
@@ -1338,6 +1347,14 @@ class MixinNodeIntrospection:
             # Fallback to 1.0.0 if version parsing fails
             node_version = ModelSemVer(major=1, minor=0, patch=0)
 
+        # Extract contract capabilities if contract is available
+        # This is automatic and non-skippable when contract is provided
+        contract_capabilities = None
+        if self._introspection_contract is not None:
+            contract_capabilities = _CAPABILITY_EXTRACTOR.extract(
+                self._introspection_contract
+            )
+
         # Create event with performance metrics (metrics is already Pydantic model)
         event = ModelNodeIntrospectionEvent(
             node_id=node_id_uuid,
@@ -1345,6 +1362,7 @@ class MixinNodeIntrospection:
             node_version=node_version,
             declared_capabilities=ModelNodeCapabilities(),
             discovered_capabilities=discovered_capabilities,
+            contract_capabilities=contract_capabilities,
             endpoints=endpoints,
             current_state=current_state,
             reason=EnumIntrospectionReason.HEARTBEAT,  # cache_refresh maps to heartbeat

omnibase_infra/models/discovery/model_introspection_config.py

@@ -27,6 +27,7 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.contracts import ModelContractBase
 
 if TYPE_CHECKING:
     from omnibase_core.protocols.event_bus.protocol_event_bus import ProtocolEventBus
@@ -86,6 +87,9 @@ class ModelIntrospectionConfig(BaseModel):
         request_introspection_topic: Topic for receiving introspection requests.
             Defaults to "node.request_introspection". ONEX topics (onex.*)
             require version suffix (.v1, .v2, etc.).
+        contract: Optional typed contract model for capability extraction.
+            When provided, MixinNodeIntrospection extracts contract_capabilities
+            using ContractCapabilityExtractor. None for legacy nodes.
 
     Example:
         ```python
@@ -185,6 +189,13 @@ class ModelIntrospectionConfig(BaseModel):
         "ONEX topics (onex.*) require version suffix (.v1, .v2, etc.).",
     )
 
+    contract: ModelContractBase | None = Field(
+        default=None,
+        description="Typed contract model for capability extraction. "
+        "When provided, MixinNodeIntrospection will extract contract_capabilities "
+        "using ContractCapabilityExtractor. None for legacy nodes without contracts.",
+    )
+
     @field_validator("node_type", mode="before")
     @classmethod
     def validate_node_type(cls, v: object) -> EnumNodeKind:

omnibase_infra/models/handlers/__init__.py

@@ -16,12 +16,21 @@ and error reporting in ONEX handlers.
     Added ModelBootstrapHandlerDescriptor for OMN-1087 bootstrap handler
     validation with required handler_class field.
 
+.. versionchanged:: 0.7.0
+    Added ModelHandlerSourceConfig for OMN-1095 handler source mode
+    configuration with production hardening features.
+
 Note:
-    ModelContractDiscoveryResult uses a forward reference to
-    ModelHandlerValidationError to avoid circular imports. The forward
-    reference is resolved via model_rebuild() in handler_contract_source.py
-    after both classes are defined. This pattern is tested in
-    tests/unit/runtime/test_handler_contract_source.py.
+    ModelContractDiscoveryResult uses a forward reference to ModelHandlerValidationError
+    to avoid circular imports between models.handlers and models.errors packages.
+    The forward reference is resolved via model_rebuild() calls in runtime modules
+    that import ModelHandlerValidationError (e.g., handler_contract_source.py,
+    handler_bootstrap_source.py, registry_contract_source.py). Each module calls
+    model_rebuild() after importing both the model and the forward-referenced type.
+    This pattern is required because:
+    1. models.errors imports ModelHandlerIdentifier from models.handlers
+    2. models.handlers cannot import from models.errors at module level (circular)
+    3. model_rebuild() is idempotent, so multiple calls are harmless
 """
 
 from omnibase_infra.models.handlers.model_bootstrap_handler_descriptor import (
@@ -37,6 +46,9 @@ from omnibase_infra.models.handlers.model_handler_descriptor import (
 from omnibase_infra.models.handlers.model_handler_identifier import (
     ModelHandlerIdentifier,
 )
+from omnibase_infra.models.handlers.model_handler_source_config import (
+    ModelHandlerSourceConfig,
+)
 
 __all__ = [
     "LiteralHandlerKind",
@@ -44,4 +56,25 @@ __all__ = [
     "ModelContractDiscoveryResult",
     "ModelHandlerDescriptor",
     "ModelHandlerIdentifier",
+    "ModelHandlerSourceConfig",
 ]
+
+# =============================================================================
+# Forward Reference Resolution
+# =============================================================================
+# ModelContractDiscoveryResult uses TYPE_CHECKING to defer import of
+# ModelHandlerValidationError to avoid circular imports:
+#   - models.errors imports ModelHandlerIdentifier from models.handlers
+#   - models.handlers cannot import ModelHandlerValidationError at module level
+#
+# The forward reference is resolved via model_rebuild() in runtime modules that
+# import ModelHandlerValidationError (e.g., handler_contract_source.py,
+# handler_bootstrap_source.py, registry_contract_source.py, handler_source_resolver.py).
+# Each module calls model_rebuild() at module level after importing both the model
+# and the forward-referenced type. This is safe because model_rebuild() is idempotent.
+#
+# Why NOT here at module level:
+#   - Circular import: models.handlers.__init__ -> models.errors.__init__
+#     -> model_handler_validation_error.py -> models.handlers (for identifier)
+#   - Runtime modules load after model packages, avoiding this cycle
+# =============================================================================