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

omnibase_infra/topics/platform_topic_suffixes.py

@@ -0,0 +1,140 @@
+"""Platform-reserved topic suffixes for ONEX infrastructure.
+
+WARNING: These are platform-reserved suffixes. Domain services must NOT
+import from this module. Domain topics should be defined in domain contracts.
+
+Topic Suffix Format:
+    onex.<kind>.<producer>.<event-name>.v<version>
+
+    Structure:
+        - onex: Required prefix for all ONEX topics
+        - kind: Message category (evt, cmd, intent, snapshot, dlq)
+        - producer: Service/module that produces the message
+        - event-name: Descriptive name using kebab-case
+        - version: Semantic version (v1, v2, etc.)
+
+    Kinds:
+        evt - Event topics (state changes, notifications)
+        cmd - Command topics (requests for action)
+        intent - Intent topics (internal workflow coordination)
+        snapshot - Snapshot topics (periodic state snapshots)
+        dlq - Dead letter queue topics
+
+    Examples:
+        onex.evt.platform.node-registration.v1
+        onex.cmd.platform.request-introspection.v1
+        onex.intent.platform.runtime-tick.v1
+
+Usage:
+    from omnibase_infra.topics import SUFFIX_NODE_REGISTRATION
+
+    # Compose full topic with tenant/namespace prefix
+    full_topic = f"{tenant}.{namespace}.{SUFFIX_NODE_REGISTRATION}"
+
+See Also:
+    omnibase_core.validation.validate_topic_suffix - Validation function
+    omnibase_core.validation.compose_full_topic - Topic composition utility
+"""
+
+from omnibase_core.errors import OnexError
+from omnibase_core.validation import validate_topic_suffix
+
+# =============================================================================
+# PLATFORM-RESERVED TOPIC SUFFIXES
+# =============================================================================
+
+# Node lifecycle events
+SUFFIX_NODE_REGISTRATION: str = "onex.evt.platform.node-registration.v1"
+"""Topic suffix for node registration events.
+
+Published when a node registers with the runtime. Contains node metadata,
+capabilities, and health check configuration.
+"""
+
+SUFFIX_NODE_INTROSPECTION: str = "onex.evt.platform.node-introspection.v1"
+"""Topic suffix for node introspection events.
+
+Published when a node responds to an introspection request. Contains node
+capabilities, supported operations, and current state.
+"""
+
+SUFFIX_NODE_HEARTBEAT: str = "onex.evt.platform.node-heartbeat.v1"
+"""Topic suffix for node heartbeat events.
+
+Published periodically by nodes to indicate liveness. Contains timestamp,
+resource usage metrics, and health status.
+"""
+
+# Command topics
+SUFFIX_REQUEST_INTROSPECTION: str = "onex.cmd.platform.request-introspection.v1"
+"""Topic suffix for introspection request commands.
+
+Published to request introspection from a specific node or all nodes.
+Nodes respond on the SUFFIX_NODE_INTROSPECTION topic.
+"""
+
+# FSM and state management
+SUFFIX_FSM_STATE_TRANSITIONS: str = "onex.evt.platform.fsm-state-transitions.v1"
+"""Topic suffix for FSM state transition events.
+
+Published when a node's finite state machine transitions between states.
+Contains previous state, new state, trigger event, and transition metadata.
+"""
+
+# Runtime coordination
+SUFFIX_RUNTIME_TICK: str = "onex.intent.platform.runtime-tick.v1"
+"""Topic suffix for runtime tick intents.
+
+Internal topic for runtime orchestration. Triggers periodic tasks like
+heartbeat collection, health checks, and scheduled workflows.
+"""
+
+# Registration snapshots
+SUFFIX_REGISTRATION_SNAPSHOTS: str = "onex.snapshot.platform.registration-snapshots.v1"
+"""Topic suffix for registration snapshot events.
+
+Published periodically with aggregated registration state. Used for
+dashboard displays and monitoring systems.
+"""
+
+# =============================================================================
+# AGGREGATE TUPLE
+# =============================================================================
+
+ALL_PLATFORM_SUFFIXES: tuple[str, ...] = (
+    SUFFIX_NODE_REGISTRATION,
+    SUFFIX_NODE_INTROSPECTION,
+    SUFFIX_NODE_HEARTBEAT,
+    SUFFIX_REQUEST_INTROSPECTION,
+    SUFFIX_FSM_STATE_TRANSITIONS,
+    SUFFIX_RUNTIME_TICK,
+    SUFFIX_REGISTRATION_SNAPSHOTS,
+)
+"""Complete tuple of all platform-reserved topic suffixes.
+
+Use this tuple for:
+    - Validating that domain topics don't conflict with platform topics
+    - Iterating over all platform topics for subscription setup
+    - Documentation and discovery
+"""
+
+# =============================================================================
+# IMPORT-TIME VALIDATION
+# =============================================================================
+
+
+def _validate_all_suffixes() -> None:
+    """Validate all suffixes at import time to fail fast on invalid format.
+
+    Raises:
+        OnexError: If any suffix fails validation with details about which
+            suffix failed and why.
+    """
+    for suffix in ALL_PLATFORM_SUFFIXES:
+        result = validate_topic_suffix(suffix)
+        if not result.is_valid:
+            raise OnexError(f"Invalid platform topic suffix '{suffix}': {result.error}")
+
+
+# Run validation at import time
+_validate_all_suffixes()

