omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_ledger_write_effect/models/model_ledger_entry.py

@@ -0,0 +1,92 @@
+"""Ledger entry model for event ledger storage.
+
+This module defines the data structure for a single event ledger entry,
+representing one row in the event_ledger table.
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelLedgerEntry(BaseModel):
+    """Represents a single event ledger entry (one row in event_ledger table).
+
+    This model captures the complete state of an event as it was received
+    from Kafka, including the raw payload, Kafka position metadata, and
+    extracted envelope fields for queryability.
+
+    All extracted metadata fields are nullable because:
+    1. Events may not conform to the ONEX envelope schema
+    2. Malformed events should still be ledgered for debugging
+    3. Legacy events may lack certain fields
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    ledger_entry_id: UUID = Field(
+        ...,
+        description="Unique identifier for this ledger entry",
+    )
+
+    # Kafka position - uniquely identifies the event in the stream
+    topic: str = Field(
+        ...,
+        min_length=1,
+        description="Kafka topic from which the event was consumed",
+    )
+    partition: int = Field(
+        ...,
+        ge=0,
+        description="Kafka partition number",
+    )
+    kafka_offset: int = Field(
+        ...,
+        ge=0,
+        description="Kafka offset within the partition",
+    )
+
+    # Raw event data (base64 encoded for transport)
+    event_key: str | None = Field(
+        default=None,
+        description="Base64-encoded Kafka message key, if present",
+    )
+    event_value: str = Field(
+        ...,
+        description="Base64-encoded Kafka message value (the event payload)",
+    )
+    onex_headers: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="ONEX-specific headers extracted from Kafka headers",
+    )
+
+    # Extracted metadata (ALL NULLABLE for schema flexibility)
+    envelope_id: UUID | None = Field(
+        default=None,
+        description="Extracted envelope ID from the event, if present",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Extracted correlation ID for request tracing",
+    )
+    event_type: str | None = Field(
+        default=None,
+        description="Extracted event type identifier",
+    )
+    source: str | None = Field(
+        default=None,
+        description="Extracted source system or service identifier",
+    )
+
+    # Timestamps
+    event_timestamp: datetime | None = Field(
+        default=None,
+        description="Original event timestamp from the envelope, if present",
+    )
+    ledger_written_at: datetime = Field(
+        ...,
+        description="Timestamp when this entry was written to the ledger",
+    )

omnibase_infra/nodes/node_ledger_write_effect/models/model_ledger_query.py

@@ -0,0 +1,53 @@
+"""Ledger query model for searching ledger entries.
+
+This module defines the query parameters for ledger search operations.
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLedgerQuery(BaseModel):
+    """Query parameters for ledger searches.
+
+    All filter fields are optional - omitting a field means no filtering
+    on that dimension. Multiple filters are combined with AND logic.
+
+    The limit and offset fields enable pagination through large result sets.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Filter by correlation ID for request tracing",
+    )
+    event_type: str | None = Field(
+        default=None,
+        description="Filter by event type identifier",
+    )
+    topic: str | None = Field(
+        default=None,
+        description="Filter by Kafka topic",
+    )
+    start_time: datetime | None = Field(
+        default=None,
+        description="Filter events at or after this timestamp",
+    )
+    end_time: datetime | None = Field(
+        default=None,
+        description="Filter events before this timestamp",
+    )
+    limit: int = Field(
+        default=100,
+        ge=1,
+        le=10000,
+        description="Maximum number of entries to return",
+    )
+    offset: int = Field(
+        default=0,
+        ge=0,
+        description="Number of entries to skip for pagination",
+    )

omnibase_infra/nodes/node_ledger_write_effect/models/model_ledger_query_result.py

@@ -0,0 +1,41 @@
+"""Ledger query result model for search responses.
+
+This module defines the result structure returned by ledger search operations.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.nodes.node_ledger_write_effect.models.model_ledger_entry import (
+    ModelLedgerEntry,
+)
+from omnibase_infra.nodes.node_ledger_write_effect.models.model_ledger_query import (
+    ModelLedgerQuery,
+)
+
+
+class ModelLedgerQueryResult(BaseModel):
+    """Result of a ledger query operation.
+
+    Contains the matching entries along with pagination metadata
+    and the original query for reference.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    entries: list[ModelLedgerEntry] = Field(
+        ...,
+        description="List of matching ledger entries",
+    )
+    total_count: int = Field(
+        ...,
+        ge=0,
+        description="Total number of entries matching the query (before pagination)",
+    )
+    has_more: bool = Field(
+        ...,
+        description="True if more entries exist beyond the current page",
+    )
+    query: ModelLedgerQuery = Field(
+        ...,
+        description="The query parameters used to generate this result",
+    )

