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

omnibase_infra/nodes/reducers/models/model_payload_ledger_append.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Ledger append payload model for audit ledger reducer.
+
+This payload implements ProtocolIntentPayload for use with ModelIntent.
+It captures Kafka events for append-only audit ledger storage with
+metadata extraction best-effort (nullable metadata ensures events are
+never dropped due to parsing failures).
+
+Design Rationale - Nullable Metadata:
+    The audit ledger serves as the system's source of truth. Events must NEVER
+    be dropped due to metadata extraction failures. By making all metadata fields
+    nullable, we guarantee:
+    1. Malformed events are captured with raw data intact
+    2. Parsing errors don't cause event loss
+    3. Metadata can be re-extracted later from raw event_value
+    4. The ledger remains complete even during schema evolution
+
+Bytes Encoding:
+    Kafka event keys and values are bytes. Since bytes cannot safely cross
+    intent boundaries (serialization issues), they are base64-encoded at the
+    boundary. The Effect layer decodes before storage.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+# NOTE: ModelIntentPayloadBase was removed in omnibase_core 0.6.2
+# Using pydantic.BaseModel directly as the base class
+
+
+class ModelPayloadLedgerAppend(BaseModel):
+    """Payload for audit ledger append intents.
+
+    This payload follows the ONEX intent payload pattern for use with ModelIntent.
+    All metadata fields are intentionally OPTIONAL to ensure the audit ledger
+    never drops events due to metadata extraction failures.
+
+    Attributes:
+        intent_type: Discriminator literal for intent routing. Always "ledger.append".
+        topic: Kafka topic the event originated from.
+        partition: Kafka partition number (idempotency key component).
+        kafka_offset: Kafka offset within partition (idempotency key component).
+        event_key: Base64-encoded event key bytes (None for keyless events).
+        event_value: Base64-encoded event value bytes (required - the raw event).
+        onex_headers: Extracted ONEX headers from Kafka message headers.
+        correlation_id: Correlation ID for distributed tracing (extracted, nullable).
+        envelope_id: Unique envelope identifier (extracted, nullable).
+        event_type: Event type discriminator (extracted, nullable).
+        source: Event source identifier (extracted, nullable).
+        event_timestamp: Event timestamp (extracted, nullable).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["ledger.append"] = Field(
+        default="ledger.append",
+        description="Discriminator literal for intent routing.",
+    )
+
+    # Kafka position - required for idempotency
+    topic: str = Field(
+        ...,
+        min_length=1,
+        description="Kafka topic the event originated from.",
+    )
+
+    partition: int = Field(
+        ...,
+        ge=0,
+        description="Kafka partition number (idempotency key component).",
+    )
+
+    kafka_offset: int = Field(
+        ...,
+        ge=0,
+        description="Kafka offset within partition (idempotency key component).",
+    )
+
+    # Raw event data as base64 strings (bytes never cross intents)
+    event_key: str | None = Field(
+        default=None,
+        description="Base64-encoded event key bytes (None for keyless events).",
+    )
+
+    event_value: str = Field(
+        ...,
+        min_length=1,
+        description="Base64-encoded event value bytes (required - the raw event).",
+    )
+
+    onex_headers: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Extracted ONEX headers from Kafka message headers.",
+    )
+
+    # Extracted metadata - ALL OPTIONAL (audit ledger must never drop events)
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing (extracted, nullable).",
+    )
+
+    envelope_id: UUID | None = Field(
+        default=None,
+        description="Unique envelope identifier (extracted, nullable).",
+    )
+
+    event_type: str | None = Field(
+        default=None,
+        description="Event type discriminator (extracted, nullable).",
+    )
+
+    source: str | None = Field(
+        default=None,
+        description="Event source identifier (extracted, nullable).",
+    )
+
+    event_timestamp: datetime | None = Field(
+        default=None,
+        description="Event timestamp (extracted, nullable).",
+    )
+
+
+__all__ = [
+    "ModelPayloadLedgerAppend",
+]

omnibase_infra/nodes/reducers/registration_reducer.py

@@ -876,6 +876,7 @@ class RegistrationReducer:
             service_name=service_name,
             tags=tags,
             health_check=health_check,
+            event_bus_config=event.event_bus,  # Pass through from introspection event
         )
 
         # ModelIntent.payload expects ProtocolIntentPayload, which our model implements

omnibase_infra/protocols/__init__.py

@@ -8,6 +8,7 @@ components in the ONEX ecosystem.
 Protocols:
     - ProtocolCapabilityProjection: Interface for capability-based projection queries
     - ProtocolCapabilityQuery: Interface for capability-based node discovery service
+    - ProtocolDispatchEngine: Interface for message dispatch engines
     - ProtocolEventBusLike: Interface for event bus abstraction (used by introspection)
     - ProtocolIdempotencyStore: Interface for idempotency checking and deduplication
     - ProtocolMessageDispatcher: Interface for message dispatchers
@@ -63,6 +64,7 @@ from omnibase_infra.protocols.protocol_capability_projection import (
 )
 from omnibase_infra.protocols.protocol_capability_query import ProtocolCapabilityQuery
 from omnibase_infra.protocols.protocol_container_aware import ProtocolContainerAware
+from omnibase_infra.protocols.protocol_dispatch_engine import ProtocolDispatchEngine
 from omnibase_infra.protocols.protocol_event_bus_like import ProtocolEventBusLike
 from omnibase_infra.protocols.protocol_event_projector import ProtocolEventProjector
 from omnibase_infra.protocols.protocol_idempotency_store import (
@@ -90,6 +92,7 @@ __all__: list[str] = [
     "ProtocolEventBusLike",
     "ProtocolEventProjector",
     "ProtocolContainerAware",
+    "ProtocolDispatchEngine",
     "ProtocolIdempotencyStore",
     "ProtocolMessageDispatcher",
     "ProtocolMessageTypeRegistry",

omnibase_infra/protocols/protocol_dispatch_engine.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2025 OmniNode Team
+"""Protocol definition for dispatch engine interface.
+
+This module defines the ProtocolDispatchEngine interface for dispatch engines
+that route event envelopes to appropriate handlers based on topic. The primary
+implementation is MessageDispatchEngine in the runtime module.
+
+Architecture:
+    The dispatch engine sits between event bus consumption and handler execution:
+
+    Kafka/EventBus -> EventBusSubcontractWiring -> ProtocolDispatchEngine -> Handlers
+
+    The wiring layer uses this protocol for duck-typed dispatch engine injection,
+    enabling both production MessageDispatchEngine and test mocks.
+
+Thread Safety:
+    Implementations MUST be thread-safe for concurrent async dispatch calls.
+    Multiple coroutines may invoke dispatch() simultaneously from event bus
+    callbacks.
+
+    Design Requirements:
+        - Use asyncio.Lock for shared mutable state (e.g., routing tables)
+        - Dispatch operations should be stateless where possible
+        - Handler invocations may run concurrently
+
+Related:
+    - OMN-1621: Runtime consumes event_bus subcontract for contract-driven wiring
+    - EventBusSubcontractWiring: Uses this protocol for dispatch engine injection
+    - MessageDispatchEngine: Production implementation of this protocol
+
+.. versionadded:: 0.2.5
+"""
+
+from __future__ import annotations
+
+__all__ = ["ProtocolDispatchEngine"]
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+    from omnibase_infra.models.dispatch.model_dispatch_result import ModelDispatchResult
+
+
+@runtime_checkable
+class ProtocolDispatchEngine(Protocol):
+    """Protocol for dispatch engines that route event envelopes to handlers.
+
+    Dispatch engines are responsible for routing incoming event envelopes
+    to the appropriate handlers based on topic and message type. The protocol
+    enables duck-typed injection of dispatch engines into the event bus wiring
+    layer.
+
+    Protocol Verification:
+        Per ONEX conventions, protocol compliance is verified via duck typing
+        rather than isinstance checks:
+
+        .. code-block:: python
+
+            # Verify required method exists and is callable
+            if hasattr(engine, 'dispatch') and callable(engine.dispatch):
+                wiring = EventBusSubcontractWiring(
+                    event_bus=event_bus,
+                    dispatch_engine=engine,
+                    environment="dev",
+                )
+            else:
+                raise TypeError("Object does not implement ProtocolDispatchEngine")
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_infra.protocols import ProtocolDispatchEngine
+            from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
+
+            class MyDispatchEngine:
+                '''Custom dispatch engine implementation.'''
+
+                async def dispatch(
+                    self,
+                    topic: str,
+                    envelope: ModelEventEnvelope[object],
+                ) -> ModelDispatchResult | None:
+                    '''Dispatch envelope to appropriate handler.'''
+                    handler = self._resolve_handler(topic, envelope)
+                    return await handler.handle(envelope)
+
+            # Verify protocol compliance via duck typing
+            engine = MyDispatchEngine()
+            assert hasattr(engine, 'dispatch') and callable(engine.dispatch)
+
+    Note:
+        Method bodies in this Protocol use ``...`` (Ellipsis) rather than
+        ``raise NotImplementedError()``. This is the standard Python convention
+        for ``typing.Protocol`` classes per PEP 544.
+
+    .. versionadded:: 0.2.5
+    """
+
+    async def dispatch(
+        self,
+        topic: str,
+        envelope: ModelEventEnvelope[object],
+    ) -> ModelDispatchResult | None:
+        """Dispatch an event envelope to the appropriate handler(s).
+
+        Routes the envelope to handlers registered for the given topic.
+        The dispatch engine resolves handlers based on topic patterns,
+        message types, and other routing criteria.
+
+        Typing Note (ModelEventEnvelope[object]):
+            The envelope parameter uses ``ModelEventEnvelope[object]`` instead of
+            ``Any`` per CLAUDE.md guidance: "Use ``object`` for generic payloads".
+
+            This is intentional:
+            - CLAUDE.md mandates "NEVER use ``Any``" and specifies ``object`` for
+              generic payloads that can accept multiple event types
+            - The dispatch engine handles envelopes from multiple topics with
+              different payload types
+            - Handler implementations use ``isinstance()`` type guards for
+              payload-specific processing
+
+        Thread Safety:
+            This method MUST be safe for concurrent calls from multiple
+            coroutines. The event bus wiring layer may dispatch messages
+            from multiple topic subscriptions concurrently.
+
+        Args:
+            topic: The full topic name from which the envelope was consumed.
+                Used for routing and logging context.
+                Example: "dev.onex.evt.node.introspected.v1"
+            envelope: The deserialized event envelope containing the payload.
+                The payload type varies by topic/event type.
+
+        Returns:
+            ModelDispatchResult if the implementation returns dispatch metrics/results,
+            None if the implementation does not track results. Callers should not
+            depend on the return value for correctness.
+
+        Raises:
+            InfraDispatchError: If no handler is registered for the topic/message type.
+            OnexError: For handler execution failures (implementation-specific).
+
+        Example:
+            .. code-block:: python
+
+                # Event bus wiring callback
+                async def on_message(message: ProtocolEventMessage) -> None:
+                    envelope = deserialize(message)
+                    await dispatch_engine.dispatch(topic, envelope)
+        """
+        ...

omnibase_infra/runtime/__init__.py

@@ -90,10 +90,13 @@ from omnibase_infra.runtime.service_kernel import load_runtime_config
 from omnibase_infra.runtime.service_kernel import main as kernel_main
 from omnibase_infra.runtime.service_message_dispatch_engine import MessageDispatchEngine
 from omnibase_infra.runtime.models import (
+    ModelContractLoadResult,
     ModelProjectorNotificationConfig,
+    ModelRuntimeContractConfig,
     ModelRuntimeSchedulerConfig,
     ModelRuntimeSchedulerMetrics,
     ModelRuntimeTick,
+    ModelSecurityConfig,
     ModelStateTransitionNotification,
     ModelTransitionNotificationPublisherMetrics,
 )
@@ -182,6 +185,16 @@ from omnibase_infra.runtime.protocol_handler_plugin_loader import (
     ProtocolHandlerPluginLoader,
 )
 
+# Binding expression resolver (OMN-1518)
+from omnibase_infra.runtime.binding_resolver import (
+    BindingExpressionParser,
+    OperationBindingResolver,
+    MAX_EXPRESSION_LENGTH,
+    MAX_PATH_SEGMENTS,
+    VALID_CONTEXT_PATHS,
+    VALID_SOURCES,
+)
+
 # Handler discovery protocol and implementation (OMN-1133)
 from omnibase_infra.runtime.protocol_handler_discovery import (
     ProtocolHandlerDiscovery,
@@ -221,6 +234,27 @@ from omnibase_infra.runtime.transition_notification_outbox import (
     TransitionNotificationOutbox,
 )
 
+# Topic-scoped publisher (OMN-1621)
+from omnibase_infra.runtime.publisher_topic_scoped import PublisherTopicScoped
+
+# Event bus subcontract wiring (OMN-1621)
+from omnibase_infra.runtime.event_bus_subcontract_wiring import (
+    EventBusSubcontractWiring,
+    load_event_bus_subcontract,
+)
+
+# Runtime contract config loader (OMN-1519)
+from omnibase_infra.runtime.runtime_contract_config_loader import (
+    RuntimeContractConfigLoader,
+)
+
+# Security constants (OMN-1519)
+from omnibase_infra.runtime.constants_security import (
+    ALLOW_NAMESPACE_OVERRIDE_ENV_VAR,
+    SECURITY_CONFIG_PATH_ENV_VAR,
+    TRUSTED_HANDLER_NAMESPACE_PREFIXES,
+)
+
 # Registry contract source (OMN-1100)
 from omnibase_infra.runtime.registry_contract_source import (
     DEFAULT_CONSUL_HOST,
@@ -235,6 +269,9 @@ from omnibase_infra.runtime.registry_contract_source import (
     store_contract_in_consul,
 )
 
+# Kafka contract source (OMN-1654)
+from omnibase_infra.runtime.kafka_contract_source import KafkaContractSource
+
 # Chain-aware dispatch (OMN-951) - must be imported LAST to avoid circular import
 from omnibase_infra.runtime.chain_aware_dispatch import (
     ChainAwareDispatcher,
@@ -266,9 +303,11 @@ __all__: list[str] = [
     "MessageDispatchEngine",
     # Message type registry (OMN-937)
     "MessageTypeRegistryError",
+    "ModelContractLoadResult",
     "ModelDomainConstraint",
     "ModelMessageTypeEntry",
     "ModelProjectorNotificationConfig",
+    "ModelRuntimeContractConfig",
     "ModelRuntimeSchedulerConfig",
     "ModelRuntimeSchedulerMetrics",
     "ModelRuntimeTick",
@@ -354,6 +393,13 @@ __all__: list[str] = [
     "load_handler_contract_config",
     # Binding config resolver (OMN-765)
     "BindingConfigResolver",
+    # Binding expression resolver (OMN-1518)
+    "BindingExpressionParser",
+    "OperationBindingResolver",
+    "MAX_EXPRESSION_LENGTH",
+    "MAX_PATH_SEGMENTS",
+    "VALID_CONTEXT_PATHS",
+    "VALID_SOURCES",
     # Handler discovery protocol and implementation (OMN-1133)
     "ContractHandlerDiscovery",
     "ProtocolHandlerDiscovery",
@@ -371,6 +417,18 @@ __all__: list[str] = [
     # Transition notification publisher and outbox (OMN-1139)
     "TransitionNotificationOutbox",
     "TransitionNotificationPublisher",
+    # Topic-scoped publisher (OMN-1621)
+    "PublisherTopicScoped",
+    # Event bus subcontract wiring (OMN-1621)
+    "EventBusSubcontractWiring",
+    "load_event_bus_subcontract",
+    # Runtime contract config loader (OMN-1519)
+    "RuntimeContractConfigLoader",
+    # Security constants and configuration (OMN-1519)
+    "ALLOW_NAMESPACE_OVERRIDE_ENV_VAR",
+    "ModelSecurityConfig",
+    "SECURITY_CONFIG_PATH_ENV_VAR",
+    "TRUSTED_HANDLER_NAMESPACE_PREFIXES",
     # Registry contract source (OMN-1100)
     "DEFAULT_CONSUL_HOST",
     "DEFAULT_CONSUL_PORT",
@@ -382,4 +440,6 @@ __all__: list[str] = [
     "delete_contract_from_consul",
     "list_contracts_in_consul",
     "store_contract_in_consul",
+    # Kafka contract source (OMN-1654)
+    "KafkaContractSource",
 ]