omnibase_infra/topics/util_topic_composition.py

@@ -0,0 +1,95 @@
+"""Topic composition utilities for ONEX infrastructure.
+
+IMPORTANT: build_full_topic() is the ONLY supported way to compose
+Kafka topics in omnibase_infra. Direct string concatenation is prohibited.
+"""
+
+from omnibase_core.errors import OnexError
+from omnibase_core.validation import validate_topic_suffix
+from omnibase_core.validation.validator_topic_suffix import ENV_PREFIXES
+
+MAX_NAMESPACE_LENGTH = 100
+"""Maximum allowed namespace length.
+
+Kafka topics have a 249 character limit. With env prefix (~10 chars),
+separators (2 dots), and suffix (~50 chars), namespace should be limited
+to ensure total topic length stays within bounds.
+"""
+
+
+class TopicCompositionError(OnexError):
+    """Raised when topic composition fails due to invalid components.
+
+    Extends OnexError to follow ONEX error handling conventions.
+    """
+
+
+def build_full_topic(env: str, namespace: str, suffix: str) -> str:
+    """Build full topic from components with validation.
+
+    Args:
+        env: Environment prefix (e.g., "dev", "staging", "prod", "test", "local")
+        namespace: Namespace/tenant identifier (e.g., "omnibase", "myapp", "tenant-123")
+        suffix: Validated topic suffix (e.g., "onex.evt.platform.node-introspection.v1")
+
+    Returns:
+        Full topic string: {env}.{namespace}.{suffix}
+
+    Raises:
+        TopicCompositionError: If env is not a valid environment prefix
+        TopicCompositionError: If namespace is empty or contains invalid characters
+        TopicCompositionError: If suffix doesn't match ONEX topic format
+
+    Namespace Validation Rules:
+        - Must not be empty
+        - Allowed characters: alphanumeric (a-z, A-Z, 0-9), hyphens (-), underscores (_)
+        - Numeric-only namespaces ARE valid (e.g., "12345") to support numeric tenant IDs
+        - Invalid: spaces, dots, special characters
+
+    Example:
+        >>> build_full_topic("dev", "omnibase", "onex.evt.platform.node-introspection.v1")
+        'dev.omnibase.onex.evt.platform.node-introspection.v1'
+
+        >>> build_full_topic("prod", "myapp", "onex.cmd.platform.request-introspection.v1")
+        'prod.myapp.onex.cmd.platform.request-introspection.v1'
+    """
+    # Validate environment prefix
+    if env not in ENV_PREFIXES:
+        raise TopicCompositionError(
+            f"Invalid environment prefix '{env}'. "
+            f"Must be one of: {', '.join(sorted(ENV_PREFIXES))}"
+        )
+
+    # Validate namespace
+    # Allowed characters: alphanumeric (a-z, A-Z, 0-9), hyphens, underscores
+    # Note: Numeric-only namespaces (e.g., "12345") ARE valid because isalnum()
+    # returns True for digit-only strings. This is intentional to support
+    # numeric tenant/organization IDs as namespaces.
+    if not namespace:
+        raise TopicCompositionError("Namespace cannot be empty")
+    if len(namespace) > MAX_NAMESPACE_LENGTH:
+        raise TopicCompositionError(
+            f"Namespace exceeds maximum length of {MAX_NAMESPACE_LENGTH} characters. "
+            f"Got {len(namespace)} characters."
+        )
+    if not namespace.replace("-", "").replace("_", "").isalnum():
+        raise TopicCompositionError(
+            f"Invalid namespace '{namespace}'. "
+            "Must contain only alphanumeric characters, hyphens, and underscores"
+        )
+
+    # Enforce lowercase to ensure composed topics are valid
+    # (ONEX topic suffixes are lowercase, so namespaces should match)
+    if namespace != namespace.lower():
+        raise TopicCompositionError(
+            f"Namespace must be lowercase: '{namespace}'. "
+            "Use lowercase to ensure consistent topic naming."
+        )
+
+    # Validate suffix using omnibase_core validation
+    result = validate_topic_suffix(suffix)
+    if not result.is_valid:
+        raise TopicCompositionError(f"Invalid topic suffix '{suffix}': {result.error}")
+
+    # Compose full topic
+    return f"{env}.{namespace}.{suffix}"