omnibase_infra/nodes/node_ledger_write_effect/node.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Ledger Write Effect - Capability-oriented event ledger write node.
+
+This effect node provides event ledger write capabilities using PostgreSQL.
+Named by capability ("ledger.write"), not by vendor (e.g., PostgreSQL).
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom storage logic - all behavior from handler
+    - Lightweight shell that delegates to handler implementation
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for external I/O operations.
+All storage logic is 100% driven by handler implementations, not Python code.
+
+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
+
+Design Decisions:
+    - 100% Contract-Driven: All capabilities in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: Handler wired externally
+    - Capability-Oriented: Named by what it does, not what it uses
+
+Related:
+    - contract.yaml: Capability definitions and IO operations
+    - models/: Input, output models (ModelPayloadLedgerAppend, ModelLedgerAppendResult)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_effect import NodeEffect
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+
+class NodeLedgerWriteEffect(NodeEffect):
+    """Effect node for event ledger write operations.
+
+    Capability: ledger.write
+
+    Provides a capability-oriented interface for event ledger operations.
+    Uses PostgreSQL for storing events in an append-only audit ledger with
+    idempotent write support via (topic, partition, kafka_offset) constraint.
+
+    This node is declarative - all behavior is defined in contract.yaml and
+    implemented through the handler. No custom storage logic exists in this class.
+
+    The audit ledger serves as the system's source of truth for all events.
+    Events are never dropped - even malformed events are captured with raw
+    data intact for later analysis or re-processing.
+
+    Attributes:
+        container: ONEX dependency injection container
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> container = ModelONEXContainer()
+        >>> node = NodeLedgerWriteEffect(container)
+        >>> # Handler must be wired externally via registry
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the ledger write effect node.
+
+        Args:
+            container: ONEX dependency injection container for resolving
+                dependencies defined in contract.yaml.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeLedgerWriteEffect"]

omnibase_infra/nodes/node_ledger_write_effect/protocols/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Protocols for event ledger persistence operations.
+
+This package defines the protocol interfaces for ledger persistence,
+enabling duck typing and testability for handlers.
+"""
+
+from omnibase_infra.nodes.node_ledger_write_effect.protocols.protocol_ledger_persistence import (
+    ProtocolLedgerPersistence,
+)
+
+__all__ = ["ProtocolLedgerPersistence"]

