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

omnibase_infra/constants_topic_patterns.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Topic pattern constants for event bus topic validation.
+
+This module provides shared regex patterns for validating event bus topic names.
+These patterns are used across multiple modules (e.g., MixinConsulTopicIndex,
+MixinNodeIntrospection) to ensure consistent topic validation.
+
+Note:
+    This module is intentionally dependency-free (no imports from omnibase_infra)
+    to avoid circular import issues. Keep it that way.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+# Topic name pattern: alphanumeric, underscores, hyphens, and periods only.
+# This matches Kafka/Redpanda topic naming conventions and ensures safe
+# interpolation into Consul KV paths (prevents path traversal via slashes).
+# Pattern: ^[a-zA-Z0-9._-]+$
+TOPIC_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-zA-Z0-9._-]+$")
+
+
+__all__: list[str] = ["TOPIC_NAME_PATTERN"]

omnibase_infra/enums/__init__.py

@@ -16,6 +16,7 @@ Exports:
     EnumChainViolationType: Chain violation types for correlation/causation validation
     EnumCircuitState: Circuit breaker states (CLOSED, OPEN, HALF_OPEN)
     EnumConfirmationEventType: Registration confirmation event types
+    EnumConsumerGroupPurpose: Consumer group purpose (CONSUME, INTROSPECTION, REPLAY, AUDIT, BACKFILL)
     EnumContractType: Contract types for ONEX nodes (effect, compute, reducer, orchestrator)
     EnumDispatchStatus: Dispatch operation status enumeration
     EnumEnvironment: Deployment environment classification (DEVELOPMENT, STAGING, PRODUCTION, CI)
@@ -54,6 +55,7 @@ from omnibase_infra.enums.enum_capture_state import EnumCaptureState
 from omnibase_infra.enums.enum_chain_violation_type import EnumChainViolationType
 from omnibase_infra.enums.enum_circuit_state import EnumCircuitState
 from omnibase_infra.enums.enum_confirmation_event_type import EnumConfirmationEventType
+from omnibase_infra.enums.enum_consumer_group_purpose import EnumConsumerGroupPurpose
 from omnibase_infra.enums.enum_contract_type import EnumContractType
 from omnibase_infra.enums.enum_dedupe_strategy import EnumDedupeStrategy
 from omnibase_infra.enums.enum_dispatch_status import EnumDispatchStatus
