omnibase_infra 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

omnibase_infra/runtime/models/model_runtime_config.py

@@ -47,6 +47,9 @@ from __future__ import annotations
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from omnibase_infra.runtime.models.model_contract_registry_config import (
+    ModelContractRegistryConfig,
+)
 from omnibase_infra.runtime.models.model_enabled_protocols_config import (
     ModelEnabledProtocolsConfig,
 )
@@ -72,6 +75,7 @@ class ModelRuntimeConfig(BaseModel):
         protocols: Enabled protocols configuration [RESERVED]
         logging: Logging configuration [RESERVED]
         shutdown: Shutdown configuration [ACTIVE - grace_period_seconds used]
+        contract_registry: Contract registry configuration [ACTIVE]
 
     Field Status Legend:
         [ACTIVE]   - Currently used by kernel.py
@@ -145,6 +149,10 @@ class ModelRuntimeConfig(BaseModel):
         default_factory=ModelShutdownConfig,
         description="Shutdown configuration",
     )
+    contract_registry: ModelContractRegistryConfig = Field(
+        default_factory=ModelContractRegistryConfig,
+        description="Contract registry configuration",
+    )
 
 
 __all__: list[str] = ["ModelRuntimeConfig"]

omnibase_infra/runtime/protocols/__init__.py

@@ -23,15 +23,31 @@ Related:
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 # Re-export from omnibase_core for convenience
 from omnibase_core.protocols.notifications import (
     ProtocolTransitionNotificationPublisher,
 )
+from omnibase_infra.runtime.protocols.protocol_intent_executor import (
+    PayloadT_contra,
+    ProtocolIntentExecutor,
+)
 from omnibase_infra.runtime.protocols.protocol_runtime_scheduler import (
     ProtocolRuntimeScheduler,
 )
 
+if TYPE_CHECKING:
+    # IntentPayloadType is only available for type checking - it references
+    # models from nodes.* which aren't loaded during package initialization.
+    from omnibase_infra.runtime.protocols.protocol_intent_executor import (
+        IntentPayloadType,
+    )
+
+# NOTE: IntentPayloadType is only available under TYPE_CHECKING (see above)
 __all__: list[str] = [
+    "PayloadT_contra",
+    "ProtocolIntentExecutor",
     "ProtocolRuntimeScheduler",
     "ProtocolTransitionNotificationPublisher",
 ]

omnibase_infra/runtime/protocols/protocol_intent_executor.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for intent executors in the contract persistence pipeline.
+
+This module defines the protocol interface for intent executors that process
+persistence intents from the ContractRegistryReducer.
+
+Design:
+    Uses a Generic Protocol with contravariant TypeVar to properly express that
+    each handler accepts its specific payload type while the router can store
+    any handler conforming to the protocol. This avoids the need for `object`
+    workarounds and `cast()` at call sites.
+
+Related:
+    - IntentExecutionRouter: Uses this protocol for handler routing
+    - OMN-1869: Implementation ticket
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    # These imports are only needed for type annotations.
+    # Using TYPE_CHECKING avoids circular import during package initialization
+    # (runtime.protocols is loaded before nodes is loaded).
+    from omnibase_infra.models.model_backend_result import (
+        ModelBackendResult,
+    )
+    from omnibase_infra.nodes.contract_registry_reducer.models import (
+        ModelPayloadCleanupTopicReferences,
+        ModelPayloadDeactivateContract,
+        ModelPayloadMarkStale,
+        ModelPayloadUpdateHeartbeat,
+        ModelPayloadUpdateTopic,
+        ModelPayloadUpsertContract,
+    )
+
+    # Type alias for payload types (union of all supported payloads)
+    # Defined inside TYPE_CHECKING since it references models only available there
+    IntentPayloadType = (
+        ModelPayloadUpsertContract
+        | ModelPayloadUpdateTopic
+        | ModelPayloadMarkStale
+        | ModelPayloadUpdateHeartbeat
+        | ModelPayloadDeactivateContract
+        | ModelPayloadCleanupTopicReferences
+    )
+
+# Contravariant TypeVar for payload types - allows handlers with specific
+# payload types to satisfy the protocol when used with broader type hints
+PayloadT_contra = TypeVar("PayloadT_contra", contravariant=True)
+
+
+@runtime_checkable
+class ProtocolIntentExecutor(Protocol[PayloadT_contra]):
+    """Generic protocol for intent executors.
+
+    All persistence executors implement this interface, enabling type-safe
+    routing without tight coupling to specific implementations.
+
+    The protocol uses a contravariant TypeVar for the payload parameter,
+    which correctly expresses that:
+    - A handler accepting `ModelPayloadUpsertContract` can be stored where
+      `ProtocolIntentExecutor[Any]` is expected
+    - The router can call `handle()` with any payload that matches the
+      handler's declared payload type
+
+    Type Parameters:
+        PayloadT_contra: The payload type this executor accepts (contravariant).
+
+    Example:
+        >>> class HandlerPostgresContractUpsert:
+        ...     async def handle(
+        ...         self,
+        ...         payload: ModelPayloadUpsertContract,
+        ...         correlation_id: UUID,
+        ...     ) -> ModelBackendResult: ...
+        >>>
+        >>> # Handler satisfies ProtocolIntentExecutor[ModelPayloadUpsertContract]
+        >>> # and can be stored as ProtocolIntentExecutor[Any]
+        >>> handlers: dict[str, ProtocolIntentExecutor[Any]] = {
+        ...     "upsert": HandlerPostgresContractUpsert(pool),
+        ... }
+    """
+
+    async def handle(
+        self,
+        payload: PayloadT_contra,
+        correlation_id: UUID,
+    ) -> ModelBackendResult:
+        """Execute the handler operation.
+
+        Args:
+            payload: The typed payload model for this handler.
+            correlation_id: Request correlation ID for distributed tracing.
+
+        Returns:
+            ModelBackendResult with execution status.
+        """
+        ...
+
+
+# NOTE: IntentPayloadType is only available under TYPE_CHECKING.
+# Import it with: if TYPE_CHECKING: from ...protocol_intent_executor import IntentPayloadType
+__all__ = ["PayloadT_contra", "ProtocolIntentExecutor"]