omnibase_infra/nodes/node_ledger_write_effect/protocols/protocol_ledger_persistence.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Protocol definition for event ledger persistence operations.
+
+This module defines the ProtocolLedgerPersistence interface for ledger
+storage and retrieval operations. Handlers implementing this protocol
+can be used interchangeably for testing and production.
+
+Design Decisions:
+    - runtime_checkable: Enables isinstance() checks for duck typing
+    - Async methods: All operations are async for non-blocking I/O
+    - Typed models: Uses Pydantic models for type safety
+    - Nullable metadata: Query filters are optional (None = no filter)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.node_ledger_write_effect.models import (
+        ModelLedgerAppendResult,
+        ModelLedgerEntry,
+    )
+    from omnibase_infra.nodes.reducers.models import ModelPayloadLedgerAppend
+
+
+@runtime_checkable
+class ProtocolLedgerPersistence(Protocol):
+    """Protocol for event ledger persistence operations.
+
+    This protocol defines the interface for appending events to the audit
+    ledger and querying events by various criteria. Implementations must
+    provide idempotent append operations via the (topic, partition, kafka_offset)
+    unique constraint.
+
+    Implementations:
+        - HandlerLedgerAppend: Production handler composing with HandlerDb
+        - MockLedgerPersistence: Test double for unit testing
+
+    Example:
+        >>> async def process_events(
+        ...     persistence: ProtocolLedgerPersistence,
+        ...     payload: ModelPayloadLedgerAppend,
+        ... ) -> ModelLedgerAppendResult:
+        ...     return await persistence.append(payload)
+    """
+
+    async def append(
+        self,
+        payload: ModelPayloadLedgerAppend,
+    ) -> ModelLedgerAppendResult:
+        """Append an event to the audit ledger with idempotent write support.
+
+        Uses INSERT ... ON CONFLICT DO NOTHING with the (topic, partition, kafka_offset)
+        unique constraint. Duplicate events are detected without raising errors.
+
+        Args:
+            payload: Event payload containing Kafka position and event data.
+                The payload includes base64-encoded event_key and event_value
+                which are decoded to BYTEA for storage.
+
+        Returns:
+            ModelLedgerAppendResult with:
+                - success: True if operation completed without error
+                - ledger_entry_id: UUID of created entry, None if duplicate
+                - duplicate: True if ON CONFLICT was triggered
+
+        Raises:
+            InfraConnectionError: If database connection fails
+            InfraTimeoutError: If operation times out
+        """
+        ...
+
+    async def query_by_correlation_id(
+        self,
+        correlation_id: UUID,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[ModelLedgerEntry]:
+        """Query ledger entries by correlation ID for distributed tracing.
+
+        Args:
+            correlation_id: The correlation ID to search for.
+            limit: Maximum number of entries to return (default: 100).
+            offset: Number of entries to skip for pagination (default: 0).
+
+        Returns:
+            List of ModelLedgerEntry matching the correlation ID,
+            ordered by event_timestamp descending.
+        """
+        ...
+
+    async def query_by_time_range(
+        self,
+        start: datetime,
+        end: datetime,
+        correlation_id: UUID | None = None,
+        event_type: str | None = None,
+        topic: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[ModelLedgerEntry]:
+        """Query ledger entries within a time range.
+
+        Uses COALESCE(event_timestamp, ledger_written_at) for consistent
+        ordering even when event_timestamp is NULL.
+
+        Args:
+            start: Start of time range (inclusive).
+            end: End of time range (exclusive).
+            correlation_id: Correlation ID for distributed tracing (auto-generated if None).
+            event_type: Optional filter by event type.
+            topic: Optional filter by Kafka topic.
+            limit: Maximum number of entries to return (default: 100, max: 10000).
+            offset: Number of entries to skip for pagination (default: 0).
+
+        Returns:
+            List of ModelLedgerEntry within the time range,
+            ordered by timestamp descending.
+        """
+        ...
+
+
+__all__ = ["ProtocolLedgerPersistence"]

omnibase_infra/nodes/node_ledger_write_effect/registry/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for event ledger write effect node."""
+
+from omnibase_infra.nodes.node_ledger_write_effect.registry.registry_infra_ledger_write import (
+    RegistryInfraLedgerWrite,
+)
+
+__all__ = ["RegistryInfraLedgerWrite"]

omnibase_infra/nodes/node_ledger_write_effect/registry/registry_infra_ledger_write.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for event ledger write effect node components.
+
+This registry exports all public symbols for the node_ledger_write_effect node,
+providing a single import point for consumers of this node.
+
+Exported Components:
+    - NodeLedgerWriteEffect: The declarative effect node
+    - HandlerLedgerAppend: Handler for idempotent append operations
+    - HandlerLedgerQuery: Handler for query operations
+    - ProtocolLedgerPersistence: Protocol for ledger persistence
+    - Models: Data models for ledger operations
+
+Example:
+    >>> from omnibase_infra.nodes.node_ledger_write_effect.registry import (
+    ...     RegistryInfraLedgerWrite,
+    ... )
+    >>> # Access all components via registry
+    >>> node_cls = RegistryInfraLedgerWrite.node
+    >>> append_handler = RegistryInfraLedgerWrite.handler_append
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Handlers
+from omnibase_infra.nodes.node_ledger_write_effect.handlers import (
+    HandlerLedgerAppend,
+    HandlerLedgerQuery,
+)
+
+# Models
+from omnibase_infra.nodes.node_ledger_write_effect.models import (
+    ModelLedgerAppendResult,
+    ModelLedgerEntry,
+    ModelLedgerQuery,
+    ModelLedgerQueryResult,
+)
+
+# Node
+from omnibase_infra.nodes.node_ledger_write_effect.node import NodeLedgerWriteEffect
+
+# Protocol
+from omnibase_infra.nodes.node_ledger_write_effect.protocols import (
+    ProtocolLedgerPersistence,
+)
+
+# Intent payload model (from reducers)
+from omnibase_infra.nodes.reducers.models import ModelPayloadLedgerAppend
+
+
+class RegistryInfraLedgerWrite:
+    """Registry providing access to all ledger write effect node components.
+
+    This class provides a centralized access point for all components of the
+    node_ledger_write_effect node. Use this registry for dependency injection
+    and container registration.
+
+    Class Attributes:
+        node: The NodeLedgerWriteEffect class
+        handler_append: The HandlerLedgerAppend class
+        handler_query: The HandlerLedgerQuery class
+        protocol: The ProtocolLedgerPersistence protocol
+        models: Tuple of all model classes
+
+    Example:
+        >>> from omnibase_infra.nodes.node_ledger_write_effect.registry import (
+        ...     RegistryInfraLedgerWrite,
+        ... )
+        >>> # Create node instance
+        >>> node = RegistryInfraLedgerWrite.node(container)
+        >>> # Create handlers
+        >>> append_handler = RegistryInfraLedgerWrite.handler_append(container, db_handler)
+    """
+
+    # Node
+    node = NodeLedgerWriteEffect
+
+    # Handlers
+    handler_append = HandlerLedgerAppend
+    handler_query = HandlerLedgerQuery
+
+    # Protocol
+    protocol = ProtocolLedgerPersistence
+
+    # Models (as tuple for iteration)
+    models = (
+        ModelLedgerAppendResult,
+        ModelLedgerEntry,
+        ModelLedgerQuery,
+        ModelLedgerQueryResult,
+        ModelPayloadLedgerAppend,
+    )
+
+    # Individual model references
+    model_append_result = ModelLedgerAppendResult
+    model_entry = ModelLedgerEntry
+    model_query = ModelLedgerQuery
+    model_query_result = ModelLedgerQueryResult
+    model_payload_append = ModelPayloadLedgerAppend
+
+
+# Re-export all components at module level for convenience
+__all__ = [
+    "RegistryInfraLedgerWrite",
+    # Node
+    "NodeLedgerWriteEffect",
+    # Handlers
+    "HandlerLedgerAppend",
+    "HandlerLedgerQuery",
+    # Protocol
+    "ProtocolLedgerPersistence",
+    # Models
+    "ModelLedgerAppendResult",
+    "ModelLedgerEntry",
+    "ModelLedgerQuery",
+    "ModelLedgerQueryResult",
+    "ModelPayloadLedgerAppend",
+]