@@ -97,6 +99,7 @@ __all__: list[str] = [
     "EnumChainViolationType",
     "EnumCircuitState",
     "EnumConfirmationEventType",
+    "EnumConsumerGroupPurpose",
     "EnumContractType",
     "EnumDedupeStrategy",
     "EnumDispatchStatus",

omnibase_infra/enums/enum_consumer_group_purpose.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consumer group purpose enumeration.
+
+This module defines the purpose classification for Kafka consumer groups,
+enabling semantic differentiation of consumer behavior and offset policies.
+
+Consumer Group Purpose Categories:
+    - CONSUME: Standard event consumption (default behavior)
+    - INTROSPECTION: Node introspection and discovery operations
+    - REPLAY: Reprocess historical data from earliest offset
+    - AUDIT: Compliance and read-only consumption
+    - BACKFILL: One-shot bounded consumers for populating derived state
+
+The purpose determines consumer group naming conventions and default
+offset reset policies in the Kafka adapter layer.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+
+See Also:
+    - ModelKafkaConsumerConfig: Consumer configuration using this enum
+    - docs/decisions/adr-consumer-group-naming.md: Naming conventions
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EnumConsumerGroupPurpose(str, Enum):
+    """Consumer group purpose classification for Kafka consumers.
+
+    Defines the semantic purpose of a consumer group, which influences:
+    - Consumer group naming conventions (suffix added to group ID)
+    - Default offset reset policy (earliest vs latest)
+    - Expected consumption patterns (continuous vs bounded)
+
+    Values:
+        CONSUME: Standard event consumption for normal processing.
+            - Default offset reset: latest
+            - Naming: {base_group_id}-consume
+            - Pattern: Continuous consumption
+
+        INTROSPECTION: Node introspection and service discovery.
+            - Default offset reset: latest
+            - Naming: {base_group_id}-introspection
+            - Pattern: Targeted discovery queries
+
+        REPLAY: Reprocess historical data from the beginning.
+            - Default offset reset: earliest
+            - Naming: {base_group_id}-replay
+            - Pattern: Full topic reprocessing
+
+        AUDIT: Compliance and read-only consumption.
+            - Default offset reset: earliest
+            - Naming: {base_group_id}-audit
+            - Pattern: Full audit trail capture
+
+        BACKFILL: One-shot bounded consumers for derived state.
+            - Default offset reset: earliest
+            - Naming: {base_group_id}-backfill
+            - Pattern: Bounded consumption until caught up
+
+    Example:
+        >>> purpose = EnumConsumerGroupPurpose.REPLAY
+        >>> f"order-processor-{purpose.value}"
+        'order-processor-replay'
+    """
+
+    CONSUME = "consume"
+    """Standard event consumption (default)."""
+
+    INTROSPECTION = "introspection"
+    """Node introspection and discovery."""
+
+    REPLAY = "replay"
+    """Reprocess historical data from earliest offset."""
+
+    AUDIT = "audit"
+    """Compliance/read-only consumption."""
+
+    BACKFILL = "backfill"
+    """One-shot bounded consumers for populating derived state."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+
+__all__: list[str] = ["EnumConsumerGroupPurpose"]

omnibase_infra/enums/enum_handler_source_mode.py

@@ -6,7 +6,7 @@ Defines the canonical source modes for handler loading in the ONEX runtime.
 Each mode determines where handlers are discovered and loaded from, enabling
 flexible deployment configurations and migration strategies.
 
-Handler loading can operate in three modes:
+Handler loading can operate in four modes:
     - BOOTSTRAP: Only use hardcoded bootstrap handlers.
                  Uses the legacy hardcoded handler registry. No YAML contract
                  discovery. Useful for minimal deployments or testing.
@@ -18,6 +18,11 @@ Handler loading can operate in three modes:
               When a handler identity matches both bootstrap and contract,
               the contract-defined handler wins. Bootstrap handlers serve
               as fallback for handlers not defined in contracts.
+    - KAFKA_EVENTS: Cache-only Kafka-based contract discovery.
+                    Subscribes to platform-reserved contract topics and
+                    maintains an in-memory cache of discovered handlers.
+                    Does NOT wire business subscriptions dynamically.
+                    For beta: discover + next restart applies model.
 
 The HYBRID mode supports gradual migration from hardcoded to contract-based
 handlers by allowing both sources to coexist with deterministic resolution.
@@ -26,6 +31,7 @@ See Also:
     - EnumHandlerSourceType: Defines validation error source types (different purpose)
     - HandlerPluginLoader: Uses this enum to determine loading strategy
     - ModelRuntimeConfig: Configuration model that holds the source mode setting
+    - KafkaContractSource: Implements KAFKA_EVENTS mode (OMN-1654)
 """
 
 from enum import Enum
@@ -36,7 +42,7 @@ class EnumHandlerSourceMode(str, Enum):
 
     These represent the different strategies for discovering and loading
     handlers at runtime. The mode determines whether handlers come from
-    hardcoded registries, YAML contracts, or a combination of both.
+    hardcoded registries, YAML contracts, Kafka events, or a combination.
 
     Attributes:
         BOOTSTRAP: Only use hardcoded bootstrap handlers.
@@ -62,11 +68,19 @@ class EnumHandlerSourceMode(str, Enum):
             - Core handlers in bootstrap, extensions in contracts
             - Development environments with mixed configurations
             - A/B testing of handler implementations
+        KAFKA_EVENTS: Cache-only Kafka-based contract discovery.
+            Subscribes to platform-reserved contract topics (baseline-wired)
+            and maintains an in-memory cache of discovered handlers. Does NOT
+            wire business subscriptions dynamically. Use cases:
+            - Distributed contract discovery via event bus
+            - Dynamic contract registration/deregistration via Kafka
+            - Beta: discover + next restart applies model
     """
 
     BOOTSTRAP = "bootstrap"
     CONTRACT = "contract"
     HYBRID = "hybrid"
+    KAFKA_EVENTS = "kafka_events"
 
 
 __all__ = ["EnumHandlerSourceMode"]

omnibase_infra/errors/__init__.py

@@ -22,6 +22,7 @@ Exports:
     EventBusRegistryError: Event bus registry operation errors
     ChainPropagationError: Correlation/causation chain validation errors
     ArchitectureViolationError: Architecture validation errors (blocks startup)
+    BindingResolutionError: Binding resolution errors (declarative operation bindings)
 
 Correlation ID Assignment:
     All infrastructure errors support correlation_id for distributed tracing.
@@ -90,6 +91,7 @@ Error Sanitization Guidelines:
 from omnibase_infra.errors.error_architecture_violation import (
     ArchitectureViolationError,
 )
+from omnibase_infra.errors.error_binding_resolution import BindingResolutionError
 from omnibase_infra.errors.error_chain_propagation import ChainPropagationError
 from omnibase_infra.errors.error_compute_registry import ComputeRegistryError
 from omnibase_infra.errors.error_consul import InfraConsulError
@@ -125,6 +127,8 @@ from omnibase_infra.models.errors.model_timeout_error_context import (
 __all__: list[str] = [
     # Architecture validation errors
     "ArchitectureViolationError",
+    # Binding resolution errors
+    "BindingResolutionError",
     "ChainPropagationError",
     "ComputeRegistryError",
     "ContainerValidationError",

omnibase_infra/errors/error_binding_resolution.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Binding Resolution Error for declarative operation bindings.
+
+This module defines the error raised when binding resolution fails during
+declarative operation processing. Bindings use ${source.path} expressions
+to extract values from envelopes, payloads, or context.
+"""
+
+from uuid import UUID
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class BindingResolutionError(RuntimeHostError):
+    """Error when binding resolution fails.
+
+    Raised when a required binding cannot be resolved from the envelope,
+    payload, or context. Includes full diagnostic context for debugging.
+
+    This error is typically raised during declarative operation processing
+    when a ${source.path} expression cannot be resolved because:
+    - The source (payload, envelope, context) is missing
+    - A path segment does not exist in the source
+    - The value is required but None
+
+    Attributes:
+        operation_name: The operation being resolved (e.g., "db.query")
+        parameter_name: The parameter that failed (e.g., "sql")
+        expression: The ${source.path} expression that failed (e.g., "${payload.sql}")
+        missing_segment: Which path segment was not found (if applicable)
+        binding_correlation_id: Request correlation for tracing (stored separately from context)
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="binding_resolution",
+        ...     target_name="db.query",
+        ... )
+        >>> raise BindingResolutionError(
+        ...     "Required parameter 'sql' could not be resolved",
+        ...     operation_name="db.query",
+        ...     parameter_name="sql",
+        ...     expression="${payload.sql}",
+        ...     missing_segment="sql",
+        ...     context=context,
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation_name: str,
+        parameter_name: str,
+        expression: str,
+        missing_segment: str | None = None,
+        correlation_id: UUID | None = None,
+        context: ModelInfraErrorContext | None = None,
+    ) -> None:
+        """Initialize binding resolution error.
+
+        Args:
+            message: Human-readable error description
+            operation_name: Operation being resolved (e.g., "db.query")
+            parameter_name: Parameter that failed (e.g., "sql")
+            expression: Original expression (e.g., "${payload.sql}")
+            missing_segment: Path segment not found (e.g., "sql")
+            correlation_id: Request correlation ID (used if context not provided)
+            context: Infrastructure error context (preferred over correlation_id)
+        """
+        self.operation_name = operation_name
+        self.parameter_name = parameter_name
+        self.expression = expression
+        self.missing_segment = missing_segment
+        # Store binding-specific correlation_id separately
+        self.binding_correlation_id = correlation_id
+
+        # Build context if not provided
+        if context is None:
+            context = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="binding_resolution",
+                target_name=operation_name,
+            )
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.INVALID_INPUT,
+            context=context,
+            operation_name=operation_name,
+            parameter_name=parameter_name,
+            expression=expression,
+            missing_segment=missing_segment,
+        )
+
+    def __str__(self) -> str:
+        """Return detailed error message with diagnostic info.
+
+        Provides a structured diagnostic message that includes all relevant
+        context for debugging binding resolution failures.
+
+        Returns:
+            Pipe-delimited string with operation, parameter, expression,
+            and optionally missing segment and correlation ID.
+        """
+        parts = [
+            f"Binding resolution failed for operation '{self.operation_name}'",
+            f"Parameter: {self.parameter_name}",
+            f"Expression: {self.expression}",
+        ]
+        if self.missing_segment:
+            parts.append(f"Missing segment: {self.missing_segment}")
+        # Include correlation_id from context (model attribute, always present after __init__)
+        if hasattr(self, "model") and self.model.correlation_id:
+            parts.append(f"Correlation ID: {self.model.correlation_id}")
+        elif self.binding_correlation_id:
+            parts.append(f"Correlation ID: {self.binding_correlation_id}")
+        return " | ".join(parts)
+
+
+__all__ = ["BindingResolutionError"]

omnibase_infra/event_bus/configs/kafka_event_bus_config.yaml

@@ -36,8 +36,6 @@
 bootstrap_servers: "${KAFKA_BOOTSTRAP_SERVERS:-localhost:9092}"
 # Environment identifier for message routing (e.g., "local", "dev", "staging", "prod")
 environment: "${KAFKA_ENVIRONMENT:-local}"
-# Consumer group identifier for message routing
-group: "${KAFKA_GROUP:-default}"
 # =============================================================================
 # Timeout and Retry Settings
 # =============================================================================

omnibase_infra/event_bus/event_bus_inmemory.py

@@ -18,14 +18,23 @@ Features:
 Usage:
     ```python
     from omnibase_infra.event_bus.event_bus_inmemory import EventBusInmemory
+    from omnibase_infra.models import ModelNodeIdentity
 
     bus = EventBusInmemory(environment="dev", group="test")
     await bus.start()
 
+    # Create node identity for consumer group derivation
+    identity = ModelNodeIdentity(
+        env="dev",
+        service="my-service",
+        node_name="event-processor",
+        version="v1",
+    )
+
     # Subscribe to a topic
     async def handler(msg):
         print(f"Received: {msg.value}")
-    unsubscribe = await bus.subscribe("events", "group1", handler)
+    unsubscribe = await bus.subscribe("events", identity, handler)
 
     # Publish a message
     await bus.publish("events", b"key", b"value")
@@ -50,13 +59,15 @@ from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 from uuid import uuid4
 
-from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.enums import EnumConsumerGroupPurpose, EnumInfraTransportType
 from omnibase_infra.errors import (
     InfraUnavailableError,
     ModelInfraErrorContext,
     ProtocolConfigurationError,
 )
 from omnibase_infra.event_bus.models import ModelEventHeaders, ModelEventMessage
+from omnibase_infra.models import ModelNodeIdentity
+from omnibase_infra.utils import compute_consumer_group_id
 
 logger = logging.getLogger(__name__)
 
@@ -97,13 +108,23 @@ class EventBusInmemory:
 
     Example:
         ```python
+        from omnibase_infra.models import ModelNodeIdentity
+
         bus = EventBusInmemory(environment="dev", group="test")
         await bus.start()
 
+        # Create node identity for consumer group derivation
+        identity = ModelNodeIdentity(
+            env="dev",
+            service="my-service",
+            node_name="event-processor",
+            version="v1",
+        )
+
         # Subscribe
         async def handler(msg):
             print(f"Received: {msg.value}")
-        unsubscribe = await bus.subscribe("events", "group1", handler)
+        unsubscribe = await bus.subscribe("events", identity, handler)
 
         # Publish
         await bus.publish("events", b"key", b"value")
@@ -445,47 +466,80 @@ class EventBusInmemory:
     async def subscribe(
         self,
         topic: str,
-        group_id: str,
+        node_identity: ModelNodeIdentity,
         on_message: Callable[[ModelEventMessage], Awaitable[None]],
+        *,
+        purpose: EnumConsumerGroupPurpose = EnumConsumerGroupPurpose.CONSUME,
     ) -> Callable[[], Awaitable[None]]:
         """Subscribe to topic with callback handler.
 
         Registers a callback to be invoked for each message published to the topic.
         Returns an unsubscribe function to remove the subscription.
 
+        The consumer group ID is derived from the node identity using the canonical
+        format: ``{env}.{service}.{node_name}.{purpose}.{version}``.
+
+        Note: For the in-memory implementation, the consumer group ID is used for
+        internal tracking and circuit breaker isolation, but does not affect actual
+        message delivery semantics (all subscribers receive all messages).
+
         Args:
             topic: Topic to subscribe to
-            group_id: Consumer group identifier for this subscription
+            node_identity: Node identity used to derive the consumer group ID.
+                Contains env, service, node_name, and version components.
             on_message: Async callback invoked for each message
+            purpose: Consumer group purpose classification. Defaults to CONSUME.
+                Used in the consumer group ID derivation for disambiguation.
 
         Returns:
             Async unsubscribe function to remove this subscription
 
         Example:
             ```python
+            from omnibase_infra.models import ModelNodeIdentity
+            from omnibase_infra.enums import EnumConsumerGroupPurpose
+
+            identity = ModelNodeIdentity(
+                env="dev",
+                service="my-service",
+                node_name="event-processor",
+                version="v1",
+            )
+
             async def handler(msg):
                 print(f"Received: {msg.value}")
 
-            unsubscribe = await bus.subscribe("events", "group1", handler)
+            # Standard subscription (group_id: dev.my-service.event-processor.consume.v1)
+            unsubscribe = await bus.subscribe("events", identity, handler)
+
+            # With explicit purpose
+            unsubscribe = await bus.subscribe(
+                "events", identity, handler,
+                purpose=EnumConsumerGroupPurpose.INTROSPECTION,
+            )
+
             # ... later ...
             await unsubscribe()
             ```
         """
+        # Derive consumer group ID from node identity (no overrides allowed)
+        effective_group_id = compute_consumer_group_id(node_identity, purpose)
+
         async with self._lock:
-            self._subscribers[topic].append((group_id, on_message))
+            self._subscribers[topic].append((effective_group_id, on_message))
             logger.debug(
                 "Subscriber added",
-                extra={"topic": topic, "group_id": group_id},
+                extra={"topic": topic, "group_id": effective_group_id},
             )
 
         async def unsubscribe() -> None:
             """Remove this subscription from the topic."""
             async with self._lock:
                 try:
-                    self._subscribers[topic].remove((group_id, on_message))
+                    self._subscribers[topic].remove((effective_group_id, on_message))
                     logger.debug(
                         "Subscriber removed",
-                        extra={"topic": topic, "group_id": group_id},
+                        extra={"topic": topic, "group_id": effective_group_id},
                     )
                 except ValueError:
                     # Already unsubscribed