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

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"]

omnibase_infra/runtime/publisher_topic_scoped.py

@@ -9,7 +9,7 @@ event emission and maintaining clean architectural boundaries.
 
 Design Principles:
     - **Contract-Driven Access Control**: Topics must be declared in contract
-    - **Environment-Aware Routing**: Topic suffixes are prefixed with environment
+    - **Realm-Agnostic Topics**: Topics passed through unchanged (no env prefix)
     - **Fail-Fast Validation**: Invalid topics raise immediately, not at delivery
     - **Duck-Typed Protocol**: Implements publisher protocol without explicit inheritance
 
@@ -95,7 +95,7 @@ class PublisherTopicScoped:
 
     Features:
         - Contract-driven topic access control
-        - Environment-aware topic resolution
+        - Realm-agnostic topics (no environment prefix)
         - Fail-fast validation on disallowed topics
         - JSON serialization for payloads
         - Correlation ID propagation for distributed tracing
@@ -103,7 +103,7 @@ class PublisherTopicScoped:
     Attributes:
         _event_bus: The underlying event bus for publishing
         _allowed_topics: Set of topic suffixes allowed by contract
-        _environment: Environment prefix for topic resolution
+        _environment: Environment identifier (retained for future use)
 
     Example:
         >>> publisher = PublisherTopicScoped(
@@ -132,8 +132,8 @@ class PublisherTopicScoped:
                 Must implement publish(topic, key, value) method. Duck typed per ONEX.
             allowed_topics: Set of topic suffixes from contract's publish_topics.
                 These are the ONLY topics this publisher can publish to.
-            environment: Environment prefix (e.g., 'dev', 'staging', 'prod').
-                Used to construct full topic names.
+            environment: Environment identifier (e.g., 'dev', 'staging', 'prod').
+                Retained for future use; topics are realm-agnostic (no prefix).
 
         Example:
             >>> publisher = PublisherTopicScoped(
@@ -174,22 +174,27 @@ class PublisherTopicScoped:
         return str(correlation_id).encode("utf-8")
 
     def resolve_topic(self, topic_suffix: str) -> str:
-        """Resolve topic suffix to full topic name with environment prefix.
+        """Resolve topic suffix to topic name (realm-agnostic, no environment prefix).
 
-        The full topic name follows the ONEX convention:
-        `{environment}.{topic_suffix}`
+        Topics are realm-agnostic in ONEX. The environment/realm is enforced via
+        envelope identity, not topic naming. This enables cross-environment event
+        routing when needed while maintaining proper isolation through identity.
 
         Args:
             topic_suffix: ONEX format topic suffix (e.g., 'onex.events.v1')
 
         Returns:
-            Full topic name with environment prefix (e.g., 'dev.onex.events.v1')
+            Topic name (same as suffix, no environment prefix)
 
         Example:
             >>> publisher.resolve_topic("onex.events.v1")
-            'dev.onex.events.v1'
+            'onex.events.v1'
+
+        Note:
+            The environment is still stored for potential consumer group derivation
+            in related components. Topics themselves are realm-agnostic.
         """
-        return f"{self._environment}.{topic_suffix}"
+        return topic_suffix
 
     async def publish(
         self,

omnibase_infra/runtime/registry_policy.py

@@ -86,7 +86,6 @@ from typing import TYPE_CHECKING
 
 from pydantic import ValidationError
 
-from omnibase_core.models.primitives import ModelSemVer
 from omnibase_infra.enums import EnumInfraTransportType, EnumPolicyType
 from omnibase_infra.errors import PolicyRegistryError, ProtocolConfigurationError
 from omnibase_infra.models.errors.model_infra_error_context import (
@@ -97,6 +96,7 @@ from omnibase_infra.runtime.mixin_semver_cache import MixinSemverCache
 from omnibase_infra.runtime.models import ModelPolicyKey, ModelPolicyRegistration
 from omnibase_infra.runtime.util_version import normalize_version
 from omnibase_infra.types import PolicyTypeInput
+from omnibase_infra.utils import validate_policy_type_value
 
 if TYPE_CHECKING:
     from omnibase_infra.runtime.protocol_policy import ProtocolPolicy
@@ -463,11 +463,13 @@ class RegistryPolicy(MixinPolicyValidation, MixinSemverCache):
         and string literals, normalizing them to their string representation while
         ensuring they match valid EnumPolicyType values.
 
+        Delegates validation to the shared ``validate_policy_type_value()`` utility,
+        which is the SINGLE SOURCE OF TRUTH for policy type validation in omnibase_infra.
+
         Validation Process:
-            1. If policy_type is EnumPolicyType instance, extract .value
-            2. If policy_type is string, validate against EnumPolicyType values
-            3. Raise PolicyRegistryError if string doesn't match any enum value
-            4. Return normalized string value
+            1. Delegate to validate_policy_type_value() for validation and coercion
+            2. Extract .value from the validated EnumPolicyType
+            3. Return normalized string value
 
         This centralized validation ensures consistent policy type handling across
         all registry operations (register, get, list_keys, is_registered, unregister).
@@ -498,12 +500,14 @@ class RegistryPolicy(MixinPolicyValidation, MixinSemverCache):
             PolicyRegistryError: Invalid policy_type: 'invalid'.
                                  Must be one of: ['orchestrator', 'reducer']
         """
-        if isinstance(policy_type, EnumPolicyType):
-            return policy_type.value
-
-        # Validate string against enum values
-        valid_types = {e.value for e in EnumPolicyType}
-        if policy_type not in valid_types:
+        try:
+            # Use shared validation utility (SINGLE SOURCE OF TRUTH)
+            validated_enum = validate_policy_type_value(policy_type)
+            return validated_enum.value
+        except ValueError as exc:
+            # Convert ValueError from shared utility to PolicyRegistryError
+            # for consistent error handling in the registry
+            valid_types = {pt.value for pt in EnumPolicyType}
             context = ModelInfraErrorContext.with_correlation(
                 transport_type=EnumInfraTransportType.RUNTIME,
                 operation="normalize_policy_type",
@@ -512,11 +516,9 @@ class RegistryPolicy(MixinPolicyValidation, MixinSemverCache):
                 f"Invalid policy_type: {policy_type!r}. "
                 f"Must be one of: {sorted(valid_types)}",
                 policy_id=None,
-                policy_type=policy_type,
+                policy_type=str(policy_type),
                 context=context,
-            )
-
-        return policy_type
+            ) from exc
 
     @staticmethod
     def _normalize_version(version: str) -> str:
@@ -656,6 +658,10 @@ class RegistryPolicy(MixinPolicyValidation, MixinSemverCache):
         Partial version strings (e.g., "1", "1.0") are auto-normalized to
         "x.y.z" format by ModelPolicyRegistration.
 
+        .. deprecated::
+            This method is deprecated. Use ``register(ModelPolicyRegistration(...))``
+            directly for new code. This method will be removed in a future version.
+
         Note:
             For new code, prefer using register(ModelPolicyRegistration(...))
             directly. This is a convenience method for simple registrations.
@@ -684,6 +690,14 @@ class RegistryPolicy(MixinPolicyValidation, MixinSemverCache):
             ...     version="1.0.0",
             ... )
         """
+        # Emit deprecation warning at runtime
+        warnings.warn(
+            "register_policy() is deprecated. Use register(ModelPolicyRegistration(...)) "
+            "instead. This method will be removed in a future version.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         # Version normalization is handled by ModelPolicyRegistration validator
         # which normalizes partial versions and v-prefixed versions automatically
         try: