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

omnibase_infra/nodes/node_ledger_projection_compute/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Ledger Projection Compute - Platform event ledger projection node.
+
+This package provides the NodeLedgerProjectionCompute, a COMPUTE node that
+subscribes to 7 platform event topics for event ledger persistence.
+
+Core Purpose:
+    Projects events from the platform event bus into the audit ledger,
+    enabling complete traceability and debugging support across all
+    node lifecycle events, FSM transitions, and runtime coordination.
+
+Subscribed Topics:
+    - onex.evt.platform.node-registration.v1
+    - onex.evt.platform.node-introspection.v1
+    - onex.evt.platform.node-heartbeat.v1
+    - onex.cmd.platform.request-introspection.v1
+    - onex.evt.platform.fsm-state-transitions.v1
+    - onex.intent.platform.runtime-tick.v1
+    - onex.snapshot.platform.registration-snapshots.v1
+
+Consumer Configuration:
+    - consumer_purpose: "audit" (non-processing, read-only)
+    - auto_offset_reset: "earliest" (capture all historical events)
+
+Related Tickets:
+    - OMN-1648: Ledger Projection Compute Node
+
+Example:
+    >>> from omnibase_core.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_ledger_projection_compute import (
+    ...     NodeLedgerProjectionCompute,
+    ...     RegistryInfraLedgerProjection,
+    ... )
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = RegistryInfraLedgerProjection.create_node(container)
+"""
+
+from omnibase_infra.nodes.node_ledger_projection_compute.node import (
+    NodeLedgerProjectionCompute,
+)
+from omnibase_infra.nodes.node_ledger_projection_compute.registry import (
+    RegistryInfraLedgerProjection,
+)
+
+__all__ = [
+    "NodeLedgerProjectionCompute",
+    "RegistryInfraLedgerProjection",
+]

omnibase_infra/nodes/node_ledger_projection_compute/contract.yaml

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeLedgerProjectionCompute
+#
+# COMPUTE node that subscribes to 7 platform event topics for event ledger
+# persistence. This node projects events from the platform event bus into
+# the audit ledger for complete traceability and debugging support.
+#
+# The node subscribes with consumer_purpose="audit" and auto_offset_reset="earliest"
+# to ensure no events are missed and all historical events are captured.
+#
+# Related Tickets:
+#   - OMN-1646: Event Ledger Schema and Models
+#   - OMN-1647: Ledger Write Effect Node
+#   - OMN-1648: Ledger Projection Compute Node
+# Contract identifiers
+name: "node_ledger_projection_compute"
+contract_name: "node_ledger_projection_compute"
+node_name: "node_ledger_projection_compute"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "0.1.0"
+# Node type - COMPUTE for event projection logic
+node_type: "COMPUTE_GENERIC"
+# Description
+description: >
+  COMPUTE node that subscribes to 7 platform event topics for event ledger persistence. Projects events from the platform event bus into the audit ledger, enabling complete traceability and debugging support. Uses consumer_purpose="audit" to indicate non-processing read-only consumption and auto_offset_reset="earliest" to capture all historical events.
+
+# Event bus configuration
+event_bus:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  # Subscribe to all 7 platform event topics for complete audit coverage
+  subscribe_topics:
+    # Node lifecycle events
+    - "onex.evt.platform.node-registration.v1"
+    - "onex.evt.platform.node-introspection.v1"
+    - "onex.evt.platform.node-heartbeat.v1"
+    # Introspection commands
+    - "onex.cmd.platform.request-introspection.v1"
+    # FSM state tracking
+    - "onex.evt.platform.fsm-state-transitions.v1"
+    # Runtime coordination
+    - "onex.intent.platform.runtime-tick.v1"
+    # State snapshots
+    - "onex.snapshot.platform.registration-snapshots.v1"
+  # Audit consumer - read-only, non-processing consumption for ledger persistence
+  consumer_purpose: "audit"
+  # Start from earliest offset to capture all historical events
+  auto_offset_reset: "earliest"
+  # Consumer group for ledger projection
+  consumer_group: "onex-ledger-projection-compute"
+# Strongly typed I/O models
+input_model:
+  name: "ModelEventMessage"
+  module: "omnibase_infra.event_bus.models.model_event_message"
+  description: >
+    Kafka event message containing raw bytes payload and headers. The compute node processes events from all 7 subscribed topics.
+
+output_model:
+  name: "ModelPayloadLedgerAppend"
+  module: "omnibase_infra.nodes.reducers.models.model_payload_ledger_append"
+  description: >
+    Ledger append payload to be passed to NodeLedgerWriteEffect. Contains the event data with Kafka position for idempotent writes.
+
+# Capabilities provided by this node
+capabilities:
+  - name: "ledger.projection"
+    description: "Project platform events into the audit ledger"
+    version: "0.1.0"
+  - name: "ledger.projection.multi_topic"
+    description: "Subscribe to multiple platform topics for comprehensive event capture"
+  - name: "ledger.projection.audit"
+    description: "Non-processing, read-only event consumption for audit purposes"
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "node_ledger_write_effect"
+    type: "node"
+    class_name: "NodeLedgerWriteEffect"
+    module: "omnibase_infra.nodes.node_ledger_write_effect"
+    description: "Effect node for writing events to the PostgreSQL audit ledger"
+  - name: "protocol_event_envelope"
+    type: "protocol"
+    description: "Protocol for parsing and handling event envelopes"
+    optional: false
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2026-01-29"
+  ticket: "OMN-1648"
+  tags:
+    - compute
+    - ledger
+    - audit
+    - projection
+    - multi-topic
+    - platform-events

omnibase_infra/nodes/node_ledger_projection_compute/node.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""NodeLedgerProjectionCompute - Extracts metadata from platform events for ledger persistence.
+
+This COMPUTE node transforms ModelEventMessage into ModelPayloadLedgerAppend wrapped
+in a ModelIntent for the Effect layer. It follows the ONEX declarative pattern:
+    - DECLARATIVE node driven by contract.yaml
+    - Subscribes to 7 platform topics via contract configuration
+    - Transforms events to ledger append intents
+
+Design Rationale - Best-Effort Metadata Extraction:
+    The audit ledger serves as the system's source of truth. Events must NEVER
+    be dropped due to metadata extraction failures. All metadata fields are
+    extracted best-effort - parsing errors result in None/empty values, not
+    exceptions. Only a missing event_value (the raw bytes) causes an error.
+
+Bytes Encoding:
+    Kafka event keys and values are bytes. Since bytes cannot safely cross
+    intent boundaries (serialization issues), they are base64-encoded at this
+    transform layer. The Effect layer decodes before storage.
+
+Subscribed Topics:
+    - onex.evt.platform.node-registration.v1
+    - onex.evt.platform.node-introspection.v1
+    - onex.evt.platform.node-heartbeat.v1
+    - onex.cmd.platform.request-introspection.v1
+    - onex.evt.platform.fsm-state-transitions.v1
+    - onex.intent.platform.runtime-tick.v1
+    - onex.snapshot.platform.registration-snapshots.v1
+
+Ticket: OMN-1648
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import TYPE_CHECKING
+
+from omnibase_core.errors import OnexError
+from omnibase_core.models.reducer.model_intent import ModelIntent
+from omnibase_core.nodes.node_compute import NodeCompute
+from omnibase_core.types import JsonType
+from omnibase_infra.event_bus.models.model_event_headers import ModelEventHeaders
+from omnibase_infra.event_bus.models.model_event_message import ModelEventMessage
+from omnibase_infra.nodes.reducers.models.model_payload_ledger_append import (
+    ModelPayloadLedgerAppend,
+)
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from omnibase_core.container import ModelONEXContainer
+
+logger = logging.getLogger(__name__)
+
+
+class NodeLedgerProjectionCompute(NodeCompute):
+    """COMPUTE node that extracts metadata from platform events for ledger persistence.
+
+    Declarative node - subscribes to 7 platform topics via contract.yaml.
+    Transforms ModelEventMessage -> ModelPayloadLedgerAppend -> ModelIntent.
+
+    This node implements the ONEX ledger projection pattern:
+    1. Receives raw Kafka events as ModelEventMessage
+    2. Extracts metadata best-effort (never fails on parse errors)
+    3. Base64-encodes bytes for safe intent serialization
+    4. Emits ModelIntent with "ledger.append" payload for Effect layer
+
+    CRITICAL INVARIANTS:
+    - NEVER drop events due to metadata extraction failure
+    - event_value is REQUIRED (raises OnexError if None)
+    - correlation_id and other metadata are OPTIONAL
+    - Best-effort extraction - parsing errors yield None, not exceptions
+
+    Attributes:
+        container: ONEX dependency injection container.
+
+    Example:
+        ```python
+        from omnibase_core.container import ModelONEXContainer
+
+        container = ModelONEXContainer()
+        node = NodeLedgerProjectionCompute(container)
+
+        # Transform event to ledger intent
+        message = ModelEventMessage(
+            topic="agent.routing.completed.v1",
+            value=b'{"agent": "code-quality"}',
+            headers=headers,
+            partition=0,
+            offset="42",
+        )
+        intent = node.compute(message)
+        # intent.payload.intent_type == "ledger.append"
+        ```
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the ledger projection compute node.
+
+        Args:
+            container: ONEX dependency injection container.
+        """
+        super().__init__(container)
+
+    def compute(self, message: ModelEventMessage) -> ModelIntent:
+        """Transform event message to ledger append intent.
+
+        Extracts metadata from the incoming Kafka event and produces a
+        ModelIntent with a ModelPayloadLedgerAppend payload for the Effect
+        layer to persist to PostgreSQL.
+
+        Args:
+            message: The incoming Kafka event message to transform.
+
+        Returns:
+            ModelIntent with intent_type="extension" containing the ledger
+            append payload for the Effect layer.
+
+        Raises:
+            OnexError: If message.value is None (event body is required).
+
+        INVARIANTS:
+        - Never drop events due to metadata extraction failure
+        - event_value is REQUIRED (raises OnexError if None)
+        - correlation_id is optional
+        """
+        payload = self._extract_ledger_metadata(message)
+        return ModelIntent(
+            intent_type="extension",
+            target=f"postgres://event_ledger/{payload.topic}/{payload.partition}/{payload.kafka_offset}",
+            payload=payload,
+        )
+
+    def _b64(self, b: bytes | None) -> str | None:
+        """Base64 encode bytes, returning None for None input.
+
+        Args:
+            b: Bytes to encode, or None.
+
+        Returns:
+            Base64-encoded string, or None if input was None.
+        """
+        if b is None:
+            return None
+        return base64.b64encode(b).decode("ascii")
+
+    def _normalize_headers(
+        self, headers: ModelEventHeaders | None
+    ) -> dict[str, JsonType]:
+        """Convert event headers to JSON-safe dictionary.
+
+        Uses Pydantic's model_dump with mode="json" to ensure all values
+        are JSON-serializable. Returns empty dict for None input.
+
+        Args:
+            headers: Event headers model, or None.
+
+        Returns:
+            JSON-safe dictionary of header values, or empty dict.
+        """
+        if headers is None:
+            return {}
+        try:
+            return headers.model_dump(mode="json")
+        except Exception:
+            # Best-effort: try to get correlation_id for logging context
+            correlation_id = getattr(headers, "correlation_id", None)
+            logger.warning(
+                "Failed to serialize event headers, returning empty dict. "
+                "correlation_id=%s",
+                correlation_id,
+                exc_info=True,
+            )
+            return {}
+
+    def _parse_offset(
+        self, offset: str | None, correlation_id: UUID | None = None
+    ) -> int:
+        """Parse Kafka offset string to integer.
+
+        Args:
+            offset: Offset string from Kafka, or None.
+            correlation_id: Optional correlation ID for logging context.
+
+        Returns:
+            Parsed offset as integer, or 0 if None or unparseable.
+        """
+        if offset is None:
+            return 0
+        try:
+            return int(offset)
+        except (ValueError, TypeError):
+            logger.warning(
+                "Failed to parse offset '%s' as integer, defaulting to 0. "
+                "correlation_id=%s",
+                offset,
+                correlation_id,
+            )
+            return 0
+
+    def _extract_ledger_metadata(
+        self, message: ModelEventMessage
+    ) -> ModelPayloadLedgerAppend:
+        """Extract ledger metadata from event message.
+
+        Main extraction logic that transforms a ModelEventMessage into a
+        ModelPayloadLedgerAppend. Uses best-effort extraction for all
+        metadata fields - only event_value being None causes an error.
+
+        Args:
+            message: The event message to extract metadata from.
+
+        Returns:
+            Populated ledger append payload ready for the Effect layer.
+
+        Raises:
+            OnexError: If message.value is None.
+
+        Field Mapping:
+            | Payload Field    | Source                          | Required |
+            |------------------|---------------------------------|----------|
+            | topic            | message.topic                   | YES      |
+            | partition        | message.partition               | YES*     |
+            | kafka_offset     | message.offset                  | YES*     |
+            | event_key        | base64(message.key)             | NO       |
+            | event_value      | base64(message.value)           | YES      |
+            | correlation_id   | message.headers.correlation_id  | NO       |
+            | event_type       | message.headers.event_type      | NO       |
+            | source           | message.headers.source          | NO       |
+            | envelope_id      | message.headers.message_id      | NO       |
+            | event_timestamp  | message.headers.timestamp       | NO       |
+            | onex_headers     | headers.model_dump(mode="json") | NO       |
+
+            * Defaults to 0 if not available (for consumed messages, these
+              should always be present, but we handle None defensively).
+        """
+        # CRITICAL: event_value is required - this is the only case where we raise
+        if message.value is None:
+            raise OnexError(
+                "Cannot create ledger entry: message.value is None. "
+                "Event body is required for audit ledger persistence."
+            )
+
+        # Base64 encode the raw bytes
+        event_value_b64 = self._b64(message.value)
+        # Defensive check - _b64 should never return None for non-None input
+        if event_value_b64 is None:
+            raise OnexError(
+                "Unexpected: base64 encoding of message.value returned None. "
+                "This should never happen for non-None bytes input."
+            )
+
+        event_key_b64 = self._b64(message.key)
+
+        # Extract headers best-effort
+        headers = message.headers
+        # Extract correlation_id early for logging context in helper methods
+        correlation_id = headers.correlation_id if headers else None
+        onex_headers = self._normalize_headers(headers)
+
+        # Build payload with best-effort metadata extraction
+        return ModelPayloadLedgerAppend(
+            # Required Kafka position fields (defensive defaults for None)
+            topic=message.topic,
+            partition=message.partition if message.partition is not None else 0,
+            kafka_offset=self._parse_offset(
+                message.offset, correlation_id=correlation_id
+            ),
+            # Raw event data as base64
+            event_key=event_key_b64,
+            event_value=event_value_b64,
+            # Extracted metadata (all optional, best-effort)
+            onex_headers=onex_headers,
+            correlation_id=correlation_id,
+            envelope_id=headers.message_id if headers else None,
+            event_type=headers.event_type if headers else None,
+            source=headers.source if headers else None,
+            event_timestamp=headers.timestamp if headers else None,
+        )
+
+
+__all__ = ["NodeLedgerProjectionCompute"]

omnibase_infra/nodes/node_ledger_projection_compute/registry/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry module for NodeLedgerProjectionCompute.
+
+This module provides the RegistryInfraLedgerProjection class for
+dependency injection registration and factory methods.
+
+Usage:
+    ```python
+    from omnibase_infra.nodes.node_ledger_projection_compute.registry import (
+        RegistryInfraLedgerProjection,
+    )
+
+    # Get node class for DI resolution
+    node_class = RegistryInfraLedgerProjection.get_node_class()
+
+    # Create node instance
+    node = RegistryInfraLedgerProjection.create_node(container)
+    ```
+
+Related Tickets:
+    - OMN-1648: Ledger Projection Compute Node
+"""
+
+from omnibase_infra.nodes.node_ledger_projection_compute.registry.registry_infra_ledger_projection import (
+    RegistryInfraLedgerProjection,
+)
+
+__all__ = ["RegistryInfraLedgerProjection"]

