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

omnibase_infra/protocols/protocol_container_aware.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol extension for Infrastructure Handlers with Container DI.
+
+This module defines the ProtocolContainerAware interface, which extends the base
+ProtocolHandler from omnibase_spi to add container-based dependency injection
+requirements. All infrastructure handlers in omnibase_infra must implement this
+extended protocol.
+
+Why This Protocol Exists:
+    The base ProtocolHandler in omnibase_spi is intentionally minimal and doesn't
+    mandate a specific constructor signature. This keeps the SPI layer decoupled
+    from implementation details.
+
+    However, omnibase_infra handlers require ModelONEXContainer for:
+    - Dependency injection of shared services (connection pools, clients)
+    - Configuration access without global state
+    - Testability through container mocking
+
+    This protocol adds the __init__ signature requirement while inheriting all
+    method requirements from the base protocol.
+
+Protocol Hierarchy:
+    omnibase_spi.ProtocolHandler (base)
+        - handler_type property
+        - initialize()
+        - shutdown()
+        - execute()
+        - describe()
+        - health_check()
+
+    omnibase_infra.ProtocolContainerAware (extension)
+        - All methods from ProtocolHandler
+        - __init__(container: ModelONEXContainer) requirement
+
+Usage:
+    Infrastructure handlers should implement this extended protocol:
+
+    ```python
+    from omnibase_core.container import ModelONEXContainer
+    from omnibase_infra.protocols import ProtocolContainerAware
+
+    class HandlerDatabase:
+        '''Database handler implementing the infra protocol.'''
+
+        def __init__(self, container: ModelONEXContainer) -> None:
+            self._container = container
+            # Access shared resources via container
+
+        @property
+        def handler_type(self) -> str:
+            return "db"
+
+        # ... implement remaining protocol methods ...
+    ```
+
+    The RuntimeHostProcess uses this protocol for type-safe handler instantiation:
+
+    ```python
+    handler_cls: type[ProtocolContainerAware] = handler_registry.get(handler_type)
+    handler_instance = handler_cls(container=container)  # Type-safe
+    ```
+
+Thread Safety:
+    Handler implementations must be thread-safe. The container provides access
+    to shared resources that may be used concurrently.
+
+See Also:
+    - omnibase_spi.protocols.handlers.protocol_handler.ProtocolHandler
+    - omnibase_core.container.ModelONEXContainer
+    - CLAUDE.md section "Container-Based Dependency Injection"
+    - PR #186: Container DI refactoring for handlers
+
+.. versionadded:: 0.7.1
+    Created as part of OMN-1434 container DI standardization.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from omnibase_spi.protocols.handlers.protocol_handler import (
+    ProtocolHandler as ProtocolHandlerBase,
+)
+
+if TYPE_CHECKING:
+    from omnibase_core.container import ModelONEXContainer
+
+__all__ = [
+    "ProtocolContainerAware",
+]
+
+
+@runtime_checkable
+class ProtocolContainerAware(ProtocolHandlerBase, Protocol):
+    """Extended protocol for infrastructure handlers with container DI.
+
+    This protocol extends the base ProtocolHandler from omnibase_spi to require
+    a constructor that accepts ModelONEXContainer for dependency injection.
+
+    All infrastructure handlers in omnibase_infra must implement this protocol.
+    The container provides access to:
+    - Database connection pools
+    - HTTP clients
+    - Service discovery clients
+    - Configuration values
+    - Logging context
+
+    Methods inherited from ProtocolHandler:
+        handler_type: Property returning the handler type identifier.
+        initialize: Initialize clients and connection pools.
+        shutdown: Release resources and close connections.
+        execute: Execute protocol-specific operations.
+        describe: Return handler metadata and capabilities.
+        health_check: Check handler health and connectivity.
+
+    Constructor Requirement (added by this protocol):
+        __init__: Must accept container: ModelONEXContainer as first positional argument.
+
+    Example:
+        ```python
+        from omnibase_core.container import ModelONEXContainer
+
+        class HandlerConsul:
+            def __init__(self, container: ModelONEXContainer) -> None:
+                self._container = container
+                self._consul_url = container.config.get("consul_url")
+
+            @property
+            def handler_type(self) -> str:
+                return "consul"
+
+            async def initialize(self, config):
+                # Use container for shared resources
+                ...
+
+            # ... implement remaining methods ...
+        ```
+
+    Protocol Verification:
+        Per ONEX conventions, verify protocol compliance via duck typing:
+
+        ```python
+        handler_cls = handler_registry.get("http")
+
+        # Verify constructor signature accepts container
+        import inspect
+        sig = inspect.signature(handler_cls.__init__)
+        params = list(sig.parameters.keys())
+        assert "container" in params or len(params) > 1  # self + container
+
+        # Verify protocol methods exist
+        assert hasattr(handler_cls, "handler_type")
+        assert hasattr(handler_cls, "initialize") and callable(getattr(handler_cls, "initialize"))
+        ```
+
+    Note:
+        Method bodies in this Protocol use ``...`` (Ellipsis) rather than
+        ``raise NotImplementedError()``. This is the standard Python convention
+        for ``typing.Protocol`` classes per PEP 544.
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the handler with a dependency injection container.
+
+        All infrastructure handlers receive their dependencies through the
+        container rather than as individual constructor arguments. This enables:
+
+        - Consistent initialization across all handlers
+        - Easy testing through container mocking
+        - Runtime configuration without code changes
+        - Shared resource management (connection pools, clients)
+
+        Args:
+            container: ONEX dependency injection container providing access to:
+                - Configuration values (container.config)
+                - Shared services (database pools, HTTP clients)
+                - Logging context
+                - Runtime metadata
+
+        Note:
+            Handlers should store the container reference and access dependencies
+            lazily when needed, rather than extracting all values in __init__.
+            This improves startup time and allows for late-bound configuration.
+
+        Example:
+            ```python
+            def __init__(self, container: ModelONEXContainer) -> None:
+                self._container = container
+                self._client: httpx.AsyncClient | None = None  # Lazy init
+
+            async def initialize(self, config):
+                # Create client during initialize(), not __init__()
+                self._client = httpx.AsyncClient(
+                    base_url=self._container.config.get("base_url"),
+                    timeout=config.get("timeout", 30.0),
+                )
+            ```
+        """
+        ...

omnibase_infra/runtime/__init__.py

@@ -160,6 +160,15 @@ from omnibase_infra.runtime.handler_bootstrap_source import (
     SOURCE_TYPE_BOOTSTRAP,
 )
 
+# Handler identity helper (OMN-1095)
+from omnibase_infra.runtime.handler_identity import (
+    HANDLER_IDENTITY_PREFIX,
+    handler_identity,
+)
+
+# Handler source resolver (OMN-1095)
+from omnibase_infra.runtime.handler_source_resolver import HandlerSourceResolver
+
 # Handler contract config loader
 from omnibase_infra.runtime.handler_contract_config_loader import (
     MAX_CONTRACT_SIZE_BYTES,
@@ -212,6 +221,20 @@ from omnibase_infra.runtime.transition_notification_outbox import (
     TransitionNotificationOutbox,
 )
 
+# Registry contract source (OMN-1100)
+from omnibase_infra.runtime.registry_contract_source import (
+    DEFAULT_CONSUL_HOST,
+    DEFAULT_CONSUL_PORT,
+    DEFAULT_CONTRACT_PREFIX,
+    RegistryContractSource,
+    adelete_contract_from_consul,
+    alist_contracts_in_consul,
+    astore_contract_in_consul,
+    delete_contract_from_consul,
+    list_contracts_in_consul,
+    store_contract_in_consul,
+)
+
 # Chain-aware dispatch (OMN-951) - must be imported LAST to avoid circular import
 from omnibase_infra.runtime.chain_aware_dispatch import (
     ChainAwareDispatcher,
@@ -320,6 +343,11 @@ __all__: list[str] = [
     # Handler bootstrap source (OMN-1087)
     "HandlerBootstrapSource",
     "SOURCE_TYPE_BOOTSTRAP",
+    # Handler identity helper (OMN-1095)
+    "HANDLER_IDENTITY_PREFIX",
+    "handler_identity",
+    # Handler source resolver (OMN-1095)
+    "HandlerSourceResolver",
     # Handler contract config loader
     "MAX_CONTRACT_SIZE_BYTES",
     "extract_handler_config",
@@ -343,4 +371,15 @@ __all__: list[str] = [
     # Transition notification publisher and outbox (OMN-1139)
     "TransitionNotificationOutbox",
     "TransitionNotificationPublisher",
+    # Registry contract source (OMN-1100)
+    "DEFAULT_CONSUL_HOST",
+    "DEFAULT_CONSUL_PORT",
+    "DEFAULT_CONTRACT_PREFIX",
+    "RegistryContractSource",
+    "adelete_contract_from_consul",
+    "alist_contracts_in_consul",
+    "astore_contract_in_consul",
+    "delete_contract_from_consul",
+    "list_contracts_in_consul",
+    "store_contract_in_consul",
 ]

omnibase_infra/runtime/handler_bootstrap_source.py

@@ -79,6 +79,7 @@ from omnibase_infra.runtime.handler_contract_config_loader import (
     extract_handler_config,
     load_handler_contract_config,
 )
+from omnibase_infra.runtime.handler_identity import handler_identity
 from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
 
@@ -95,7 +96,7 @@ class BootstrapEffectDefinition(TypedDict):
     must always specify their implementation class.
 
     Attributes:
-        handler_id: Unique identifier with "bootstrap." prefix.
+        handler_id: Unique identifier with "proto." prefix (protocol identity namespace).
         name: Human-readable display name.
         description: Handler purpose description.
         handler_kind: ONEX handler archetype (all are "effect" for I/O handlers).
@@ -116,36 +117,27 @@ class BootstrapEffectDefinition(TypedDict):
 
 
 # =============================================================================
-# Thread-Safe Model Rebuild Pattern (Deferred Execution)
+# Thread-Safe Model Rebuild Pattern (Safety Net)
 # =============================================================================
 #
-# This module uses a DEFERRED model_rebuild() pattern with thread-safe
-# double-checked locking. This differs from HandlerContractSource which uses
-# a simpler module-level model_rebuild() call.
+# ModelContractDiscoveryResult.model_rebuild() is now called CENTRALLY in
+# omnibase_infra.models.handlers.__init__ to resolve forward references.
+# This ensures the forward reference to ModelHandlerValidationError is resolved
+# as soon as the handlers package is imported.
 #
-# WHY DEFERRED (runtime) vs IMMEDIATE (module-load):
-#   - HandlerBootstrapSource is imported through runtime.__init__.py during
-#     application bootstrap, BEFORE all model dependencies are fully resolved
-#   - If we called model_rebuild() at module load time (like HandlerContractSource),
-#     it would fail with circular import errors because ModelHandlerValidationError
-#     may not be fully defined yet in the import chain
-#   - HandlerContractSource can use immediate module-level model_rebuild() because
-#     by the time that module is imported (via explicit user code, not runtime init),
-#     all dependencies are already resolved
+# This module retains a DEFERRED, thread-safe model_rebuild() call as a SAFETY NET:
+#   - model_rebuild() is idempotent - multiple calls are harmless
+#   - The flag-guarded pattern ensures at most one rebuild per process
+#   - This provides fallback protection if import order changes in the future
 #
-# WHY THREAD-SAFE:
+# WHY THREAD-SAFE (historical context):
 #   - discover_handlers() may be called concurrently from multiple threads
 #   - Unlike module-level code (which Python imports once, thread-safely),
 #     runtime-invoked code needs explicit synchronization
-#   - The double-checked locking pattern minimizes lock contention: after the
-#     first successful rebuild, subsequent calls hit only the fast path check
-#
-# PATTERN COMPARISON:
-#   - HandlerBootstrapSource: Deferred + thread-safe (this file)
-#   - HandlerContractSource: Immediate + module-level (see that file for rationale)
+#   - The double-checked locking pattern minimizes lock contention
 #
 # See Also:
-#   - handler_contract_source.py lines 49-68 for the immediate pattern rationale
+#   - omnibase_infra.models.handlers.__init__: Central model_rebuild() location
 #   - OMN-1087 for the ticket tracking this design decision
 # =============================================================================
 
@@ -229,7 +221,7 @@ _HANDLER_TYPE_VAULT = "vault"
 # Bootstrap handler definitions.
 #
 # Each entry contains the metadata needed to create a ModelHandlerDescriptor:
-#   handler_id: Unique identifier with "bootstrap." prefix
+#   handler_id: Unique identifier with "proto." prefix (protocol identity namespace)
 #   name: Human-readable display name
 #   description: Handler purpose description
 #   handler_kind: ONEX handler archetype (all are "effect" for I/O handlers)
@@ -252,7 +244,7 @@ _HANDLER_TYPE_VAULT = "vault"
 # providing compile-time type safety for the hardcoded values.
 _BOOTSTRAP_HANDLER_DEFINITIONS: list[BootstrapEffectDefinition] = [
     {
-        "handler_id": f"bootstrap.{_HANDLER_TYPE_CONSUL}",
+        "handler_id": handler_identity(_HANDLER_TYPE_CONSUL),
         "name": "Consul Handler",
         "description": "HashiCorp Consul service discovery handler",
         "handler_kind": "effect",
@@ -262,7 +254,7 @@ _BOOTSTRAP_HANDLER_DEFINITIONS: list[BootstrapEffectDefinition] = [
         "contract_path": "contracts/handlers/consul/handler_contract.yaml",
     },
     {
-        "handler_id": f"bootstrap.{_HANDLER_TYPE_DATABASE}",
+        "handler_id": handler_identity(_HANDLER_TYPE_DATABASE),
         "name": "Database Handler",
         "description": "PostgreSQL database handler",
         "handler_kind": "effect",
@@ -272,7 +264,7 @@ _BOOTSTRAP_HANDLER_DEFINITIONS: list[BootstrapEffectDefinition] = [
         "contract_path": "contracts/handlers/db/handler_contract.yaml",
     },
     {
-        "handler_id": f"bootstrap.{_HANDLER_TYPE_HTTP}",
+        "handler_id": handler_identity(_HANDLER_TYPE_HTTP),
         "name": "HTTP Handler",
         "description": "HTTP REST protocol handler",
         "handler_kind": "effect",
@@ -282,7 +274,7 @@ _BOOTSTRAP_HANDLER_DEFINITIONS: list[BootstrapEffectDefinition] = [
         "contract_path": "contracts/handlers/http/handler_contract.yaml",
     },
     {
-        "handler_id": f"bootstrap.{_HANDLER_TYPE_VAULT}",
+        "handler_id": handler_identity(_HANDLER_TYPE_VAULT),
         "name": "Vault Handler",
         "description": "HashiCorp Vault secret management handler",
         "handler_kind": "effect",
@@ -292,7 +284,7 @@ _BOOTSTRAP_HANDLER_DEFINITIONS: list[BootstrapEffectDefinition] = [
         "contract_path": "contracts/handlers/vault/handler_contract.yaml",
     },
     {
-        "handler_id": f"bootstrap.{_HANDLER_TYPE_MCP}",
+        "handler_id": handler_identity(_HANDLER_TYPE_MCP),
         "name": "MCP Handler",
         "description": "Model Context Protocol handler for AI agent integration",
         "handler_kind": "effect",
@@ -331,13 +323,14 @@ class HandlerBootstrapSource(
         >>> source = HandlerBootstrapSource()
         >>> result = await source.discover_handlers()
         >>> print(f"Found {len(result.descriptors)} bootstrap handlers")
-        Found 4 bootstrap handlers
+        Found 5 bootstrap handlers
         >>> for desc in result.descriptors:
         ...     print(f"  - {desc.handler_id}: {desc.description}")
-        - bootstrap.consul: HashiCorp Consul service discovery handler
-        - bootstrap.db: PostgreSQL database handler
-        - bootstrap.http: HTTP REST protocol handler
-        - bootstrap.vault: HashiCorp Vault secret management handler
+        - proto.consul: HashiCorp Consul service discovery handler
+        - proto.db: PostgreSQL database handler
+        - proto.http: HTTP REST protocol handler
+        - proto.mcp: Model Context Protocol handler for AI agent integration
+        - proto.vault: HashiCorp Vault secret management handler
 
     Performance Characteristics:
         - No filesystem or network I/O required

omnibase_infra/runtime/handler_contract_config_loader.py

@@ -95,7 +95,7 @@ def load_handler_contract_config(
     Example:
         >>> contract = load_handler_contract_config(
         ...     "contracts/handlers/consul/handler_contract.yaml",
-        ...     "bootstrap.consul",
+        ...     "proto.consul",
         ... )
         >>> contract["name"]
         'handler-consul'

omnibase_infra/runtime/handler_contract_source.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 import logging
 import time
 from pathlib import Path
+from typing import cast
 
 import yaml
 from pydantic import ValidationError
@@ -41,62 +42,18 @@ from omnibase_core.models.primitives import ModelSemVer
 from omnibase_infra.enums import EnumHandlerErrorType, EnumHandlerSourceType
 from omnibase_infra.models.errors import ModelHandlerValidationError
 from omnibase_infra.models.handlers import (
+    LiteralHandlerKind,
     ModelContractDiscoveryResult,
     ModelHandlerDescriptor,
     ModelHandlerIdentifier,
 )
 from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
-# =============================================================================
-# Module-Level Model Rebuild Pattern (Immediate Execution)
-# =============================================================================
-#
-# This module uses a simple MODULE-LEVEL model_rebuild() call. This differs from
-# HandlerBootstrapSource which uses a deferred, thread-safe pattern.
-#
-# WHY IMMEDIATE (module-load) IS SAFE HERE:
-#   - HandlerContractSource is NOT imported through runtime.__init__.py
-#   - This module is imported explicitly by user code AFTER the runtime is
-#     initialized and all model dependencies are resolved
-#   - Python's import mechanism is inherently thread-safe for module-level code:
-#     the import lock ensures module initialization runs exactly once, even if
-#     multiple threads import the same module simultaneously
-#   - Therefore, no explicit thread-safety mechanism (locks) is needed
-#
-# WHY HANDLERBOOTSTRAPSOURCE NEEDS DEFERRED PATTERN:
-#   - HandlerBootstrapSource is imported during runtime bootstrap (via __init__.py)
-#   - At that point, ModelHandlerValidationError may not be fully resolved
-#   - Additionally, discover_handlers() may be called from multiple threads,
-#     requiring explicit synchronization for the rebuild call
-#
-# PATTERN COMPARISON:
-#   - HandlerContractSource: Immediate + module-level (this file)
-#   - HandlerBootstrapSource: Deferred + thread-safe (see that file for rationale)
-#
-# See Also:
-#   - handler_bootstrap_source.py lines 68-100 for the deferred pattern rationale
-#   - OMN-1087 for the ticket tracking this design decision
-# =============================================================================
-#
-# Rebuild ModelContractDiscoveryResult to resolve the forward reference
-# to ModelHandlerValidationError. This must happen after ModelHandlerValidationError
-# is imported to make the type available for Pydantic validation.
-#
-# Why forward reference resolution is needed:
-#   ModelContractDiscoveryResult has a field typed as list[ModelHandlerValidationError].
-#   ModelHandlerValidationError imports ModelHandlerIdentifier from models.handlers.
-#   If ModelContractDiscoveryResult directly imported ModelHandlerValidationError,
-#   it would cause a circular import because models.handlers.__init__.py imports
-#   ModelContractDiscoveryResult.
-#
-# The solution:
-#   1. ModelContractDiscoveryResult uses TYPE_CHECKING to defer the import
-#   2. With PEP 563 (from __future__ import annotations), the annotation becomes
-#      a string at runtime, avoiding the circular import
-#   3. model_rebuild() resolves the string annotation to the actual type after
-#      both classes are defined
-#
-# This is tested in: tests/unit/runtime/test_handler_contract_source.py
+# Forward Reference Resolution:
+# ModelContractDiscoveryResult uses a forward reference to ModelHandlerValidationError.
+# Since we import ModelHandlerValidationError above, we can call model_rebuild() here
+# to resolve the forward reference. This call is idempotent - multiple calls are harmless.
+# This ensures the model is fully defined before we create instances in discover_handlers().
 ModelContractDiscoveryResult.model_rebuild()
 
 logger = logging.getLogger(__name__)
@@ -735,7 +692,9 @@ class HandlerContractSource(ProtocolContractSource):
             handler_id=contract.handler_id,
             name=contract.name,
             version=contract.contract_version,
-            handler_kind=contract.descriptor.handler_kind,
+            handler_kind=cast(
+                "LiteralHandlerKind", contract.descriptor.node_archetype.value
+            ),
             input_model=contract.input_model,
             output_model=contract.output_model,
             description=contract.description,

omnibase_infra/runtime/handler_identity.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Identity Utilities for HYBRID Mode Resolution.
+
+This module provides the `handler_identity()` function used by both bootstrap
+and contract sources to generate consistent handler IDs. This enables per-handler
+identity matching in HYBRID mode.
+
+The Problem:
+    Prior to this module, contract-discovered handlers used a "bootstrap." prefix
+    for handler_id to enable HYBRID mode identity matching. This was semantically
+    confusing because "bootstrap" reads like "where it came from," not "what it is."
+
+The Solution:
+    A neutral "proto." prefix that indicates this is a **protocol identity namespace**,
+    not a source indicator. Both HandlerBootstrapSource and PluginLoaderContractSource
+    use this shared helper to generate consistent IDs.
+
+Example:
+    >>> from omnibase_infra.runtime.handler_identity import handler_identity
+    >>> handler_identity("consul")
+    'proto.consul'
+    >>> handler_identity("http")
+    'proto.http'
+
+See Also:
+    - HandlerSourceResolver._resolve_hybrid(): Resolution logic that compares handler_id
+    - HandlerBootstrapSource: Uses this to generate bootstrap handler IDs
+    - PluginLoaderContractSource: Uses this for contract-discovered handlers
+
+Part of OMN-1095: Handler Source Mode Feature Flag / Bootstrap Contract Hybrid.
+
+.. versionadded:: 0.7.0
+    Introduced to fix handler ID namespace confusion.
+"""
+
+from __future__ import annotations
+
+# Prefix used for handler identity in HYBRID mode resolution.
+# This is a protocol namespace, NOT a source indicator.
+# Both bootstrap and contract sources use this prefix.
+HANDLER_IDENTITY_PREFIX = "proto"
+
+
+def handler_identity(protocol_type: str) -> str:
+    """Generate stable handler identity for HYBRID mode resolution.
+
+    Both bootstrap and contract sources use this to generate consistent IDs,
+    enabling per-handler identity matching in HYBRID mode. When both sources
+    provide a handler with the same identity, the resolver applies precedence
+    rules (contract wins by default, or bootstrap wins if allow_bootstrap_override=True).
+
+    The "proto." prefix indicates this is a **protocol identity namespace**, not
+    a source origin indicator. Contract-discovered handlers use this prefix
+    specifically so they can be compared against bootstrap-discovered handlers
+    with the same protocol_type.
+
+    Args:
+        protocol_type: The protocol type (e.g., "consul", "http", "db", "vault", "mcp").
+
+    Returns:
+        Stable handler identity string (e.g., "proto.consul", "proto.http").
+
+    Example:
+        >>> handler_identity("consul")
+        'proto.consul'
+        >>> handler_identity("http")
+        'proto.http'
+
+    See Also:
+        HandlerSourceResolver._resolve_hybrid() for resolution logic that uses
+        these identities to determine which handler wins when both sources
+        provide handlers with the same identity.
+    """
+    return f"{HANDLER_IDENTITY_PREFIX}.{protocol_type}"
+
+
+__all__ = [
+    "HANDLER_IDENTITY_PREFIX",
+    "handler_identity",
+]

omnibase_infra/runtime/handler_plugin_loader.py

@@ -659,6 +659,20 @@ class HandlerPluginLoader(ProtocolHandlerPluginLoader):
             },
         )
 
+        # contract.handler_version is guaranteed non-None by model_validator
+        if contract.handler_version is None:
+            context = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="load_from_contract",
+            )
+            raise ProtocolConfigurationError(
+                "handler_version should be set by model_validator",
+                context=context,
+                loader_error=EnumHandlerLoaderError.MISSING_REQUIRED_FIELDS.value,
+                contract_path=str(contract_path),
+            )
+
         return ModelLoadedHandler(
             handler_name=handler_name,
             protocol_type=protocol_type,
@@ -667,6 +681,7 @@ class HandlerPluginLoader(ProtocolHandlerPluginLoader):
             contract_path=resolved_contract_path,
             capability_tags=capability_tags,
             loaded_at=datetime.now(UTC),
+            handler_version=contract.handler_version,
         )
 
     def load_from_directory(

omnibase_infra/runtime/handler_registry.py

@@ -74,7 +74,7 @@ from omnibase_infra.runtime.registry.registry_protocol_binding import (
 
 if TYPE_CHECKING:
     from omnibase_core.protocol.protocol_event_bus import ProtocolEventBus
-    from omnibase_spi.protocols.handlers.protocol_handler import ProtocolHandler
+    from omnibase_infra.protocols import ProtocolContainerAware
 
 # =============================================================================
 # Handler Type Constants
@@ -115,6 +115,12 @@ HANDLER_TYPE_MCP: str = "mcp"
 The MCP handler exposes ONEX nodes as tools for AI agents via streamable HTTP.
 Supports tools/list and tools/call operations per the MCP specification."""
 
+HANDLER_TYPE_GRAPH: str = "graph"
+"""Graph database (Memgraph/Neo4j) protocol handler type."""
+
+HANDLER_TYPE_INTENT: str = "intent"  # DEMO (OMN-1515)
+"""Intent storage and query handler type for demo wiring."""
+
 
 # =============================================================================
 # Event Bus Kind Constants
@@ -192,7 +198,7 @@ def get_event_bus_registry() -> RegistryEventBusBinding:
 # =============================================================================
 
 
-def get_handler_class(handler_type: str) -> type[ProtocolHandler]:
+def get_handler_class(handler_type: str) -> type[ProtocolContainerAware]:
     """Get handler class for the given type from the singleton registry.
 
     Convenience function that wraps get_handler_registry().get().
@@ -275,7 +281,7 @@ def register_handlers_from_config(
 
         TODO(OMN-41): Implement full handler resolution:
         1. Use importlib to resolve protocol_class string to actual class
-        2. Validate class implements ProtocolHandler protocol
+        2. Validate class implements ProtocolContainerAware protocol
         3. Register handler with runtime via get_handler_registry()
         4. Support handler instantiation options from config.options
     """
@@ -300,8 +306,10 @@ __all__: list[str] = [
     "HANDLER_TYPE_CONSUL",
     "HANDLER_TYPE_DATABASE",
     "HANDLER_TYPE_GRPC",
+    "HANDLER_TYPE_GRAPH",
     # Handler type constants
     "HANDLER_TYPE_HTTP",
+    "HANDLER_TYPE_INTENT",
     "HANDLER_TYPE_KAFKA",
     "HANDLER_TYPE_MCP",
     "HANDLER_TYPE_VALKEY",