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

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_deactivate_contract.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Deactivate contract intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPayloadDeactivateContract(BaseModel):
+    """Payload for PostgreSQL deactivate contract intents.
+
+    Used when a contract-deregistered event is processed to mark the
+    contract as inactive (soft delete).
+
+    Note: contract_id is a derived natural key (node_name:major.minor.patch),
+    not a UUID. This is intentional per the contract registry design.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.deactivate_contract".
+        correlation_id: Correlation ID for distributed tracing.
+        contract_id: Contract to deactivate.
+        node_name: Contract node name.
+        reason: Deregistration reason (shutdown, upgrade, manual).
+        deactivated_at: Deactivation timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.deactivate_contract"] = Field(
+        default="postgres.deactivate_contract",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(..., description="Contract to deactivate.")
+
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(..., description="Contract node name.")
+
+    reason: str = Field(..., description="Deregistration reason.")
+
+    deactivated_at: datetime = Field(..., description="Deactivation timestamp.")
+
+
+__all__ = ["ModelPayloadDeactivateContract"]

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_mark_stale.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Mark stale intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPayloadMarkStale(BaseModel):
+    """Payload for PostgreSQL mark stale intents.
+
+    Used when a runtime-tick event is processed to batch mark
+    contracts as stale if they haven't been seen within the threshold.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.mark_stale".
+        correlation_id: Correlation ID for distributed tracing.
+        stale_cutoff: Contracts with last_seen_at before this are stale.
+        checked_at: When staleness check was performed.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.mark_stale"] = Field(
+        default="postgres.mark_stale",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    stale_cutoff: datetime = Field(
+        ..., description="Contracts older than this are marked stale."
+    )
+
+    checked_at: datetime = Field(..., description="When check was performed.")
+
+
+__all__ = ["ModelPayloadMarkStale"]

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_update_heartbeat.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Update heartbeat intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPayloadUpdateHeartbeat(BaseModel):
+    """Payload for PostgreSQL update heartbeat intents.
+
+    Used when a node-heartbeat event is processed to update the
+    last_seen_at timestamp for a contract.
+
+    Note: contract_id is a derived natural key (node_name:major.minor.patch),
+    not a UUID. This is intentional per the contract registry design.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.update_heartbeat".
+        correlation_id: Correlation ID for distributed tracing.
+        contract_id: Contract to update.
+        node_name: Contract node name.
+        source_node_id: String representation of heartbeating node's UUID (optional).
+        last_seen_at: New heartbeat timestamp.
+        uptime_seconds: Node uptime in seconds (optional).
+        sequence_number: Heartbeat sequence number (optional).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.update_heartbeat"] = Field(
+        default="postgres.update_heartbeat",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(..., description="Contract to update.")
+
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(..., description="Contract node name.")
+
+    source_node_id: str | None = Field(
+        default=None,
+        description="Source node ID as string (UUID string representation, optional).",
+    )
+
+    last_seen_at: datetime = Field(..., description="Heartbeat timestamp.")
+
+    uptime_seconds: float | None = Field(
+        default=None, ge=0, description="Node uptime in seconds."
+    )
+
+    sequence_number: int | None = Field(
+        default=None, ge=0, description="Heartbeat sequence number."
+    )
+
+
+__all__ = ["ModelPayloadUpdateHeartbeat"]

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_update_topic.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Update topic intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPayloadUpdateTopic(BaseModel):
+    """Payload for PostgreSQL update topic intents.
+
+    Used when a contract-registered event is processed to update
+    the topic routing table with producer/consumer information.
+
+    Note: contract_id is a derived natural key (node_name:major.minor.patch),
+    not a UUID. This is intentional per the contract registry design.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.update_topic".
+        correlation_id: Correlation ID for distributed tracing.
+        topic_suffix: Topic suffix (e.g., onex.evt.platform.contract-registered.v1).
+        direction: Whether this contract publishes or subscribes to the topic.
+        contract_id: Contract that uses this topic.
+        node_name: Contract node name.
+        event_type: Event type name (optional).
+        last_seen_at: When topic usage was last seen.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.update_topic"] = Field(
+        default="postgres.update_topic",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    topic_suffix: str = Field(..., description="Topic suffix.")
+
+    direction: Literal["publish", "subscribe"] = Field(
+        ..., description="Topic direction."
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(..., description="Contract using this topic.")
+
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(..., description="Contract node name.")
+
+    event_type: str | None = Field(default=None, description="Event type name.")
+
+    last_seen_at: datetime = Field(..., description="Last seen timestamp.")
+
+
+__all__ = ["ModelPayloadUpdateTopic"]

omnibase_infra/nodes/contract_registry_reducer/models/model_payload_upsert_contract.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Upsert contract intent payload model.
+
+Related:
+    - OMN-1653: Contract Registry Reducer implementation
+"""
+
+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
+
+
+class ModelPayloadUpsertContract(BaseModel):
+    """Payload for PostgreSQL upsert contract intents.
+
+    Used when a contract-registered event is processed to insert or update
+    the contract record in the contracts table.
+
+    Note: contract_id is a derived natural key (node_name:major.minor.patch),
+    not a UUID. This is intentional per the contract registry design.
+
+    Serialization Note:
+        The contract_yaml field accepts both dict (parsed) and str (raw YAML).
+        The Effect layer (PostgresAdapter) is responsible for serializing dict
+        to YAML string before INSERT, as the PostgreSQL column is TEXT type.
+
+    Attributes:
+        intent_type: Routing discriminator. Always "postgres.upsert_contract".
+        correlation_id: Correlation ID for distributed tracing.
+        contract_id: Derived contract identity (node_name:major.minor.patch).
+        node_name: Contract node name from event.
+        version_major: Semantic version major component.
+        version_minor: Semantic version minor component.
+        version_patch: Semantic version patch component.
+        contract_hash: Hash of the contract YAML for change detection.
+        contract_yaml: Full contract YAML for storage and replay. Accepts dict
+            (parsed) or str (raw). Effect layer serializes dict to YAML string
+            before INSERT.
+        source_node_id: UUID of the node that emitted the event (optional).
+        is_active: Whether the contract is currently active.
+        registered_at: Timestamp when contract was registered.
+        last_seen_at: Last heartbeat/registration timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: Literal["postgres.upsert_contract"] = Field(
+        default="postgres.upsert_contract",
+        description="Routing discriminator for intent dispatch.",
+    )
+
+    correlation_id: UUID = Field(
+        ..., description="Correlation ID for distributed tracing."
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ..., description="Contract identity: node_name:major.minor.patch"
+    )
+
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(..., description="Contract node name.")
+
+    version_major: int = Field(..., ge=0, description="Semantic version major.")
+    version_minor: int = Field(..., ge=0, description="Semantic version minor.")
+    version_patch: int = Field(..., ge=0, description="Semantic version patch.")
+
+    contract_hash: str = Field(..., description="Hash of contract YAML.")
+
+    contract_yaml: JsonType = Field(
+        ..., description="Full contract YAML (dict or raw string)."
+    )
+
+    source_node_id: str | None = Field(
+        default=None, description="Source node UUID (optional)."
+    )
+
+    is_active: bool = Field(default=True, description="Whether contract is active.")
+
+    registered_at: datetime = Field(..., description="Registration timestamp.")
+
+    last_seen_at: datetime = Field(..., description="Last heartbeat timestamp.")
+
+
+__all__ = ["ModelPayloadUpsertContract"]

omnibase_infra/nodes/contract_registry_reducer/node.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Registry Reducer - FSM-driven declarative reducer.
+
+This reducer follows the ONEX declarative pattern:
+    - DECLARATIVE reducer driven by contract.yaml
+    - Zero custom routing logic - all behavior from FSM state_machine
+    - Lightweight shell that delegates to NodeReducer base class
+    - Used for ONEX-compliant runtime execution via RuntimeHostProcess
+    - Pattern: "Contract-driven, FSM state transitions"
+
+Extends NodeReducer from omnibase_core for FSM-driven state management.
+All state transition logic is 100% driven by contract.yaml, not Python code.
+
+Purpose:
+    This reducer projects contract registration events to PostgreSQL:
+    1. Receives contract registration events from Kafka
+    2. Validates and deduplicates events using Kafka offset tracking
+    3. Emits PostgreSQL upsert intents for the contract_registry table
+    4. Processes heartbeat events to update last_seen timestamps
+    5. Handles deregistration events to mark contracts as inactive
+
+FSM Pattern:
+    1. Receive contract event (trigger: contract_registered, heartbeat, deregistered)
+    2. Check idempotency via Kafka offset (skip duplicates)
+    3. Emit PostgreSQL intent for persistence
+    4. Update state with processed event tracking
+
+Design Decisions:
+    - 100% Contract-Driven: All FSM logic in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: State transitions defined in state_machine
+    - Pure Function Pattern: (state, event) -> (new_state, intents)
+
+Related Modules:
+    - contract.yaml: FSM state machine and intent emission configuration
+    - models/: State model for idempotency and statistics tracking
+    - OMN-1653: Contract registry reducer implementation
+
+Testing Notes:
+    - Unit tests: tests/unit/nodes/contract_registry_reducer/
+    - Integration tests: Required before production
+        * Intent emission through RuntimeHostProcess
+        * End-to-end contract workflow with PostgreSQL mocks
+        * Kafka offset-based idempotency verification
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_reducer import NodeReducer
+
+if TYPE_CHECKING:
+    # Import needed for string annotation in class definition
+    from omnibase_infra.nodes.contract_registry_reducer.models.model_contract_registry_state import (
+        ModelContractRegistryState,
+    )
+
+
+class NodeContractRegistryReducer(
+    NodeReducer["ModelContractRegistryState", "ModelContractRegistryState"]
+):
+    """Contract registry reducer - FSM state transitions driven by contract.yaml.
+
+    This is a purely declarative reducer. All behavior is defined in contract.yaml.
+    No custom Python logic is required - the base NodeReducer class handles all
+    FSM-driven state transitions via the contract configuration.
+
+    This reducer processes contract registration workflows by:
+    1. Receiving contract events (registration, heartbeat, deregistration)
+    2. Executing FSM transitions defined in contract.yaml
+    3. Emitting PostgreSQL upsert intents for the contract_registry table
+    4. Tracking processed events for idempotency via Kafka offsets
+
+    All state transition logic, intent emission, and validation are driven
+    entirely by the contract.yaml FSM configuration.
+
+    Example YAML Contract (state_machine section):
+        ```yaml
+        state_machine:
+          state_machine_name: contract_registry_fsm
+          initial_state: idle
+          states:
+            - state_name: idle
+              description: "Waiting for contract events"
+            - state_name: processing
+              description: "Processing contract event"
+              entry_actions:
+                - emit_postgres_upsert_intent
+          transitions:
+            - from_state: idle
+              to_state: processing
+              trigger: contract_received
+              conditions:
+                - expression: "node_id is_present"
+                  required: true
+        ```
+
+    Usage:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_core.models.reducer import ModelReducerInput
+        from omnibase_core.enums import EnumReductionType
+
+        # Create and initialize
+        container = ModelONEXContainer()
+        reducer = NodeContractRegistryReducer(container)
+
+        # Process input via FSM
+        input_data = ModelReducerInput(
+            data=contract_event,
+            reduction_type=EnumReductionType.MERGE,
+            metadata=ModelReducerMetadata(trigger="contract_registered"),
+        )
+        result = await reducer.process(input_data)
+        ```
+    """
+
+
+__all__ = ["NodeContractRegistryReducer"]