omnibase_infra/nodes/node_ledger_projection_compute/registry/registry_infra_ledger_projection.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for NodeLedgerProjectionCompute - DI bindings and exports.
+
+This registry provides factory methods and dependency injection bindings for
+the NodeLedgerProjectionCompute. It follows the ONEX registry pattern with
+the naming convention ``RegistryInfra<NodeName>``.
+
+Node Purpose:
+    NodeLedgerProjectionCompute is a COMPUTE node that transforms platform
+    events (ModelEventMessage) into ledger append intents (ModelPayloadLedgerAppend)
+    for persistence by the Effect layer.
+
+Usage:
+    ```python
+    from omnibase_infra.nodes.node_ledger_projection_compute.registry import (
+        RegistryInfraLedgerProjection,
+    )
+
+    # Get the node class for DI resolution
+    node_class = RegistryInfraLedgerProjection.get_node_class()
+
+    # Create node instance with container
+    from omnibase_core.container import ModelONEXContainer
+    container = ModelONEXContainer()
+    node = RegistryInfraLedgerProjection.create_node(container)
+    ```
+
+Related Tickets:
+    - OMN-1648: Ledger Projection Compute Node
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_infra.nodes.node_ledger_projection_compute.node import (
+    NodeLedgerProjectionCompute,
+)
+
+if TYPE_CHECKING:
+    from omnibase_core.container import ModelONEXContainer
+
+
+class RegistryInfraLedgerProjection:
+    """DI registry for ledger projection compute node.
+
+    Provides factory methods and bindings for the NodeLedgerProjectionCompute.
+    This registry follows the ONEX registry pattern for infrastructure nodes.
+
+    Why a Registry Class?
+        ONEX convention requires registry classes (not modules) for:
+        - Centralized factory methods for node creation
+        - Type-safe DI resolution via get_node_class()
+        - Extensibility for subclassing specialized registries
+        - Consistent interface across all node registries
+
+    Example:
+        ```python
+        from omnibase_core.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_ledger_projection_compute.registry import (
+            RegistryInfraLedgerProjection,
+        )
+
+        container = ModelONEXContainer()
+        node = RegistryInfraLedgerProjection.create_node(container)
+        intent = node.compute(event_message)
+        ```
+    """
+
+    @staticmethod
+    def get_node_class() -> type[NodeLedgerProjectionCompute]:
+        """Return the node class for DI resolution.
+
+        This method enables DI containers to resolve the node class type
+        without importing the node module directly, supporting lazy loading
+        and circular import prevention.
+
+        Returns:
+            The NodeLedgerProjectionCompute class type.
+
+        Example:
+            ```python
+            node_class = RegistryInfraLedgerProjection.get_node_class()
+            assert node_class is NodeLedgerProjectionCompute
+            ```
+        """
+        return NodeLedgerProjectionCompute
+
+    @staticmethod
+    def create_node(container: ModelONEXContainer) -> NodeLedgerProjectionCompute:
+        """Create a NodeLedgerProjectionCompute instance with the given container.
+
+        Factory method for creating properly-configured node instances.
+        Prefer this method over direct instantiation for consistency
+        and future extensibility.
+
+        Args:
+            container: ONEX dependency injection container.
+
+        Returns:
+            Configured NodeLedgerProjectionCompute instance.
+
+        Example:
+            ```python
+            from omnibase_core.container import ModelONEXContainer
+
+            container = ModelONEXContainer()
+            node = RegistryInfraLedgerProjection.create_node(container)
+            ```
+        """
+        return NodeLedgerProjectionCompute(container)
+
+
+__all__ = [
+    "NodeLedgerProjectionCompute",
+    "RegistryInfraLedgerProjection",
+]