omnibase_infra/types/typed_dict/__init__.py

@@ -7,10 +7,14 @@ forms of Pydantic models, enabling proper type checking for cache operations
 and JSON serialization/deserialization without requiring type: ignore comments.
 
 Available TypedDicts:
+    - TypedDictEnvelopeBuildParams: Parameters for building ModelEventEnvelope
     - TypedDictIntrospectionCache: JSON-serialized ModelNodeIntrospectionEvent
     - TypedDictPerformanceMetricsCache: JSON-serialized introspection performance metrics
 """
 
+from omnibase_infra.types.typed_dict.typed_dict_envelope_build_params import (
+    TypedDictEnvelopeBuildParams,
+)
 from omnibase_infra.types.typed_dict.typed_dict_introspection_cache import (
     TypedDictIntrospectionCache,
 )
@@ -18,4 +22,8 @@ from omnibase_infra.types.typed_dict.typed_dict_performance_metrics_cache import
     TypedDictPerformanceMetricsCache,
 )
 
-__all__ = ["TypedDictIntrospectionCache", "TypedDictPerformanceMetricsCache"]
+__all__ = [
+    "TypedDictEnvelopeBuildParams",
+    "TypedDictIntrospectionCache",
+    "TypedDictPerformanceMetricsCache",
+]

omnibase_infra/types/typed_dict/typed_dict_envelope_build_params.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definition for envelope build parameters.
+
+This module provides a TypedDict that represents the parameters passed to the
+_build_envelope method in AdapterProtocolEventPublisherInmemory, replacing the
+loose dict[str, object] typing with proper type safety.
+
+The TypedDictEnvelopeBuildParams ensures type-checked access to envelope
+construction parameters without requiring type: ignore comments or unsafe casts.
+
+Key Features:
+    - Full type annotations for all envelope build parameters
+    - Proper handling of nullable fields (correlation_id, causation_id, metadata)
+    - Integration with JsonType for payload typing
+    - Uses TYPE_CHECKING import for ContextValue to avoid circular imports
+
+Usage:
+    This TypedDict is primarily used for:
+    - Type-safe parameter passing to envelope builder methods
+    - Eliminating dict[str, object] loose typing
+    - Enabling mypy verification of parameter access
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictEnvelopeBuildParams
+
+    def build_envelope(params: TypedDictEnvelopeBuildParams) -> ModelEventEnvelope:
+        # Type-safe access to all fields
+        event_type = params["event_type"]
+        payload = params["payload"]
+        correlation_id = params.get("correlation_id")
+        return ...
+    ```
+
+See Also:
+    - AdapterProtocolEventPublisherInmemory: Primary consumer of this TypedDict
+    - ModelEventEnvelope: Target envelope model constructed from these params
+    - ProtocolEventPublisher: SPI protocol defining publish interface
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+from omnibase_core.types import JsonType
+
+if TYPE_CHECKING:
+    from omnibase_spi.protocols.types.protocol_core_types import ContextValue
+
+__all__ = ["TypedDictEnvelopeBuildParams"]
+
+
+class TypedDictEnvelopeBuildParams(TypedDict):
+    """TypedDict representing parameters for building a ModelEventEnvelope.
+
+    This type provides a type-safe alternative to dict[str, object] for passing
+    envelope construction parameters. It enables proper type checking when
+    building event envelopes in publisher adapters.
+
+    Required fields (event_type, payload) are enforced by TypedDict's default
+    total=True behavior. Optional fields use NotRequired[] to allow omission
+    while maintaining type safety.
+
+    Attributes:
+        event_type: Fully-qualified event type identifier
+            (e.g., "omninode.user.event.created.v1"). Required field - must
+            always be provided when constructing the TypedDict.
+        payload: Event payload data as JSON-compatible types. Required field -
+            must always be provided. Can be dict, list, str, int, float, bool,
+            or None.
+        correlation_id: Optional correlation ID for request tracing.
+            Used to link related events across service boundaries.
+            May be omitted or set to None.
+        causation_id: Optional causation ID for event sourcing chains.
+            Links this event to the event that caused it.
+            May be omitted or set to None.
+        metadata: Optional additional context values for the envelope.
+            Keys are string identifiers, values are ContextValue protocol
+            implementations (e.g., ProtocolContextStringValue).
+            May be omitted or set to None.
+
+    Note:
+        The metadata field uses ContextValue from omnibase_spi which is imported
+        under TYPE_CHECKING to avoid runtime circular import issues. At runtime,
+        the dict values are duck-typed protocol implementations.
+
+    Example:
+        ```python
+        # Minimal valid TypedDict (only required fields)
+        params: TypedDictEnvelopeBuildParams = {
+            "event_type": "user.created.v1",
+            "payload": {"user_id": "123", "email": "user@example.com"},
+        }
+
+        # Full TypedDict with all fields
+        params_full: TypedDictEnvelopeBuildParams = {
+            "event_type": "user.created.v1",
+            "payload": {"user_id": "123", "email": "user@example.com"},
+            "correlation_id": "corr-abc-123",
+            "causation_id": None,
+            "metadata": {"trace_id": trace_value},
+        }
+
+        # Safe field access
+        event_type: str = params["event_type"]  # Always present
+        correlation_id: str | None = params.get("correlation_id")  # May be absent
+        ```
+    """
+
+    event_type: str
+    payload: JsonType
+    correlation_id: NotRequired[str | None]
+    causation_id: NotRequired[str | None]
+    metadata: NotRequired[dict[str, ContextValue] | None]

omnibase_infra/utils/__init__.py

@@ -5,6 +5,7 @@
 This package provides common utilities used across the infrastructure:
     - correlation: Correlation ID generation and propagation for distributed tracing
     - util_atomic_file: Atomic file write primitives using temp-file-rename pattern
+    - util_consumer_group: Kafka consumer group ID generation with deterministic hashing
     - util_datetime: Datetime validation and timezone normalization
     - util_db_transaction: Database transaction context manager for asyncpg
     - util_dsn_validation: PostgreSQL DSN validation and sanitization
@@ -26,6 +27,11 @@ from omnibase_infra.utils.util_atomic_file import (
     write_atomic_bytes,
     write_atomic_bytes_async,
 )
+from omnibase_infra.utils.util_consumer_group import (
+    KAFKA_CONSUMER_GROUP_MAX_LENGTH,
+    compute_consumer_group_id,
+    normalize_kafka_identifier,
+)
 from omnibase_infra.utils.util_datetime import (
     ensure_timezone_aware,
     is_timezone_aware,
@@ -72,15 +78,18 @@ from omnibase_infra.utils.util_semver import (
 
 __all__: list[str] = [
     "CorrelationContext",
+    "KAFKA_CONSUMER_GROUP_MAX_LENGTH",
     "OptimisticConflictError",
     "SAFE_ERROR_PATTERNS",
     "SEMVER_PATTERN",
     "SENSITIVE_PATTERNS",
     "clear_correlation_id",
+    "compute_consumer_group_id",
     "ensure_timezone_aware",
     "generate_correlation_id",
     "get_correlation_id",
     "is_timezone_aware",
+    "normalize_kafka_identifier",
     "parse_and_validate_dsn",
     "parse_env_float",
     "parse_env_int",

omnibase_infra/utils/util_consumer_group.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Kafka consumer group ID utilities.
+
+Provides utilities for normalizing and validating Kafka consumer group identifiers.
+Kafka consumer group IDs have specific character and length constraints that this
+module helps enforce consistently across the codebase.
+
+Kafka Consumer Group ID Constraints:
+    - Maximum length: 255 characters
+    - Valid characters: alphanumeric, period (.), underscore (_), hyphen (-)
+    - Cannot be empty
+
+This module provides:
+    - normalize_kafka_identifier: Normalize strings for use as Kafka consumer group IDs
+    - compute_consumer_group_id: Compute canonical consumer group ID from node identity
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import TYPE_CHECKING
+
+from omnibase_infra.enums import EnumConsumerGroupPurpose
+
+if TYPE_CHECKING:
+    from omnibase_infra.models import ModelNodeIdentity
+
+# Maximum length for Kafka consumer group IDs
+KAFKA_CONSUMER_GROUP_MAX_LENGTH = 255
+
+# Pattern for invalid characters (anything not alphanumeric, period, underscore, or hyphen)
+_INVALID_CHAR_PATTERN = re.compile(r"[^a-z0-9._-]")
+
+# Pattern for consecutive separators (period, underscore, or hyphen)
+_CONSECUTIVE_SEPARATOR_PATTERN = re.compile(r"[._-]{2,}")
+
+# Pattern for leading/trailing separators
+_EDGE_SEPARATOR_PATTERN = re.compile(r"^[._-]+|[._-]+$")
+
+
+def normalize_kafka_identifier(value: str) -> str:
+    """Normalize a string for use as a Kafka consumer group ID.
+
+    Applies the following transformations in order:
+        1. Convert to lowercase
+        2. Replace invalid characters (non-alphanumeric, non-separator) with underscore
+        3. Collapse consecutive separators (., _, -) into a single separator
+        4. Strip leading and trailing separators
+        5. Truncate to max length (255) with hash suffix if necessary
+
+    The hash suffix ensures uniqueness when truncation is required. The suffix
+    format is `_<8-char-hash>` appended after truncating to fit within 255 chars.
+
+    Args:
+        value: The input string to normalize.
+
+    Returns:
+        A normalized string safe for use as a Kafka consumer group ID.
+
+    Raises:
+        ValueError: If the input is empty or results in an empty string after
+            normalization.
+
+    Example:
+        >>> normalize_kafka_identifier("My Service!!")
+        'my_service'
+        >>> normalize_kafka_identifier("foo..bar__baz")
+        'foo.bar_baz'
+        >>> normalize_kafka_identifier("  UPPER_Case-Test  ")
+        'upper_case-test'
+        >>> normalize_kafka_identifier("valid.consumer-group_id")
+        'valid.consumer-group_id'
+        >>> normalize_kafka_identifier("@#$%^&*()")  # Raises ValueError
+        Traceback (most recent call last):
+            ...
+        ValueError: Input '@#$%^&*()' results in empty string after normalization
+    """
+    if not value:
+        raise ValueError("Kafka consumer group ID cannot be empty")
+
+    # Step 1: Lowercase
+    result = value.lower()
+
+    # Step 2: Replace invalid characters with underscore
+    result = _INVALID_CHAR_PATTERN.sub("_", result)
+
+    # Step 3: Collapse consecutive separators, preserving the first separator type
+    result = _CONSECUTIVE_SEPARATOR_PATTERN.sub(lambda m: m.group(0)[0], result)
+
+    # Step 4: Strip leading and trailing separators
+    result = _EDGE_SEPARATOR_PATTERN.sub("", result)
+
+    # Check for empty result after normalization
+    if not result:
+        raise ValueError(f"Input {value!r} results in empty string after normalization")
+
+    # Step 5: Truncate with hash suffix if exceeds max length
+    if len(result) > KAFKA_CONSUMER_GROUP_MAX_LENGTH:
+        # Generate 8-character hash suffix from original value for determinism
+        hash_suffix = hashlib.sha256(value.encode()).hexdigest()[:8]
+        # Reserve space for underscore + hash suffix (9 chars total)
+        max_prefix_length = KAFKA_CONSUMER_GROUP_MAX_LENGTH - 9
+        result = f"{result[:max_prefix_length]}_{hash_suffix}"
+
+    return result
+
+
+def compute_consumer_group_id(
+    identity: ModelNodeIdentity,
+    purpose: EnumConsumerGroupPurpose = EnumConsumerGroupPurpose.CONSUME,
+) -> str:
+    """Compute canonical Kafka consumer group ID from node identity.
+
+    Generates a deterministic, Kafka-compliant consumer group ID using the
+    canonical format: ``{env}.{service}.{node_name}.{purpose}.{version}``
+
+    Each component is normalized using ``normalize_kafka_identifier()`` to ensure
+    the result is safe for use as a Kafka consumer group ID. The final result
+    is validated against Kafka's 255 character limit.
+
+    Args:
+        identity: Node identity containing env, service, node_name, and version.
+        purpose: Consumer group purpose classification. Defaults to CONSUME.
+            The purpose determines consumer behavior semantics (e.g., offset
+            reset policy) and is included in the group ID for disambiguation.
+
+    Returns:
+        A canonical consumer group ID in the format:
+        ``{env}.{service}.{node_name}.{purpose}.{version}``
+
+        If the combined length exceeds Kafka's 255 character limit, the result
+        is truncated with an 8-character hash suffix to preserve uniqueness
+        while fitting within the constraint.
+
+    Example:
+        >>> from omnibase_infra.models import ModelNodeIdentity
+        >>> from omnibase_infra.enums import EnumConsumerGroupPurpose
+        >>> identity = ModelNodeIdentity(
+        ...     env="dev",
+        ...     service="omniintelligence",
+        ...     node_name="claude_hook_event_effect",
+        ...     version="v1",
+        ... )
+        >>> compute_consumer_group_id(identity)
+        'dev.omniintelligence.claude_hook_event_effect.consume.v1'
+
+        With a different purpose:
+
+        >>> compute_consumer_group_id(identity, EnumConsumerGroupPurpose.INTROSPECTION)
+        'dev.omniintelligence.claude_hook_event_effect.introspection.v1'
+
+        Component normalization is applied automatically:
+
+        >>> identity_mixed = ModelNodeIdentity(
+        ...     env="DEV",
+        ...     service="Omni Intelligence",
+        ...     node_name="claude-hook-event-effect",
+        ...     version="V1.0.0",
+        ... )
+        >>> compute_consumer_group_id(identity_mixed)
+        'dev.omni_intelligence.claude-hook-event-effect.consume.v1.0.0'
+
+        Long identities are automatically truncated with a hash suffix:
+
+        >>> long_identity = ModelNodeIdentity(
+        ...     env="development",
+        ...     service="a" * 100,
+        ...     node_name="b" * 100,
+        ...     version="v1",
+        ... )
+        >>> result = compute_consumer_group_id(long_identity)
+        >>> len(result) <= 255
+        True
+        >>> result.endswith("_" + result[-8:])  # Has hash suffix
+        True
+
+    Note:
+        The canonical format uses period (.) as the separator between components.
+        This enables hierarchical grouping and filtering in Kafka tooling while
+        maintaining compatibility with Kafka's consumer group ID constraints.
+
+    See Also:
+        - :func:`normalize_kafka_identifier`: Component normalization rules
+        - :class:`~omnibase_infra.enums.EnumConsumerGroupPurpose`: Purpose values
+        - :class:`~omnibase_infra.models.ModelNodeIdentity`: Identity model
+
+    .. versionadded:: 0.2.6
+        Created as part of OMN-1602.
+    """
+    # Normalize each component
+    normalized_env = normalize_kafka_identifier(identity.env)
+    normalized_service = normalize_kafka_identifier(identity.service)
+    normalized_node_name = normalize_kafka_identifier(identity.node_name)
+    normalized_purpose = normalize_kafka_identifier(purpose.value)
+    normalized_version = normalize_kafka_identifier(identity.version)
+
+    # Join with period separator
+    group_id = ".".join(
+        [
+            normalized_env,
+            normalized_service,
+            normalized_node_name,
+            normalized_purpose,
+            normalized_version,
+        ]
+    )
+
+    # Handle length constraint with truncation + hash (same strategy as normalize_kafka_identifier)
+    # This can occur when multiple long components combine, even though each was individually
+    # truncated to 255 chars by normalize_kafka_identifier.
+    if len(group_id) > KAFKA_CONSUMER_GROUP_MAX_LENGTH:
+        # Generate deterministic hash from original (pre-normalized) identity components
+        # to ensure the same identity always produces the same truncated group ID
+        hash_input = (
+            f"{identity.env}|{identity.service}|{identity.node_name}|"
+            f"{purpose.value}|{identity.version}"
+        )
+        hash_suffix = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
+        # Reserve space for underscore + hash suffix (9 chars total)
+        max_prefix_length = KAFKA_CONSUMER_GROUP_MAX_LENGTH - 9
+        group_id = f"{group_id[:max_prefix_length]}_{hash_suffix}"
+
+    return group_id
+
+
+__all__: list[str] = [
+    "KAFKA_CONSUMER_GROUP_MAX_LENGTH",
+    "compute_consumer_group_id",
+    "normalize_kafka_identifier",
+]

omnibase_infra/validation/infra_validators.py

@@ -429,7 +429,24 @@ INFRA_NODES_PATH = "src/omnibase_infra/nodes/"
 #                    ast.FunctionDef | ast.AsyncFunctionDef for AST method type checking
 # - 105 (2026-01-21): Contract-driven handler config loading (+4 unions)
 #                     ModelHandlerContract transport config fields and lifecycle types
-INFRA_MAX_UNIONS = 105
+# - 108 (2026-01-27): OMN-1518 declarative operation bindings (+3 unions)
+#                     ModelEventEnvelope[object] | dict[str, object] for materialized
+#                     envelopes in dispatch engine (3 occurrences in type aliases)
+# - 105 (2026-01-27): OMN-1518 simplify to always-dict envelope format (-3 unions)
+#                     Removed hybrid union types by always materializing to dict format
+#                     Dispatchers now receive consistent dict[str, object] with __bindings
+# - 112 (2026-01-27): OMN-1610 emit daemon for persistent Kafka connections (+7 unions)
+#                     BoundedEventQueue, EmitClient, EventRegistry return types
+# - 112 (2026-01-29): OMN-1610 emit daemon + refactor to strongly typed input model
+#                     BoundedEventQueue, EmitClient, EventRegistry, socket_permissions
+#                     Replaced dict unions with ModelEmitDaemonConfigInput
+# - 113 (2026-01-29): OMN-1610 properly typed daemon protocol models (+1 union)
+#                     Added ModelDaemonRequest, ModelDaemonResponse discriminated unions
+#                     Replaced dict[str, object] soup with strongly typed Pydantic models
+# - 115 (2026-01-29): OMN-1653 contract registry reducer (+2 unions)
+#                     ContractRegistryEvent: 4-type union for event routing
+#                     contract_yaml: dict | str for flexible YAML handling
+INFRA_MAX_UNIONS = 115
 
 # Maximum allowed architecture violations in infrastructure code.
 # Set to 0 (strict enforcement) to ensure one-model-per-file principle is always followed.