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

omnibase_infra/runtime/contract_dependency_resolver.py

@@ -0,0 +1,455 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract dependency resolver for ONEX nodes.
+
+This module provides ContractDependencyResolver, which reads protocol
+dependencies from a node's contract.yaml and resolves them from the
+container's service_registry.
+
+Part of OMN-1732: Runtime dependency injection for zero-code nodes.
+
+Architecture:
+    - Container: service provider (owns protocol instances)
+    - Runtime (this resolver): wiring authority (resolves + validates)
+    - Node: consumer (receives resolved deps via constructor)
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, cast
+
+import yaml
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import (
+    ModelInfraErrorContext,
+    ProtocolConfigurationError,
+    ProtocolDependencyResolutionError,
+)
+from omnibase_infra.models.runtime.model_resolved_dependencies import (
+    ModelResolvedDependencies,
+)
+
+if TYPE_CHECKING:
+    from omnibase_core.container import ModelONEXContainer
+    from omnibase_core.models.contracts import ModelContractBase
+
+logger = logging.getLogger(__name__)
+
+
+class ContractDependencyResolver:
+    """Resolves protocol dependencies from contracts using container.
+
+    Reads the `dependencies` field from a node's contract, filters for
+    protocol-type dependencies, imports the protocol classes, and resolves
+    instances from the container's service_registry.
+
+    This resolver implements the "fail-fast" principle: if any required
+    protocol cannot be resolved, it raises ProtocolDependencyResolutionError
+    immediately rather than allowing node creation with missing dependencies.
+
+    Example:
+        >>> from omnibase_core.container import ModelONEXContainer
+        >>>
+        >>> container = ModelONEXContainer()
+        >>> # ... register protocols in container ...
+        >>>
+        >>> resolver = ContractDependencyResolver(container)
+        >>> resolved = await resolver.resolve(node_contract)
+        >>>
+        >>> # Use resolved dependencies for node creation
+        >>> node = NodeRegistry.create(container, dependencies=resolved)
+
+    .. versionadded:: 0.x.x
+        Part of OMN-1732 runtime dependency injection.
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the resolver with a container.
+
+        Args:
+            container: ONEX container with service_registry for protocol resolution.
+        """
+        self._container = container
+
+    async def resolve(
+        self,
+        contract: ModelContractBase,
+        *,
+        allow_missing: bool = False,
+    ) -> ModelResolvedDependencies:
+        """Resolve protocol dependencies from a contract.
+
+        Reads contract.dependencies, filters for protocol-type entries,
+        and resolves each from the container's service_registry.
+
+        Args:
+            contract: The node contract containing dependency declarations.
+            allow_missing: If True, skip missing protocols instead of raising.
+                          Default False (fail-fast behavior).
+
+        Returns:
+            ModelResolvedDependencies containing resolved protocol instances.
+
+        Raises:
+            ProtocolDependencyResolutionError: If any required protocol cannot
+                be resolved and allow_missing is False.
+
+        Example:
+            >>> resolved = await resolver.resolve(contract)
+            >>> adapter = resolved.get("ProtocolPostgresAdapter")
+        """
+        # Extract protocol dependencies from contract
+        protocol_deps = self._extract_protocol_dependencies(contract)
+
+        if not protocol_deps:
+            logger.debug(
+                "No protocol dependencies declared in contract",
+                extra={"contract_name": getattr(contract, "name", "unknown")},
+            )
+            return ModelResolvedDependencies()
+
+        # Resolve each protocol from container
+        # ONEX_EXCLUDE: any_type - dict holds heterogeneous protocol instances resolved at runtime
+        resolved: dict[str, Any] = {}
+        missing: list[str] = []
+        resolution_errors: dict[str, str] = {}
+
+        for dep in protocol_deps:
+            class_name = dep.get("class_name")
+            module_path = dep.get("module")
+
+            if not class_name:
+                logger.warning(
+                    "Protocol dependency missing class_name, skipping",
+                    extra={"dependency": dep},
+                )
+                continue
+
+            try:
+                # Import the protocol class
+                protocol_class = self._import_protocol_class(class_name, module_path)
+
+                # Resolve from container
+                instance = await self._resolve_from_container(protocol_class)
+                resolved[class_name] = instance
+
+                logger.debug(
+                    "Resolved protocol dependency",
+                    extra={
+                        "protocol": class_name,
+                        "module_path": module_path,
+                    },
+                )
+
+            except Exception as e:
+                error_msg = str(e)
+                resolution_errors[class_name] = error_msg
+                missing.append(class_name)
+
+                logger.warning(
+                    "Failed to resolve protocol dependency",
+                    extra={
+                        "protocol": class_name,
+                        "module_path": module_path,
+                        "error": error_msg,
+                    },
+                )
+
+        # Fail-fast if any protocols are missing
+        if missing and not allow_missing:
+            contract_name = getattr(contract, "name", "unknown")
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="resolve_dependencies",
+                target_name=contract_name,
+            )
+
+            error_details = "\n".join(
+                f"  - {proto}: {resolution_errors.get(proto, 'unknown error')}"
+                for proto in missing
+            )
+
+            raise ProtocolDependencyResolutionError(
+                f"Cannot create node '{contract_name}': missing required protocols.\n"
+                f"The following protocols are declared in contract.yaml but could not "
+                f"be resolved from the container:\n{error_details}\n\n"
+                f"Ensure these protocols are registered in the container before "
+                f"node creation via container.service_registry.register_instance().",
+                context=context,
+                missing_protocols=missing,
+                node_name=contract_name,
+            )
+
+        return ModelResolvedDependencies(protocols=resolved)
+
+    def _extract_protocol_dependencies(
+        self,
+        contract: ModelContractBase,
+    ) -> list[dict[str, str]]:
+        """Extract protocol-type dependencies from contract.
+
+        Supports multiple detection patterns:
+        1. `type` field = "protocol" (YAML contract style)
+        2. `is_protocol()` method returns True
+        3. `dependency_type` attribute with value "PROTOCOL"
+
+        Args:
+            contract: The contract to extract dependencies from.
+
+        Returns:
+            List of dependency dicts with keys: name, type, class_name, module
+        """
+        dependencies: list[dict[str, str]] = []
+
+        # Get dependencies attribute if present
+        contract_deps = getattr(contract, "dependencies", None)
+        if not contract_deps:
+            return dependencies
+
+        for dep in contract_deps:
+            is_protocol = self._is_protocol_dependency(dep)
+
+            if is_protocol:
+                dep_dict: dict[str, str] = {}
+
+                # Extract fields - handle both attribute and dict access
+                if hasattr(dep, "name"):
+                    dep_dict["name"] = str(dep.name) if dep.name else ""
+                if hasattr(dep, "class_name"):
+                    dep_dict["class_name"] = (
+                        str(dep.class_name) if dep.class_name else ""
+                    )
+                if hasattr(dep, "module"):
+                    dep_dict["module"] = str(dep.module) if dep.module else ""
+
+                # Only add if we have a class_name
+                if dep_dict.get("class_name"):
+                    dependencies.append(dep_dict)
+
+        return dependencies
+
+    # ONEX_EXCLUDE: any_type - dep can be ModelContractDependency or dict from various sources
+    def _is_protocol_dependency(self, dep: Any) -> bool:
+        """Check if a dependency is a protocol dependency.
+
+        Supports multiple detection patterns:
+        1. `type` field = "protocol" (YAML contract style)
+        2. `is_protocol()` method returns True
+        3. `dependency_type` attribute with value "PROTOCOL"
+
+        Args:
+            dep: The dependency object to check.
+
+        Returns:
+            True if this is a protocol dependency, False otherwise.
+        """
+        # Check is_protocol() method first (most explicit)
+        if hasattr(dep, "is_protocol") and callable(dep.is_protocol):
+            if dep.is_protocol():
+                return True
+
+        # Check dependency_type attribute (enum or string)
+        if hasattr(dep, "dependency_type"):
+            dep_type_val = dep.dependency_type
+            if hasattr(dep_type_val, "value"):
+                # Enum with .value
+                if str(dep_type_val.value).upper() == "PROTOCOL":
+                    return True
+            elif str(dep_type_val).upper() == "PROTOCOL":
+                return True
+
+        # Check type field (YAML contract style: type: "protocol")
+        if hasattr(dep, "type"):
+            type_val = getattr(dep, "type", "")
+            if str(type_val).lower() == "protocol":
+                return True
+
+        return False
+
+    def _import_protocol_class(
+        self,
+        class_name: str,
+        module_path: str | None,
+    ) -> type:
+        """Import a protocol class by name and module.
+
+        Args:
+            class_name: The class name to import
+            module_path: The module path (required for import)
+
+        Returns:
+            The imported class type.
+
+        Raises:
+            ImportError: If the class cannot be imported.
+        """
+        if not module_path:
+            raise ImportError(
+                f"Protocol '{class_name}' has no module path specified in contract. "
+                f"Cannot import without module path."
+            )
+
+        try:
+            module = importlib.import_module(module_path)
+            protocol_class = getattr(module, class_name)
+            return cast("type", protocol_class)
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                f"Module '{module_path}' not found for protocol '{class_name}': {e}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class '{class_name}' not found in module '{module_path}': {e}"
+            ) from e
+
+    # ONEX_EXCLUDE: any_type - returns protocol instance, type varies by resolved protocol class
+    async def _resolve_from_container(self, protocol_class: type) -> Any:
+        """Resolve a protocol instance from the container.
+
+        Args:
+            protocol_class: The protocol class type to resolve.
+
+        Returns:
+            The resolved protocol instance.
+
+        Raises:
+            RuntimeError: If container.service_registry is None.
+            Exception: If resolution fails (propagated from container).
+        """
+        if self._container.service_registry is None:
+            raise RuntimeError(
+                "Container service_registry is None. "
+                "Ensure container is properly initialized with service_registry enabled."
+            )
+
+        return await self._container.service_registry.resolve_service(protocol_class)
+
+    async def resolve_from_path(
+        self,
+        contract_path: Path,
+        *,
+        allow_missing: bool = False,
+    ) -> ModelResolvedDependencies:
+        """Resolve protocol dependencies from a contract.yaml file path.
+
+        Loads the contract YAML, extracts the dependencies section, and resolves
+        each protocol from the container's service_registry. This is a convenience
+        method that combines file loading with dependency resolution.
+
+        Part of OMN-1903: Runtime dependency injection integration.
+
+        Args:
+            contract_path: Path object to the contract.yaml file.
+            allow_missing: If True, skip missing protocols instead of raising.
+                          Default False (fail-fast behavior).
+
+        Returns:
+            ModelResolvedDependencies containing resolved protocol instances.
+            Returns empty ModelResolvedDependencies if contract has no dependencies.
+
+        Raises:
+            ProtocolConfigurationError: If contract file cannot be loaded or parsed.
+            ProtocolDependencyResolutionError: If any required protocol cannot
+                be resolved and allow_missing is False.
+
+        Example:
+            >>> resolver = ContractDependencyResolver(container)
+            >>> resolved = await resolver.resolve_from_path(
+            ...     Path("src/nodes/my_node/contract.yaml")
+            ... )
+            >>> adapter = resolved.get("ProtocolPostgresAdapter")
+
+        .. versionadded:: 0.x.x
+            Part of OMN-1903 runtime dependency injection integration.
+        """
+        path = contract_path
+
+        # Load and parse the contract YAML
+        contract_data = self._load_contract_yaml(path)
+
+        # Check if contract has dependencies section
+        if "dependencies" not in contract_data or not contract_data["dependencies"]:
+            logger.debug(
+                "No dependencies section in contract, skipping resolution",
+                extra={"contract_path": str(path)},
+            )
+            return ModelResolvedDependencies()
+
+        # Create a lightweight contract object for the resolver
+        # Uses SimpleNamespace for duck-typing compatibility with resolve()
+        contract_name = contract_data.get("name", path.stem)
+        dependencies = [SimpleNamespace(**dep) for dep in contract_data["dependencies"]]
+        contract = SimpleNamespace(name=contract_name, dependencies=dependencies)
+
+        logger.debug(
+            "Resolving dependencies from contract path",
+            extra={
+                "contract_path": str(path),
+                "contract_name": contract_name,
+                "dependency_count": len(dependencies),
+            },
+        )
+
+        # Type ignore: contract is a SimpleNamespace duck-typed to match ModelContractBase
+        # The resolver uses getattr() internally so any object with name/dependencies works
+        return await self.resolve(contract, allow_missing=allow_missing)  # type: ignore[arg-type]
+
+    # ONEX_EXCLUDE: any_type - yaml.safe_load returns heterogeneous dict, values vary by contract schema
+    def _load_contract_yaml(self, path: Path) -> dict[str, Any]:
+        """Load and parse a contract.yaml file.
+
+        Args:
+            path: Path to the contract YAML file.
+
+        Returns:
+            Parsed YAML content as a dictionary.
+
+        Raises:
+            ProtocolConfigurationError: If file doesn't exist or cannot be parsed.
+        """
+        if not path.exists():
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.FILESYSTEM,
+                operation="load_contract_yaml",
+                target_name=str(path),
+            )
+            raise ProtocolConfigurationError(
+                f"Contract file not found: {path}",
+                context=context,
+            )
+
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+                if data is None:
+                    data = {}
+                # ONEX_EXCLUDE: any_type - yaml.safe_load returns Any, we validate structure elsewhere
+                return cast("dict[str, Any]", data)
+        except yaml.YAMLError as e:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.FILESYSTEM,
+                operation="load_contract_yaml",
+                target_name=str(path),
+            )
+            raise ProtocolConfigurationError(
+                f"Failed to parse contract YAML at {path}: {e}",
+                context=context,
+            ) from e
+        except OSError as e:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.FILESYSTEM,
+                operation="load_contract_yaml",
+                target_name=str(path),
+            )
+            raise ProtocolConfigurationError(
+                f"Failed to read contract file at {path}: {e}",
+                context=context,
+            ) from e
+
+
+__all__ = ["ContractDependencyResolver"]

omnibase_infra/runtime/contract_registration_event_router.py

@@ -11,10 +11,10 @@ The router:
     - Routes to ContractRegistryReducer.reduce() for state transitions
     - Emits intents for Effect layer execution (PostgreSQL operations)
 
-Topics Handled:
-    - {env}.onex.evt.platform.contract-registered.v1 -> ModelContractRegisteredEvent
-    - {env}.onex.evt.platform.contract-deregistered.v1 -> ModelContractDeregisteredEvent
-    - {env}.onex.evt.platform.node-heartbeat.v1 -> ModelNodeHeartbeatEvent
+Topics Handled (realm-agnostic, no environment prefix):
+    - onex.evt.platform.contract-registered.v1 -> ModelContractRegisteredEvent
+    - onex.evt.platform.contract-deregistered.v1 -> ModelContractDeregisteredEvent
+    - onex.evt.platform.node-heartbeat.v1 -> ModelNodeHeartbeatEvent
 
 Design:
     This class encapsulates the message routing logic for contract registration
@@ -69,7 +69,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 # Topic suffix patterns for event type matching
-# These match the topic suffix after the environment prefix
+# Topics are realm-agnostic (no environment prefix)
 TOPIC_SUFFIX_CONTRACT_REGISTERED = "onex.evt.platform.contract-registered.v1"
 TOPIC_SUFFIX_CONTRACT_DEREGISTERED = "onex.evt.platform.contract-deregistered.v1"
 TOPIC_SUFFIX_NODE_HEARTBEAT = "onex.evt.platform.node-heartbeat.v1"

