omnibase_infra 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

omnibase_infra/runtime/service_runtime_host_process.py

@@ -46,20 +46,25 @@ import asyncio
 import importlib
 import json
 import logging
+import os
 from collections.abc import Awaitable, Callable
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 from uuid import UUID, uuid4
 
 from pydantic import BaseModel
 
 from omnibase_infra.enums import (
+    EnumConsumerGroupPurpose,
     EnumHandlerSourceMode,
     EnumHandlerTypeCategory,
     EnumInfraTransportType,
 )
 from omnibase_infra.errors import (
     EnvelopeValidationError,
+    InfraConsulError,
+    InfraTimeoutError,
+    InfraUnavailableError,
     ModelInfraErrorContext,
     ProtocolConfigurationError,
     RuntimeHostError,
@@ -67,14 +72,22 @@ from omnibase_infra.errors import (
 )
 from omnibase_infra.event_bus.event_bus_inmemory import EventBusInmemory
 from omnibase_infra.event_bus.event_bus_kafka import EventBusKafka
+from omnibase_infra.models import ModelNodeIdentity
 from omnibase_infra.runtime.envelope_validator import (
     normalize_correlation_id,
     validate_envelope,
 )
 from omnibase_infra.runtime.handler_registry import RegistryProtocolBinding
-from omnibase_infra.runtime.models import ModelDuplicateResponse
+from omnibase_infra.runtime.models import (
+    ModelDuplicateResponse,
+    ModelRuntimeContractConfig,
+)
 from omnibase_infra.runtime.protocol_lifecycle_executor import ProtocolLifecycleExecutor
+from omnibase_infra.runtime.runtime_contract_config_loader import (
+    RuntimeContractConfigLoader,
+)
 from omnibase_infra.runtime.util_wiring import wire_default_handlers
+from omnibase_infra.utils.util_consumer_group import compute_consumer_group_id
 from omnibase_infra.utils.util_env_parsing import parse_env_float
 
 if TYPE_CHECKING:
@@ -90,8 +103,14 @@ if TYPE_CHECKING:
     from omnibase_infra.runtime.contract_handler_discovery import (
         ContractHandlerDiscovery,
     )
+    from omnibase_infra.runtime.service_message_dispatch_engine import (
+        MessageDispatchEngine,
+    )
 
 # Imports for PluginLoaderContractSource adapter class
+from omnibase_core.protocols.event_bus.protocol_event_bus_subscriber import (
+    ProtocolEventBusSubscriber,
+)
 from omnibase_infra.models.errors import ModelHandlerValidationError
 from omnibase_infra.models.handlers import (
     LiteralHandlerKind,
@@ -99,11 +118,20 @@ from omnibase_infra.models.handlers import (
     ModelHandlerDescriptor,
 )
 from omnibase_infra.models.types import JsonDict
+from omnibase_infra.runtime.event_bus_subcontract_wiring import (
+    EventBusSubcontractWiring,
+    load_event_bus_subcontract,
+)
 from omnibase_infra.runtime.handler_identity import (
     HANDLER_IDENTITY_PREFIX,
     handler_identity,
 )
 from omnibase_infra.runtime.handler_plugin_loader import HandlerPluginLoader
+from omnibase_infra.runtime.kafka_contract_source import (
+    TOPIC_SUFFIX_CONTRACT_DEREGISTERED,
+    TOPIC_SUFFIX_CONTRACT_REGISTERED,
+    KafkaContractSource,
+)
 from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
 # Expose wire_default_handlers as wire_handlers for test patching compatibility
@@ -159,6 +187,51 @@ DEFAULT_DRAIN_TIMEOUT_SECONDS: float = parse_env_float(
 )
 
 
+def _parse_contract_event_payload(
+    msg: ModelEventMessage,
+) -> tuple[dict[str, object], UUID] | None:
+    """Parse contract event message payload and extract correlation ID.
+
+    This helper extracts common JSON parsing and correlation ID extraction logic
+    used by contract registration and deregistration handlers.
+
+    Args:
+        msg: The event message to parse.
+
+    Returns:
+        A tuple of (payload_dict, correlation_id) if message has a value,
+        None if message value is empty.
+
+    Raises:
+        json.JSONDecodeError: If the message value is not valid JSON.
+        UnicodeDecodeError: If the message value cannot be decoded as UTF-8.
+
+    Note:
+        This function is intentionally a module-level utility rather than a
+        class method because it performs pure data transformation without
+        requiring any class state.
+
+    .. versionadded:: 0.8.0
+        Created for OMN-1654 to reduce duplication in contract event handlers.
+    """
+    if not msg.value:
+        return None
+
+    payload: dict[str, object] = json.loads(msg.value.decode("utf-8"))
+
+    # Extract correlation ID from headers if available, or generate new
+    correlation_id: UUID
+    if msg.headers and msg.headers.correlation_id:
+        try:
+            correlation_id = UUID(str(msg.headers.correlation_id))
+        except (ValueError, TypeError):
+            correlation_id = uuid4()
+    else:
+        correlation_id = uuid4()
+
+    return (payload, correlation_id)
+
+
 class PluginLoaderContractSource(ProtocolContractSource):
     """Adapter that uses HandlerPluginLoader for contract discovery.
 
@@ -526,6 +599,9 @@ class RuntimeHostProcess:
         # Handler discovery service (lazy-created if contract_paths provided)
         self._handler_discovery: ContractHandlerDiscovery | None = None
 
+        # Kafka contract source (created if KAFKA_EVENTS mode, wired separately)
+        self._kafka_contract_source: KafkaContractSource | None = None
+
         # Create or use provided event bus
         self._event_bus: EventBusInmemory | EventBusKafka = (
             event_bus or EventBusInmemory()
@@ -537,16 +613,40 @@ class RuntimeHostProcess:
         # Topic configuration (config overrides constructor args)
         self._input_topic: str = str(config.get("input_topic", input_topic))
         self._output_topic: str = str(config.get("output_topic", output_topic))
-        # Note: ModelRuntimeConfig uses field name "consumer_group" with alias "group_id".
-        # When config.model_dump() is called, it outputs "consumer_group" by default.
-        # We check both keys to support either field name or alias.
-        # Empty strings and whitespace-only strings fall through to the next option.
-        consumer_group = config.get("consumer_group")
-        group_id = config.get("group_id")
-        self._group_id: str = str(
-            (consumer_group if consumer_group and str(consumer_group).strip() else None)
-            or (group_id if group_id and str(group_id).strip() else None)
-            or DEFAULT_GROUP_ID
+
+        # Node identity configuration (required for consumer group derivation)
+        # Extract components from config - fail-fast if required fields are missing
+        _env = config.get("env")
+        env: str = str(_env).strip() if _env else "local"
+
+        _service_name = config.get("service_name")
+        if not _service_name or not str(_service_name).strip():
+            raise ValueError(
+                "RuntimeHostProcess requires 'service_name' in config. "
+                "This is the service name from your node's contract (e.g., 'omniintelligence'). "
+                "Cannot infer service_name - please provide it explicitly."
+            )
+        service_name: str = str(_service_name).strip()
+
+        _node_name = config.get("node_name")
+        if not _node_name or not str(_node_name).strip():
+            raise ValueError(
+                "RuntimeHostProcess requires 'node_name' in config. "
+                "This is the node name from your contract (e.g., 'claude_hook_event_effect'). "
+                "Cannot infer node_name - please provide it explicitly."
+            )
+        node_name: str = str(_node_name).strip()
+
+        _version = config.get("version")
+        version: str = (
+            str(_version).strip() if _version and str(_version).strip() else "v1"
+        )
+
+        self._node_identity: ModelNodeIdentity = ModelNodeIdentity(
+            env=env,
+            service=service_name,
+            node_name=node_name,
+            version=version,
         )
 
         # Health check configuration (from lifecycle subcontract pattern)
@@ -678,12 +778,32 @@ class RuntimeHostProcess:
         self._idempotency_store: ProtocolIdempotencyStore | None = None
         self._idempotency_config: ModelIdempotencyGuardConfig | None = None
 
+        # Event bus subcontract wiring for contract-driven subscriptions (OMN-1621)
+        # Bridges contract-declared topics to Kafka subscriptions.
+        # None until wired during start() when dispatch_engine is available.
+        self._event_bus_wiring: EventBusSubcontractWiring | None = None
+
+        # Message dispatch engine for routing received messages (OMN-1621)
+        # Used by event_bus_wiring to dispatch messages to handlers.
+        # None = not configured, wiring will be skipped
+        self._dispatch_engine: MessageDispatchEngine | None = None
+
+        # Baseline subscriptions for platform-reserved topics (OMN-1654)
+        # Stores unsubscribe callbacks for contract registration/deregistration topics.
+        # Wired when KAFKA_EVENTS mode is active with a KafkaContractSource.
+        self._baseline_subscriptions: list[Callable[[], Awaitable[None]]] = []
+
+        # Contract configuration loaded at startup (OMN-1519)
+        # Contains consolidated handler_routing and operation_bindings from all contracts.
+        # None until loaded during start() via _load_contract_configs()
+        self._contract_config: ModelRuntimeContractConfig | None = None
+
         logger.debug(
             "RuntimeHostProcess initialized",
             extra={
                 "input_topic": self._input_topic,
                 "output_topic": self._output_topic,
-                "group_id": self._group_id,
+                "group_id": self.group_id,
                 "health_check_timeout_seconds": self._health_check_timeout_seconds,
                 "drain_timeout_seconds": self._drain_timeout_seconds,
                 "has_container": self._container is not None,
@@ -702,6 +822,31 @@ class RuntimeHostProcess:
         """
         return self._container
 
+    @property
+    def contract_config(self) -> ModelRuntimeContractConfig | None:
+        """Return the loaded contract configuration.
+
+        Contains consolidated handler_routing and operation_bindings from all
+        contracts discovered during startup. Returns None if contracts have
+        not been loaded yet (before start() is called).
+
+        The contract config provides access to:
+            - handler_routing_configs: All loaded handler routing configurations
+            - operation_bindings_configs: All loaded operation bindings
+            - success_rate: Ratio of successfully loaded contracts
+            - error_messages: Any errors encountered during loading
+
+        Returns:
+            ModelRuntimeContractConfig if loaded, None if not yet loaded.
+
+        Example:
+            >>> process = RuntimeHostProcess(...)
+            >>> await process.start()
+            >>> if process.contract_config:
+            ...     print(f"Loaded {process.contract_config.total_contracts_loaded} contracts")
+        """
+        return self._contract_config
+
     @property
     def event_bus(self) -> EventBusInmemory | EventBusKafka:
         """Return the owned event bus instance.
@@ -742,10 +887,28 @@ class RuntimeHostProcess:
     def group_id(self) -> str:
         """Return the consumer group identifier.
 
+        Computes the consumer group ID from the node identity using the canonical
+        format: ``{env}.{service}.{node_name}.{purpose}.{version}``
+
+        Returns:
+            The computed consumer group ID for this process.
+        """
+        return compute_consumer_group_id(
+            self._node_identity, EnumConsumerGroupPurpose.CONSUME
+        )
+
+    @property
+    def node_identity(self) -> ModelNodeIdentity:
+        """Return the node identity used for consumer group derivation.
+
+        The node identity contains the environment, service name, node name,
+        and version that uniquely identify this runtime host process within
+        the ONEX infrastructure.
+
         Returns:
-            The consumer group ID for this process.
+            The immutable node identity for this process.
         """
-        return self._group_id
+        return self._node_identity
 
     @property
     def is_draining(self) -> bool:
@@ -877,7 +1040,7 @@ class RuntimeHostProcess:
             extra={
                 "input_topic": self._input_topic,
                 "output_topic": self._output_topic,
-                "group_id": self._group_id,
+                "group_id": self.group_id,
                 "has_contract_paths": len(self._contract_paths) > 0,
             },
         )
@@ -980,14 +1143,32 @@ class RuntimeHostProcess:
                 registry_protocol_count=registry_protocol_count,
             )
 
+        # Step 4.15: Load contract configurations (OMN-1519)
+        # Loads handler_routing and operation_bindings from all discovered contracts.
+        # Uses the same contract_paths configured for handler discovery.
+        # The loaded config is accessible via self.contract_config property.
+        startup_correlation_id = uuid4()
+        await self._load_contract_configs(correlation_id=startup_correlation_id)
+
+        # Step 4.2: Wire event bus subscriptions from contracts (OMN-1621)
+        # This bridges contract-declared topics to Kafka subscriptions.
+        # Requires dispatch_engine to be available for message routing.
+        await self._wire_event_bus_subscriptions()
+
+        # Step 4.3: Wire baseline subscriptions for contract discovery (OMN-1654)
+        # When KAFKA_EVENTS mode is active, subscribe to platform-reserved
+        # contract topics to receive registration/deregistration events.
+        await self._wire_baseline_subscriptions()
+
         # Step 4.5: Initialize idempotency store if configured (OMN-945)
         await self._initialize_idempotency_store()
 
         # Step 5: Subscribe to input topic
         self._subscription = await self._event_bus.subscribe(
             topic=self._input_topic,
-            group_id=self._group_id,
+            node_identity=self._node_identity,
             on_message=self._on_message,
+            purpose=EnumConsumerGroupPurpose.CONSUME,
         )
 
         self._is_running = True
@@ -997,7 +1178,7 @@ class RuntimeHostProcess:
             extra={
                 "input_topic": self._input_topic,
                 "output_topic": self._output_topic,
-                "group_id": self._group_id,
+                "group_id": self.group_id,
                 "registered_handlers": list(self._handlers.keys()),
             },
         )
@@ -1148,6 +1329,26 @@ class RuntimeHostProcess:
         # Step 2.5: Cleanup idempotency store if initialized (OMN-945)
         await self._cleanup_idempotency_store()
 
+        # Step 2.6: Cleanup event bus subcontract wiring (OMN-1621)
+        if self._event_bus_wiring:
+            await self._event_bus_wiring.cleanup()
+
+        # Step 2.7: Cleanup baseline subscriptions for contract discovery (OMN-1654)
+        if self._baseline_subscriptions:
+            for unsubscribe in self._baseline_subscriptions:
+                try:
+                    await unsubscribe()
+                except Exception as e:
+                    logger.warning(
+                        "Failed to unsubscribe baseline subscription",
+                        extra={"error": str(e)},
+                    )
+            self._baseline_subscriptions.clear()
+            logger.debug("Baseline contract subscriptions cleaned up")
+
+        # Step 2.8: Nullify KafkaContractSource reference for proper cleanup (OMN-1654)
+        self._kafka_contract_source = None
+
         # Step 3: Close event bus
         await self._event_bus.close()
 
@@ -1295,12 +1496,34 @@ class RuntimeHostProcess:
         # Create bootstrap source
         bootstrap_source = HandlerBootstrapSource()
 
+        # Check for KAFKA_EVENTS mode first
+        if source_config.effective_mode == EnumHandlerSourceMode.KAFKA_EVENTS:
+            # Create Kafka-based contract source (cache-only beta)
+            # Note: Kafka subscriptions are wired separately in _wire_baseline_subscriptions()
+            environment = self._get_environment_from_config()
+            kafka_source = KafkaContractSource(
+                environment=environment,
+                graceful_mode=True,
+            )
+            contract_source: ProtocolContractSource = kafka_source
+
+            # Store reference for subscription wiring
+            self._kafka_contract_source = kafka_source
+
+            logger.info(
+                "Using KafkaContractSource for contract discovery",
+                extra={
+                    "environment": environment,
+                    "mode": "KAFKA_EVENTS",
+                    "correlation_id": str(kafka_source.correlation_id),
+                },
+            )
         # Contract source needs paths - use configured paths or default
         # If no contract_paths provided, reuse bootstrap_source as placeholder
-        if self._contract_paths:
+        elif self._contract_paths:
             # Use PluginLoaderContractSource which uses the simpler contract schema
             # compatible with test contracts (handler_name, handler_class, handler_type)
-            contract_source: ProtocolContractSource = PluginLoaderContractSource(
+            contract_source = PluginLoaderContractSource(
                 contract_paths=self._contract_paths,
             )
         else:
@@ -1667,6 +1890,77 @@ class RuntimeHostProcess:
             },
         )
 
+    async def _load_contract_configs(self, correlation_id: UUID) -> None:
+        """Load contract configurations from all discovered contracts.
+
+        Uses RuntimeContractConfigLoader to scan for contract.yaml files and
+        load handler_routing and operation_bindings subcontracts into a
+        consolidated configuration.
+
+        This method is called during start() after handler discovery but before
+        event bus subscriptions are wired. The loaded config is stored in
+        self._contract_config and accessible via the contract_config property.
+
+        Error Handling:
+            Individual contract load failures are logged but do not stop the
+            overall loading process. This enables graceful degradation where
+            some contracts can be loaded even if others fail. Errors are
+            collected in the ModelRuntimeContractConfig for introspection.
+
+        Args:
+            correlation_id: Correlation ID for tracing this load operation.
+
+        Part of OMN-1519: Runtime contract config loader integration.
+        """
+        # Skip if no contract paths configured
+        if not self._contract_paths:
+            logger.debug(
+                "No contract paths configured, skipping contract config loading",
+                extra={"correlation_id": str(correlation_id)},
+            )
+            return
+
+        # Create loader - no namespace restrictions by default
+        # (namespace allowlisting can be added via constructor parameter if needed)
+        loader = RuntimeContractConfigLoader()
+
+        # Load all contracts from configured paths
+        self._contract_config = loader.load_all_contracts(
+            search_paths=self._contract_paths,
+            correlation_id=correlation_id,
+        )
+
+        # Log summary at INFO level
+        if self._contract_config.total_errors > 0:
+            logger.warning(
+                "Contract config loading completed with errors",
+                extra={
+                    "total_contracts_found": self._contract_config.total_contracts_found,
+                    "total_contracts_loaded": self._contract_config.total_contracts_loaded,
+                    "total_errors": self._contract_config.total_errors,
+                    "success_rate": f"{self._contract_config.success_rate:.1%}",
+                    "correlation_id": str(correlation_id),
+                    "error_paths": [
+                        str(p) for p in self._contract_config.error_messages
+                    ],
+                },
+            )
+        else:
+            logger.info(
+                "Contract config loading completed successfully",
+                extra={
+                    "total_contracts_found": self._contract_config.total_contracts_found,
+                    "total_contracts_loaded": self._contract_config.total_contracts_loaded,
+                    "handler_routing_count": len(
+                        self._contract_config.handler_routing_configs
+                    ),
+                    "operation_bindings_count": len(
+                        self._contract_config.operation_bindings_configs
+                    ),
+                    "correlation_id": str(correlation_id),
+                },
+            )
+
     async def _get_handler_registry(self) -> RegistryProtocolBinding:
         """Get handler registry (pre-resolved, container, or singleton).
 
@@ -2213,6 +2507,171 @@ class RuntimeHostProcess:
         """
         return self._handlers.get(handler_type)
 
+    async def get_subscribers_for_topic(self, topic: str) -> list[UUID]:
+        """Query Consul for node IDs that subscribe to a topic.
+
+        This method provides dynamic topic-to-subscriber lookup via Consul KV store.
+        Topics are stored at `onex/topics/{topic}/subscribers` and contain a JSON
+        array of node UUID strings.
+
+        Args:
+            topic: Environment-qualified topic string
+                   (e.g., "dev.onex.evt.intent-classified.v1")
+
+        Returns:
+            List of node UUIDs that subscribe to this topic.
+            Empty list if no subscribers registered or Consul unavailable.
+
+        Note:
+            Returns node IDs, not handler names. Node ID is the stable registry key.
+            Handler selection is a separate concern that can change independently.
+
+        Example:
+            >>> runtime = RuntimeHostProcess()
+            >>> await runtime.start()
+            >>> subscribers = await runtime.get_subscribers_for_topic(
+            ...     "dev.onex.evt.intent-classified.v1"
+            ... )
+            >>> print(subscribers)  # [UUID('abc123...'), UUID('def456...')]
+
+        Related:
+            - OMN-1613: Add event bus topic storage to registry for dynamic topic discovery
+            - MixinConsulTopicIndex: Consul mixin that manages topic index storage
+        """
+        consul_handler = self.get_handler("consul")
+        if consul_handler is None:
+            logger.debug(
+                "Consul handler not available for topic subscriber lookup",
+                extra={"topic": topic},
+            )
+            return []
+
+        try:
+            correlation_id = uuid4()
+            envelope: dict[str, object] = {
+                "operation": "consul.kv_get",
+                "payload": {"key": f"onex/topics/{topic}/subscribers"},
+                "correlation_id": str(correlation_id),
+            }
+
+            # Execute the Consul KV get operation
+            # NOTE: MVP adapters use legacy execute(envelope: dict) signature.
+            result = await consul_handler.execute(envelope)  # type: ignore[call-arg]
+
+            # Navigate to the value in the response structure:
+            # ModelHandlerOutput -> result (ModelConsulHandlerResponse)
+            #   -> payload (ModelConsulHandlerPayload) -> data (ConsulPayload)
+            if result is None:
+                return []
+
+            # Check if result has the expected structure
+            if not hasattr(result, "result") or result.result is None:
+                return []
+
+            response = result.result
+            if not hasattr(response, "payload") or response.payload is None:
+                return []
+
+            payload_data = response.payload.data
+            if payload_data is None:
+                return []
+
+            # Check for "not found" response - key doesn't exist
+            if hasattr(payload_data, "found") and payload_data.found is False:
+                return []
+
+            # Get the value field from the payload
+            value = getattr(payload_data, "value", None)
+            if not value:
+                return []
+
+            # Parse JSON array of node ID strings
+            node_ids_raw = json.loads(value)
+            if not isinstance(node_ids_raw, list):
+                logger.warning(
+                    "Topic subscriber value is not a list",
+                    extra={
+                        "topic": topic,
+                        "correlation_id": str(correlation_id),
+                        "value_type": type(node_ids_raw).__name__,
+                    },
+                )
+                return []
+
+            # Convert string UUIDs to UUID objects (skip invalid entries)
+            subscribers: list[UUID] = []
+            invalid_ids: list[str] = []
+            for nid in node_ids_raw:
+                if not isinstance(nid, str):
+                    continue
+                try:
+                    subscribers.append(UUID(nid))
+                except ValueError:
+                    invalid_ids.append(nid)
+
+            if invalid_ids:
+                logger.warning(
+                    "Invalid UUIDs in topic subscriber list",
+                    extra={
+                        "topic": topic,
+                        "correlation_id": str(correlation_id),
+                        "invalid_count": len(invalid_ids),
+                    },
+                )
+            return subscribers
+
+        except json.JSONDecodeError as e:
+            logger.warning(
+                "Failed to parse topic subscriber JSON",
+                extra={
+                    "topic": topic,
+                    "error": str(e),
+                },
+            )
+            return []
+        except InfraConsulError as e:
+            logger.warning(
+                "Consul error querying topic subscribers",
+                extra={
+                    "topic": topic,
+                    "error": str(e),
+                    "error_type": "InfraConsulError",
+                    "consul_key": getattr(e, "consul_key", None),
+                },
+            )
+            return []
+        except InfraTimeoutError as e:
+            logger.warning(
+                "Timeout querying topic subscribers",
+                extra={
+                    "topic": topic,
+                    "error": str(e),
+                    "error_type": "InfraTimeoutError",
+                },
+            )
+            return []
+        except InfraUnavailableError as e:
+            logger.warning(
+                "Service unavailable for topic subscriber query",
+                extra={
+                    "topic": topic,
+                    "error": str(e),
+                    "error_type": "InfraUnavailableError",
+                },
+            )
+            return []
+        except Exception as e:
+            # Graceful degradation - Consul unavailable is not fatal
+            logger.warning(
+                "Failed to query topic subscribers from Consul",
+                extra={
+                    "topic": topic,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+            )
+            return []
+
     # =========================================================================
     # Architecture Validation Methods (OMN-1138)
     # =========================================================================
@@ -2383,6 +2842,297 @@ class RuntimeHostProcess:
         self._container = ModelONEXContainer()
         return self._container
 
+    def _get_environment_from_config(self) -> str:
+        """Extract environment setting from config with consistent fallback.
+
+        Handles both dict-based config and object-based config (e.g., Pydantic models)
+        with a unified access pattern.
+
+        Resolution order:
+            1. config["event_bus"]["environment"] (if config is dict-like)
+            2. config.event_bus.environment (if config is object-like)
+            3. ONEX_ENVIRONMENT environment variable
+            4. "dev" (hardcoded default)
+
+        Returns:
+            Environment string (e.g., "dev", "staging", "prod").
+        """
+        default_env = os.getenv("ONEX_ENVIRONMENT", "dev")
+        config = self._config or {}
+
+        event_bus_config = config.get("event_bus", {})
+        if isinstance(event_bus_config, dict):
+            return str(event_bus_config.get("environment", default_env))
+
+        # Object-based config (e.g., ModelEventBusConfig)
+        return str(getattr(event_bus_config, "environment", default_env))
+
+    # =========================================================================
+    # Event Bus Subcontract Wiring Methods (OMN-1621)
+    # =========================================================================
+
+    async def _wire_event_bus_subscriptions(self) -> None:
+        """Wire Kafka subscriptions from handler contract event_bus sections.
+
+        This method bridges contract-declared topics to actual Kafka subscriptions
+        using the EventBusSubcontractWiring class. It reads the event_bus subcontract
+        from each handler's contract YAML and creates subscriptions for declared
+        subscribe_topics.
+
+        Preconditions:
+            - self._event_bus must be available and started
+            - self._dispatch_engine must be set (otherwise wiring is skipped)
+            - self._handler_descriptors must be populated
+
+        The wiring creates subscriptions that route messages to the dispatch engine,
+        which then routes to appropriate handlers based on topic/category matching.
+
+        Per ARCH-002: "Runtime owns all Kafka plumbing" - nodes and handlers declare
+        their topic requirements in contracts but never directly interact with Kafka.
+
+        Note:
+            If dispatch_engine is not configured, this method logs a debug message
+            and returns without creating any subscriptions. This allows the runtime
+            to operate in legacy mode without contract-driven subscriptions.
+
+        .. versionadded:: 0.2.5
+            Part of OMN-1621 contract-driven event bus wiring.
+        """
+        # Guard: require both event_bus and dispatch_engine
+        if not self._event_bus:
+            logger.debug("Event bus not available, skipping subcontract wiring")
+            return
+
+        if not self._dispatch_engine:
+            logger.debug(
+                "Dispatch engine not configured, skipping event bus subcontract wiring"
+            )
+            return
+
+        if not self._handler_descriptors:
+            logger.debug(
+                "No handler descriptors available, skipping subcontract wiring"
+            )
+            return
+
+        environment = self._get_environment_from_config()
+
+        # Create wiring instance
+        # Cast to protocol type - both EventBusKafka and EventBusInmemory implement
+        # the ProtocolEventBusSubscriber interface (subscribe method)
+        self._event_bus_wiring = EventBusSubcontractWiring(
+            event_bus=cast("ProtocolEventBusSubscriber", self._event_bus),
+            dispatch_engine=self._dispatch_engine,
+            environment=environment,
+        )
+
+        # Wire subscriptions for each handler with a contract
+        wired_count = 0
+        for handler_type, descriptor in self._handler_descriptors.items():
+            contract_path_str = descriptor.contract_path
+            if not contract_path_str:
+                continue
+
+            contract_path = Path(contract_path_str)
+
+            # Load event_bus subcontract from contract YAML
+            subcontract = load_event_bus_subcontract(contract_path, logger)
+            if subcontract and subcontract.subscribe_topics:
+                await self._event_bus_wiring.wire_subscriptions(
+                    subcontract=subcontract,
+                    node_name=descriptor.name or handler_type,
+                )
+                wired_count += 1
+                logger.info(
+                    "Wired subscription(s) for handler '%s': topics=%s",
+                    descriptor.name or handler_type,
+                    subcontract.subscribe_topics,
+                )
+
+        if wired_count > 0:
+            logger.info(
+                "Event bus subcontract wiring complete",
+                extra={
+                    "wired_handler_count": wired_count,
+                    "total_handler_count": len(self._handler_descriptors),
+                    "environment": environment,
+                },
+            )
+        else:
+            logger.debug(
+                "No handlers with event_bus subscriptions found",
+                extra={"handler_count": len(self._handler_descriptors)},
+            )
+
+    async def _wire_baseline_subscriptions(self) -> None:
+        """Wire platform-baseline topic subscriptions for contract discovery.
+
+        These subscriptions are wired at runtime startup to receive contract
+        registration and deregistration events from Kafka. This enables
+        dynamic contract discovery without polling.
+
+        The subscriptions route events to KafkaContractSource callbacks:
+        - on_contract_registered(): Parses contract YAML and caches descriptor
+        - on_contract_deregistered(): Removes descriptor from cache
+
+        Preconditions:
+            - KAFKA_EVENTS mode must be active (self._kafka_contract_source set)
+            - Event bus must be available and started
+
+        Topic Format:
+            - Registration: {env}.{TOPIC_SUFFIX_CONTRACT_REGISTERED}
+            - Deregistration: {env}.{TOPIC_SUFFIX_CONTRACT_DEREGISTERED}
+
+        Note:
+            Unsubscribe callbacks are stored in self._baseline_subscriptions
+            for cleanup during stop().
+
+        Part of OMN-1654: KafkaContractSource cache discovery.
+
+        .. versionadded:: 0.8.0
+            Created for event-driven contract discovery.
+        """
+        # Guard: only wire if KafkaContractSource is active
+        if self._kafka_contract_source is None:
+            logger.debug(
+                "KafkaContractSource not active, skipping baseline subscriptions"
+            )
+            return
+
+        # Guard: event bus must be available
+        if self._event_bus is None:
+            logger.warning(
+                "Event bus not available, cannot wire baseline contract subscriptions",
+                extra={"mode": "KAFKA_EVENTS"},
+            )
+            return
+
+        source = self._kafka_contract_source
+        environment = source.environment
+
+        # Compose topic names using platform-reserved suffixes
+        registration_topic = f"{environment}.{TOPIC_SUFFIX_CONTRACT_REGISTERED}"
+        deregistration_topic = f"{environment}.{TOPIC_SUFFIX_CONTRACT_DEREGISTERED}"
+
+        # Import ModelEventMessage type for handler signature
+        from omnibase_infra.event_bus.models.model_event_message import (
+            ModelEventMessage,
+        )
+
+        async def handle_registration(msg: ModelEventMessage) -> None:
+            """Handle contract registration event from Kafka."""
+            try:
+                parsed = _parse_contract_event_payload(msg)
+                if parsed is None:
+                    return
+
+                payload, correlation_id = parsed
+
+                source.on_contract_registered(
+                    node_name=str(payload.get("node_name", "")),
+                    contract_yaml=str(payload.get("contract_yaml", "")),
+                    correlation_id=correlation_id,
+                )
+
+                logger.debug(
+                    "Processed contract registration event",
+                    extra={
+                        "node_name": payload.get("node_name"),
+                        "topic": registration_topic,
+                        "correlation_id": str(correlation_id),
+                    },
+                )
+
+            except Exception as e:
+                logger.warning(
+                    "Failed to process contract registration event",
+                    extra={
+                        "error": str(e),
+                        "error_type": type(e).__name__,
+                        "topic": registration_topic,
+                    },
+                )
+
+        async def handle_deregistration(msg: ModelEventMessage) -> None:
+            """Handle contract deregistration event from Kafka."""
+            try:
+                parsed = _parse_contract_event_payload(msg)
+                if parsed is None:
+                    return
+
+                payload, correlation_id = parsed
+
+                source.on_contract_deregistered(
+                    node_name=str(payload.get("node_name", "")),
+                    correlation_id=correlation_id,
+                )
+
+                logger.debug(
+                    "Processed contract deregistration event",
+                    extra={
+                        "node_name": payload.get("node_name"),
+                        "topic": deregistration_topic,
+                        "correlation_id": str(correlation_id),
+                    },
+                )
+
+            except Exception as e:
+                logger.warning(
+                    "Failed to process contract deregistration event",
+                    extra={
+                        "error": str(e),
+                        "error_type": type(e).__name__,
+                        "topic": deregistration_topic,
+                    },
+                )
+
+        # Subscribe to topics
+        try:
+            # Create node identity for baseline subscriptions
+            baseline_identity = ModelNodeIdentity(
+                env=environment,
+                service=self._node_identity.service,
+                node_name=f"{self._node_identity.node_name}-contract-discovery",
+                version=self._node_identity.version,
+            )
+
+            # Subscribe to registration topic
+            reg_unsub = await self._event_bus.subscribe(
+                topic=registration_topic,
+                node_identity=baseline_identity,
+                on_message=handle_registration,
+                purpose=EnumConsumerGroupPurpose.CONSUME,
+            )
+            self._baseline_subscriptions.append(reg_unsub)
+
+            # Subscribe to deregistration topic
+            dereg_unsub = await self._event_bus.subscribe(
+                topic=deregistration_topic,
+                node_identity=baseline_identity,
+                on_message=handle_deregistration,
+                purpose=EnumConsumerGroupPurpose.CONSUME,
+            )
+            self._baseline_subscriptions.append(dereg_unsub)
+
+            logger.info(
+                "Wired baseline contract subscriptions",
+                extra={
+                    "registration_topic": registration_topic,
+                    "deregistration_topic": deregistration_topic,
+                    "environment": environment,
+                    "subscription_count": len(self._baseline_subscriptions),
+                },
+            )
+
+        except Exception:
+            logger.exception(
+                "Failed to wire baseline subscriptions",
+                extra={
+                    "registration_topic": registration_topic,
+                    "deregistration_topic": deregistration_topic,
+                },
+            )
+
     # =========================================================================
     # Idempotency Guard Methods (OMN-945)
     # =========================================================================