omnibase_infra/nodes/node_ledger_write_effect/__init__.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Ledger Write Effect - Capability-oriented event ledger write node.
+
+This package provides the NodeLedgerWriteEffect, a capability-oriented
+effect node for event ledger write operations using PostgreSQL.
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+    Named by capability (ledger.write), not by specific backend implementation.
+    Uses PostgreSQL for append-only event ledger storage with idempotent writes.
+
+Capabilities:
+    - ledger.write: Append events to the audit ledger
+    - ledger.query: Query events from the audit ledger
+
+Event Topics:
+    Consumed:
+        - {env}.{namespace}.onex.cmd.ledger-append.v1
+        - {env}.{namespace}.onex.cmd.ledger-query.v1
+    Published:
+        - {env}.{namespace}.onex.evt.ledger-appended.v1
+        - {env}.{namespace}.onex.evt.ledger-query-result.v1
+
+Available Exports:
+    - NodeLedgerWriteEffect: The declarative effect node
+    - ModelLedgerEntry: Single ledger entry representing one event
+    - ModelLedgerAppendResult: Result of a ledger write operation
+    - ModelLedgerQuery: Query parameters for ledger searches
+    - ModelLedgerQueryResult: Result of a ledger query operation
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_ledger_write_effect import (
+    ...     NodeLedgerWriteEffect,
+    ...     ModelLedgerEntry,
+    ...     ModelLedgerAppendResult,
+    ... )
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeLedgerWriteEffect(container)
+
+Related Modules:
+    - models: Pydantic models for ledger operations
+    - registry: Dependency injection registration
+"""
+
+from omnibase_infra.nodes.node_ledger_write_effect.handlers import (
+    HandlerLedgerAppend,
+    HandlerLedgerQuery,
+)
+from omnibase_infra.nodes.node_ledger_write_effect.models import (
+    ModelLedgerAppendResult,
+    ModelLedgerEntry,
+    ModelLedgerQuery,
+    ModelLedgerQueryResult,
+)
+from omnibase_infra.nodes.node_ledger_write_effect.node import NodeLedgerWriteEffect
+from omnibase_infra.nodes.node_ledger_write_effect.protocols import (
+    ProtocolLedgerPersistence,
+)
+from omnibase_infra.nodes.node_ledger_write_effect.registry import (
+    RegistryInfraLedgerWrite,
+)
+
+__all__ = [
+    # Node
+    "NodeLedgerWriteEffect",
+    # Handlers
+    "HandlerLedgerAppend",
+    "HandlerLedgerQuery",
+    # Protocol
+    "ProtocolLedgerPersistence",
+    # Registry
+    "RegistryInfraLedgerWrite",
+    # Models
+    "ModelLedgerAppendResult",
+    "ModelLedgerEntry",
+    "ModelLedgerQuery",
+    "ModelLedgerQueryResult",
+]