omnibase_infra/runtime/emit_daemon/event_registry.py

@@ -25,15 +25,15 @@ Example Usage:
     registry.register(
         ModelEventRegistration(
             event_type="custom.event",
-            topic_template="{env}.onex.evt.custom.event.v1",
+            topic_template="onex.evt.custom.event.v1",
             partition_key_field="session_id",
             required_fields=["session_id", "user_id"],
         )
     )
 
-    # Resolve topic for event type
+    # Resolve topic for event type (realm-agnostic, no env prefix)
     topic = registry.resolve_topic("prompt.submitted")
-    # Returns: "dev.onex.evt.omniclaude.prompt-submitted.v1"
+    # Returns: "onex.evt.omniclaude.prompt-submitted.v1"
 
     # Inject metadata into payload
     enriched = registry.inject_metadata(
@@ -70,8 +70,10 @@ class ModelEventRegistration(BaseModel):
     Attributes:
         event_type: Semantic event type identifier (e.g., "prompt.submitted").
             This is the logical name used by event emitters.
-        topic_template: Kafka topic name template with {env} placeholder.
-            Example: "{env}.onex.evt.omniclaude.prompt-submitted.v1"
+        topic_template: Kafka topic name (realm-agnostic, no environment prefix).
+            Example: "onex.evt.omniclaude.prompt-submitted.v1"
+            Note: Topics are realm-agnostic in ONEX. The environment/realm is
+            enforced via envelope identity, not topic naming.
         partition_key_field: Optional field name in payload to use as partition key.
             When set, ensures events with same key go to same partition for ordering.
         required_fields: List of field names that must be present in payload.
@@ -82,7 +84,7 @@ class ModelEventRegistration(BaseModel):
     Example:
         >>> reg = ModelEventRegistration(
         ...     event_type="prompt.submitted",
-        ...     topic_template="{env}.onex.evt.omniclaude.prompt-submitted.v1",
+        ...     topic_template="onex.evt.omniclaude.prompt-submitted.v1",
         ...     partition_key_field="session_id",
         ...     required_fields=["prompt", "session_id"],
         ...     schema_version="1.0.0",
@@ -99,7 +101,7 @@ class ModelEventRegistration(BaseModel):
         description="Semantic event type identifier (e.g., 'prompt.submitted')",
     )
     topic_template: str = Field(
-        description="Kafka topic name template with {env} placeholder",
+        description="Kafka topic name (realm-agnostic, no environment prefix)",
     )
     partition_key_field: str | None = Field(
         default=None,
@@ -133,7 +135,7 @@ class EventRegistry:
         >>> registry = EventRegistry(environment="dev")
         >>> topic = registry.resolve_topic("prompt.submitted")
         >>> print(topic)
-        'dev.onex.evt.omniclaude.prompt-submitted.v1'
+        'onex.evt.omniclaude.prompt-submitted.v1'
 
         >>> registry.validate_payload("prompt.submitted", {"prompt": "Hello"})
         True
@@ -144,6 +146,11 @@ class EventRegistry:
         ... )
         >>> "correlation_id" in enriched
         True
+
+    Note:
+        Topics are realm-agnostic in ONEX. The environment is stored for
+        potential use in consumer group derivation by related components,
+        but topics themselves do not include environment prefixes.
     """
 
     def __init__(self, environment: str = "dev") -> None:
@@ -156,7 +163,11 @@ class EventRegistry:
         Example:
             >>> registry = EventRegistry(environment="staging")
             >>> registry.resolve_topic("prompt.submitted")
-            'staging.onex.evt.omniclaude.prompt-submitted.v1'
+            'onex.evt.omniclaude.prompt-submitted.v1'
+
+        Note:
+            The environment is stored for potential consumer group derivation
+            in related components. Topics themselves are realm-agnostic.
         """
         self._environment = environment
         self._registrations: dict[str, ModelEventRegistration] = {}
@@ -174,25 +185,25 @@ class EventRegistry:
         defaults = [
             ModelEventRegistration(
                 event_type="prompt.submitted",
-                topic_template="{env}.onex.evt.omniclaude.prompt-submitted.v1",
+                topic_template="onex.evt.omniclaude.prompt-submitted.v1",
                 partition_key_field="session_id",
                 required_fields=["prompt"],
             ),
             ModelEventRegistration(
                 event_type="session.started",
-                topic_template="{env}.onex.evt.omniclaude.session-started.v1",
+                topic_template="onex.evt.omniclaude.session-started.v1",
                 partition_key_field="session_id",
                 required_fields=["session_id"],
             ),
             ModelEventRegistration(
                 event_type="session.ended",
-                topic_template="{env}.onex.evt.omniclaude.session-ended.v1",
+                topic_template="onex.evt.omniclaude.session-ended.v1",
                 partition_key_field="session_id",
                 required_fields=["session_id"],
             ),
             ModelEventRegistration(
                 event_type="tool.executed",
-                topic_template="{env}.onex.evt.omniclaude.tool-executed.v1",
+                topic_template="onex.evt.omniclaude.tool-executed.v1",
                 partition_key_field="session_id",
                 required_fields=["tool_name"],
             ),
@@ -214,25 +225,26 @@ class EventRegistry:
             >>> registry.register(
             ...     ModelEventRegistration(
             ...         event_type="custom.event",
-            ...         topic_template="{env}.onex.evt.custom.event.v1",
+            ...         topic_template="onex.evt.custom.event.v1",
             ...     )
             ... )
             >>> registry.resolve_topic("custom.event")
-            'dev.onex.evt.custom.event.v1'
+            'onex.evt.custom.event.v1'
         """
         self._registrations[registration.event_type] = registration
 
     def resolve_topic(self, event_type: str) -> str:
-        """Get the Kafka topic for an event type.
+        """Get the Kafka topic for an event type (realm-agnostic).
 
-        Resolves the topic template by substituting the {env} placeholder
-        with the configured environment name.
+        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:
             event_type: Semantic event type identifier.
 
         Returns:
-            Fully resolved Kafka topic name.
+            Kafka topic name (no environment prefix).
 
         Raises:
             OnexError: If the event type is not registered.
@@ -240,7 +252,7 @@ class EventRegistry:
         Example:
             >>> registry = EventRegistry(environment="prod")
             >>> registry.resolve_topic("prompt.submitted")
-            'prod.onex.evt.omniclaude.prompt-submitted.v1'
+            'onex.evt.omniclaude.prompt-submitted.v1'
         """
         registration = self._registrations.get(event_type)
         if registration is None:
@@ -248,7 +260,7 @@ class EventRegistry:
             raise OnexError(
                 f"Unknown event type: '{event_type}'. Registered types: {registered}"
             )
-        return registration.topic_template.format(env=self._environment)
+        return registration.topic_template
 
     def get_partition_key(
         self,
@@ -452,7 +464,7 @@ class EventRegistry:
             >>> registry = EventRegistry()
             >>> reg = registry.get_registration("prompt.submitted")
             >>> reg.topic_template
-            '{env}.onex.evt.omniclaude.prompt-submitted.v1'
+            'onex.evt.omniclaude.prompt-submitted.v1'
         """
         return self._registrations.get(event_type)