omnibase_infra 0.2.6__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/models/model_payload_postgres_upsert_registration.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL upsert registration payload model for registration reducer.
+
+This payload implements ProtocolIntentPayload for use with ModelIntent.
+It contains the same data as ModelPostgresUpsertRegistrationIntent but with an
+`intent_type` field instead of `kind` to satisfy the protocol.
+
+Related:
+    - ModelPostgresUpsertRegistrationIntent: Core intent model (uses `kind` discriminator)
+    - ProtocolIntentPayload: Protocol requiring `intent_type` property
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, SerializeAsAny
+
+# NOTE: ModelIntentPayloadBase was removed in omnibase_core 0.6.2
+# Using pydantic.BaseModel directly as the base class
+
+
+class ModelPayloadPostgresUpsertRegistration(BaseModel):
+    """Payload for PostgreSQL upsert registration intents.
+
+    This payload follows the ONEX intent payload pattern for use with ModelIntent.
+
+    Uses SerializeAsAny wrapper: the `record` field accepts any BaseModel subclass,
+    and serialization preserves all subclass fields via Pydantic's SerializeAsAny
+    type wrapper.
+
+    Attributes:
+        intent_type: Discriminator literal for intent routing. Always "postgres.upsert_registration".
+        correlation_id: Correlation ID for distributed tracing.
+        record: The registration record to upsert (uses SerializeAsAny for subclass preservation).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.upsert_registration"] = Field(
+        default="postgres.upsert_registration",
+        description="Discriminator literal for intent routing.",
+    )
+
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing.",
+    )
+
+    record: SerializeAsAny[BaseModel] = Field(
+        ...,
+        description="Registration record to upsert. Accepts any BaseModel subclass.",
+    )
+
+
+__all__ = [
+    "ModelPayloadPostgresUpsertRegistration",
+]

omnibase_infra/nodes/reducers/models/model_registration_confirmation.py

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration Confirmation Model for Phase 2 Implementation.
+
+This module provides ModelRegistrationConfirmation, the Pydantic model for
+confirmation events from the Effect layer. These events complete the dual
+registration workflow by confirming Consul and PostgreSQL operations.
+
+Phase Status:
+    This is a Phase 1 placeholder model. The model contract is defined here
+    to ensure Phase 2 implementation aligns with Phase 1 reducer expectations.
+
+    Phase 2 Implementation (OMN-996):
+        - Effect layer nodes (ConsulAdapter, PostgresAdapter) will publish
+          confirmation events using this model
+        - RegistrationReducer.reduce_confirmation() will process these events
+        - Runtime will route confirmations based on event_type
+
+Confirmation Event Flow:
+    1. Reducer emits intents (consul.register, postgres.upsert_registration)
+    2. Effect nodes execute intents and perform I/O
+    3. Effect nodes publish confirmation events to Kafka
+    4. Runtime routes confirmations to RegistrationReducer.reduce_confirmation()
+    5. Reducer updates state: pending -> partial -> complete (or -> failed)
+
+Event Types:
+    - consul.registered: Consul service registration completed
+    - postgres.registration_upserted: PostgreSQL record upsert completed
+
+    Both event types may indicate success or failure via the ``success`` field.
+    On failure, ``error_message`` provides diagnostic information (sanitized).
+
+State Transitions Triggered:
+    - success + consul.registered:
+        pending -> partial (if postgres pending)
+        partial -> complete (if postgres already confirmed)
+
+    - success + postgres.registration_upserted:
+        pending -> partial (if consul pending)
+        partial -> complete (if consul already confirmed)
+
+    - failure (any event_type):
+        pending -> failed
+        partial -> failed
+
+Related:
+    - RegistrationReducer: Pure reducer that consumes this model
+    - ModelRegistrationState: State model updated by confirmations
+    - DESIGN_TWO_WAY_REGISTRATION_ARCHITECTURE.md: Architecture design
+    - OMN-889: Infrastructure MVP - Dual Registration Reducer
+    - OMN-996: Implement Confirmation Event Handling (follow-up)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumConfirmationEventType
+
+
+class ModelRegistrationConfirmation(BaseModel):
+    """Confirmation event for dual registration operations.
+
+    This model represents confirmation events published by Effect layer nodes
+    (ConsulAdapter, PostgresAdapter) after executing registration intents.
+
+    Phase 1 Stub:
+        This model defines the contract for confirmation events that will be
+        processed in Phase 2 implementation by RegistrationReducer.reduce_confirmation().
+
+    Immutability:
+        This model uses frozen=True to ensure confirmation events are immutable
+        once created. This aligns with the immutable event sourcing pattern.
+
+    Serialization:
+        This model is designed for Kafka transport. Effect nodes serialize using
+        ``model_dump(mode="json")`` and the Runtime deserializes using
+        ``model_validate()``.
+
+    Security Note:
+        The ``error_message`` field should contain sanitized error information
+        only. Effect nodes must NOT include credentials, connection strings,
+        or other sensitive information in error messages. See CLAUDE.md
+        "Error Sanitization Guidelines" for details.
+
+    Attributes:
+        event_type: The type of confirmation event.
+            - "consul.registered": Consul service registration result
+            - "postgres.registration_upserted": PostgreSQL upsert result
+        correlation_id: UUID linking this confirmation to the original
+            introspection event. Used by the reducer to match confirmations
+            to pending registrations.
+        node_id: UUID of the node being registered. Used for validation
+            to ensure confirmation matches the expected node.
+        success: Whether the registration operation succeeded.
+            - True: Operation completed successfully
+            - False: Operation failed (see error_message)
+        error_message: Optional error message if success is False.
+            Must be sanitized - no credentials or PII.
+        timestamp: When the confirmation was generated by the Effect node.
+            Used for observability and timeout tracking.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumConfirmationEventType
+        >>> confirmation = ModelRegistrationConfirmation(
+        ...     event_type=EnumConfirmationEventType.CONSUL_REGISTERED,
+        ...     correlation_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     success=True,
+        ...     timestamp=datetime.now(UTC),
+        ... )
+        >>> confirmation.event_type
+        <EnumConfirmationEventType.CONSUL_REGISTERED: 'consul.registered'>
+        >>> confirmation.success
+        True
+
+    Example (failure case):
+        >>> from omnibase_infra.enums import EnumConfirmationEventType
+        >>> confirmation = ModelRegistrationConfirmation(
+        ...     event_type=EnumConfirmationEventType.POSTGRES_REGISTRATION_UPSERTED,
+        ...     correlation_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     success=False,
+        ...     error_message="Connection refused to database host",
+        ...     timestamp=datetime.now(UTC),
+        ... )
+        >>> confirmation.success
+        False
+        >>> confirmation.error_message
+        'Connection refused to database host'
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    event_type: EnumConfirmationEventType = Field(
+        ...,
+        description="The type of confirmation event (consul or postgres)",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="UUID linking this to the original registration request",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="UUID of the node being registered",
+    )
+    success: bool = Field(
+        ...,
+        description="Whether the registration operation succeeded",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Optional sanitized error message if success is False",
+    )
+    timestamp: datetime = Field(
+        ...,
+        description="When the confirmation was generated",
+    )
+
+
+__all__ = ["ModelRegistrationConfirmation"]