omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_orchestrator/models/model_consul_intent_payload.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul intent payload model for registration orchestrator.
+
+This module provides the typed payload model for Consul registration intents.
+
+Thread Safety:
+    This model is fully immutable (frozen=True) with immutable field types.
+    - ``tags`` uses tuple instead of list
+    - ``meta`` uses tuple of key-value pairs instead of dict
+
+    For dict-like access to metadata, use the ``meta_dict`` property which
+    returns a MappingProxyType (read-only view).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ModelConsulIntentPayload(BaseModel):
+    """Payload for Consul registration intents.
+
+    Used by the Consul adapter to register nodes in service discovery.
+
+    This model is fully immutable to support thread-safe concurrent access.
+    All fields use immutable types (tuple instead of list/dict).
+
+    Attributes:
+        service_name: Name to register the node as in Consul.
+        tags: Immutable tuple of service tags for Consul filtering.
+        meta: Immutable tuple of (key, value) pairs for metadata.
+            Use the ``meta_dict`` property for dict-like read access.
+
+    Example:
+        >>> payload = ModelConsulIntentPayload(
+        ...     service_name="my-service",
+        ...     tags=["production", "v1"],
+        ...     meta={"env": "prod", "region": "us-west"},
+        ... )
+        >>> payload.tags
+        ('production', 'v1')
+        >>> payload.meta_dict["env"]
+        'prod'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    service_name: str = Field(
+        ...,
+        min_length=1,
+        description="Service name to register in Consul",
+    )
+    tags: tuple[str, ...] = Field(
+        default=(),
+        description="Immutable tuple of service tags for Consul filtering",
+    )
+    meta: tuple[tuple[str, str], ...] = Field(
+        default=(),
+        description="Immutable tuple of (key, value) pairs for metadata",
+    )
+
+    @field_validator("tags", mode="before")
+    @classmethod
+    def _coerce_tags_to_tuple(cls, v: object) -> tuple[str, ...]:
+        """Convert list/sequence to tuple for immutability.
+
+        This validator ensures explicit handling of all input types rather than
+        silent fallback, which could mask invalid input. In strict mode, all
+        items must already be strings - no silent type coercion.
+
+        Args:
+            v: The input value to coerce. Must be a tuple, list, set, or frozenset
+                containing only string elements.
+
+        Returns:
+            A tuple of string tags.
+
+        Raises:
+            ValueError: If the input is not a recognized sequence type or if
+                any element is not a string. This ensures invalid input types
+                are explicitly rejected rather than silently coerced.
+
+        Edge Cases:
+            - ``None``: Raises ValueError (explicit rejection)
+            - Empty sequence ``[]``, ``()``: Returns empty tuple
+            - Invalid types (int, str, dict): Raises ValueError
+            - Non-string elements: Raises ValueError (strict mode)
+            - Valid sequences of strings: Converts to tuple
+        """
+        if isinstance(v, tuple):
+            # Validate tuple contents in strict mode
+            for i, item in enumerate(v):
+                if not isinstance(item, str):
+                    raise ValueError(
+                        f"tags[{i}] must be a string, got {type(item).__name__}"
+                    )
+            return v  # type: ignore[return-value]  # NOTE: runtime type validated by Pydantic
+        if isinstance(v, list | set | frozenset):
+            # Validate and convert to tuple - strict mode requires string elements
+            result: list[str] = []
+            for i, item in enumerate(v):
+                if not isinstance(item, str):
+                    raise ValueError(
+                        f"tags[{i}] must be a string, got {type(item).__name__}"
+                    )
+                result.append(item)
+            return tuple(result)
+        raise ValueError(
+            f"tags must be a tuple, list, set, or frozenset, got {type(v).__name__}"
+        )
+
+    @field_validator("meta", mode="before")
+    @classmethod
+    def _coerce_meta_to_tuple(cls, v: object) -> tuple[tuple[str, str], ...]:
+        """Convert dict/mapping to tuple of pairs for immutability.
+
+        This validator ensures explicit handling of all input types rather than
+        silent fallback to empty tuple, which could mask invalid input. In strict
+        mode, all keys and values must already be strings - no silent type coercion.
+
+        Args:
+            v: The input value to coerce. Must be either a tuple of (key, value)
+                pairs or a Mapping (dict-like object) with string keys and values.
+
+        Returns:
+            A tuple of (key, value) string pairs.
+
+        Raises:
+            ValueError: If the input is neither a tuple nor a Mapping type, or if
+                any key/value is not a string. This ensures invalid input types
+                are explicitly rejected rather than silently coerced.
+
+        Edge Cases:
+            - ``None``: Raises ValueError (explicit rejection)
+            - Empty Mapping ``{}``: Returns empty tuple
+            - Empty tuple ``()``: Passed through (same as default)
+            - Invalid types (list, int, str): Raises ValueError
+            - Non-string keys/values: Raises ValueError (strict mode)
+            - Non-empty Mapping with strings: Converts to tuple of (key, value) pairs
+        """
+        if isinstance(v, tuple):
+            # Validate tuple contents in strict mode
+            for i, item in enumerate(v):
+                if not isinstance(item, tuple) or len(item) != 2:
+                    raise ValueError(
+                        f"meta[{i}] must be a (key, value) tuple, got {type(item).__name__}"
+                    )
+                key, val = item
+                if not isinstance(key, str):
+                    raise ValueError(
+                        f"meta[{i}][0] (key) must be a string, got {type(key).__name__}"
+                    )
+                if not isinstance(val, str):
+                    raise ValueError(
+                        f"meta[{i}][1] (value) must be a string, got {type(val).__name__}"
+                    )
+            return v  # type: ignore[return-value]  # NOTE: runtime type validated by Pydantic
+        if isinstance(v, Mapping):
+            # Validate and convert to tuple - strict mode requires string keys/values
+            result: list[tuple[str, str]] = []
+            for key, val in v.items():
+                if not isinstance(key, str):
+                    raise ValueError(
+                        f"meta key must be a string, got {type(key).__name__}"
+                    )
+                if not isinstance(val, str):
+                    raise ValueError(
+                        f"meta[{key!r}] value must be a string, got {type(val).__name__}"
+                    )
+                result.append((key, val))
+            return tuple(result)
+        raise ValueError(f"meta must be a tuple or Mapping, got {type(v).__name__}")
+
+    @property
+    def meta_dict(self) -> MappingProxyType[str, str]:
+        """Return a read-only dict view of the metadata.
+
+        Returns:
+            MappingProxyType providing dict-like read access to metadata.
+        """
+        return MappingProxyType(dict(self.meta))
+
+
+__all__ = [
+    "ModelConsulIntentPayload",
+]

omnibase_infra/nodes/node_registration_orchestrator/models/model_consul_registration_intent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul registration intent model for registration orchestrator.
+
+This module provides the typed intent model for Consul registration operations.
+Registered with RegistryIntent for dynamic type resolution.
+
+Related:
+    - ModelRegistryIntent: Base class for all registration intents
+    - RegistryIntent: Decorator-based registry for intent type discovery
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_consul_intent_payload import (
+    ModelConsulIntentPayload,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_registry_intent import (
+    ModelRegistryIntent,
+    RegistryIntent,
+)
+
+
+@RegistryIntent.register("consul")
+class ModelConsulRegistrationIntent(ModelRegistryIntent):
+    """Intent to register a node in Consul service discovery.
+
+    This model is registered with RegistryIntent for dynamic type resolution,
+    enabling Pydantic discriminated union validation without explicit union types.
+
+    Attributes:
+        kind: Literal discriminator, always "consul".
+        operation: The operation type (e.g., "register", "deregister").
+        node_id: Target node ID for the operation.
+        correlation_id: Correlation ID for distributed tracing.
+        payload: Consul-specific registration payload.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    kind: Literal["consul"] = Field(
+        default="consul",
+        description="Intent type discriminator",
+    )
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Operation to perform (e.g., 'register', 'deregister')",
+    )
+    payload: ModelConsulIntentPayload = Field(
+        ...,
+        description="Consul-specific registration payload",
+    )
+
+
+__all__ = [
+    "ModelConsulRegistrationIntent",
+]

omnibase_infra/nodes/node_registration_orchestrator/models/model_intent_execution_result.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Intent execution result model for registration orchestrator."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIntentExecutionResult(BaseModel):
+    """Result of executing a single intent.
+
+    Captures the outcome of a single registration intent execution,
+    including success/failure status, timing, and error details.
+
+    Attributes:
+        intent_kind: The type of intent that was executed (e.g., 'consul', 'postgres').
+        success: Whether the execution completed successfully.
+        error: Error message if execution failed, None otherwise.
+        execution_time_ms: Time taken to execute the intent in milliseconds.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        from_attributes=True,
+    )
+
+    intent_kind: str = Field(
+        ...,
+        min_length=1,
+        description="The intent kind that was executed",
+    )
+    success: bool = Field(
+        ...,
+        description="Whether execution succeeded",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if failed",
+    )
+    execution_time_ms: float = Field(
+        ...,
+        ge=0.0,
+        description="Execution time in milliseconds",
+    )
+
+
+__all__ = ["ModelIntentExecutionResult"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_node_liveness_expired.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Liveness expired event model for the registration orchestrator.
+
+Emitted when an active node misses its liveness heartbeat deadline.
+This is a timeout decision event that triggers state transition to LIVENESS_EXPIRED.
+
+Timestamp Accuracy Verification (2025-12-25):
+    All timestamps in this event model are verified accurate:
+
+    - detected_at: Fresh UTC timestamp from RuntimeTick.now at detection time.
+      Source: RuntimeScheduler.emit_tick() -> datetime.now(UTC) -> process_timeouts().
+      NOT cached or stale.
+
+    - liveness_deadline: The deadline that was missed, sourced from the
+      registration projection (calculated as last_heartbeat_at + liveness_window
+      when heartbeat was processed).
+
+    - last_heartbeat_at: Optional timestamp of last heartbeat, sourced from
+      projection.last_heartbeat_at (set from heartbeat event timestamp).
+
+    UTC timezone handling is enforced at the RuntimeScheduler level using
+    datetime.now(UTC). See test_timeout_emitter.py for comprehensive tests.
+
+Related Tickets:
+    - OMN-932 (C2): Durable Timeout Handling
+    - OMN-888 (C1): Registration Orchestrator
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeLivenessExpired(BaseModel):
+    """Event emitted when an active node misses liveness heartbeat deadline.
+
+    This is a timeout decision event emitted by the orchestrator when:
+    - liveness_deadline has passed
+    - Node state is ACTIVE
+    - No previous expiry event was emitted (liveness_timeout_emitted_at was None)
+
+    The orchestrator emits this event during RuntimeTick processing when
+    scanning projections for missed heartbeat deadlines. The reducer will
+    transition the node to LIVENESS_EXPIRED state (terminal) upon receiving
+    this event.
+
+    Topic Pattern:
+        {env}.{namespace}.onex.evt.node-liveness-expired.v1
+
+    Attributes:
+        node_id: UUID of the node whose liveness expired.
+        liveness_deadline: The deadline that was missed.
+        detected_at: When the expiry was detected (from RuntimeTick.now).
+        last_heartbeat_at: When the last heartbeat was received (if tracked).
+        correlation_id: Correlation ID from the RuntimeTick that triggered detection.
+        causation_id: Message ID that caused this event (RuntimeTick.tick_id).
+
+    Example:
+        >>> from datetime import datetime, UTC, timedelta
+        >>> from uuid import uuid4
+        >>> now = datetime.now(UTC)
+        >>> event = ModelNodeLivenessExpired(
+        ...     node_id=uuid4(),
+        ...     liveness_deadline=now - timedelta(seconds=30),
+        ...     detected_at=now,
+        ...     last_heartbeat_at=now - timedelta(minutes=2),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    node_id: UUID = Field(
+        ...,
+        description="UUID of the node whose liveness expired",
+    )
+    liveness_deadline: datetime = Field(
+        ...,
+        description="The deadline that was missed",
+    )
+    detected_at: datetime = Field(
+        ...,
+        description="When the expiry was detected (from RuntimeTick.now)",
+    )
+    last_heartbeat_at: datetime | None = Field(
+        default=None,
+        description="When last heartbeat was received (if tracked)",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID from the RuntimeTick that triggered detection",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="Message ID that caused this event (RuntimeTick.tick_id)",
+    )
+
+
+__all__ = ["ModelNodeLivenessExpired"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_orchestrator_config.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for registration orchestrator."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOrchestratorConfig(BaseModel):
+    """Configuration for the registration orchestrator node.
+
+    Controls workflow execution parameters including timeouts, retry behavior,
+    and failure handling strategies.
+
+    Attributes:
+        timeout_seconds: Maximum time allowed for the entire workflow.
+        max_retries: Maximum retry attempts for individual effect calls.
+        initial_delay_ms: Initial delay before first retry attempt.
+        max_delay_ms: Maximum delay between retry attempts.
+        exponential_base: Base for exponential backoff calculation.
+        fail_fast: If True, stop workflow on first failure; if False, continue.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Workflow timeout in seconds",
+    )
+    max_retries: int = Field(
+        default=3,
+        ge=0,
+        le=10,
+        description="Max retry attempts for effect calls",
+    )
+    initial_delay_ms: int = Field(
+        default=100,
+        ge=10,
+        le=10000,
+        description="Initial retry delay in milliseconds",
+    )
+    max_delay_ms: int = Field(
+        default=5000,
+        ge=100,
+        le=60000,
+        description="Max retry delay in milliseconds",
+    )
+    exponential_base: float = Field(
+        default=2.0,
+        ge=1.1,
+        le=4.0,
+        description="Exponential backoff base multiplier",
+    )
+    fail_fast: bool = Field(
+        default=True,
+        description="Stop on first failure if True",
+    )
+
+
+__all__ = ["ModelOrchestratorConfig"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_orchestrator_input.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Input model for registration orchestrator."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.registration import ModelNodeIntrospectionEvent
+
+
+class ModelOrchestratorInput(BaseModel):
+    """Input for the registration orchestrator workflow.
+
+    Contains the introspection event to process and correlation ID for
+    distributed tracing across the workflow execution.
+
+    Attributes:
+        introspection_event: The introspection event containing node registration data.
+        correlation_id: Correlation ID for distributed tracing.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    introspection_event: ModelNodeIntrospectionEvent = Field(
+        ...,
+        description="The introspection event to process",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+
+
+__all__ = ["ModelOrchestratorInput"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_orchestrator_output.py

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Output model for registration orchestrator.
+
+Thread Safety:
+    This model is fully immutable (frozen=True) with immutable field types.
+    The ``intent_results`` field uses tuple instead of list to ensure
+    complete immutability for thread-safe concurrent access.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_intent_execution_result import (
+    ModelIntentExecutionResult,
+)
+
+
+class ModelOrchestratorOutput(BaseModel):
+    """Output from the registration orchestrator workflow.
+
+    Provides comprehensive results of the orchestrated registration workflow,
+    including per-target success status and detailed execution metrics.
+
+    This model is fully immutable to support thread-safe concurrent access.
+    All collection fields use immutable types (tuple instead of list).
+
+    Attributes:
+        correlation_id: Correlation ID for distributed tracing.
+        status: Overall workflow status - success, partial, or failed.
+        consul_applied: Whether Consul registration succeeded.
+        postgres_applied: Whether PostgreSQL registration succeeded.
+        consul_error: Error message from Consul registration if any.
+        postgres_error: Error message from PostgreSQL registration if any.
+        intent_results: Immutable tuple of results for each executed intent.
+        total_execution_time_ms: Total workflow execution time in milliseconds.
+
+    Example:
+        >>> output = ModelOrchestratorOutput(
+        ...     correlation_id=uuid4(),
+        ...     status="success",
+        ...     intent_results=[result1, result2],  # list auto-converted to tuple
+        ...     total_execution_time_ms=150.5,
+        ... )
+        >>> isinstance(output.intent_results, tuple)
+        True
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    status: Literal["success", "partial", "failed"] = Field(
+        ...,
+        description="Overall workflow status",
+    )
+    consul_applied: bool = Field(
+        default=False,
+        description="Whether Consul registration succeeded",
+    )
+    postgres_applied: bool = Field(
+        default=False,
+        description="Whether PostgreSQL registration succeeded",
+    )
+    consul_error: str | None = Field(
+        default=None,
+        description="Consul error message if any",
+    )
+    postgres_error: str | None = Field(
+        default=None,
+        description="PostgreSQL error message if any",
+    )
+    intent_results: tuple[ModelIntentExecutionResult, ...] = Field(
+        default=(),
+        description="Immutable tuple of results for each intent execution",
+    )
+    total_execution_time_ms: float = Field(
+        ...,
+        ge=0.0,
+        description="Total workflow execution time in milliseconds",
+    )
+
+    @field_validator("intent_results", mode="before")
+    @classmethod
+    def _coerce_intent_results_to_tuple(
+        cls, v: object
+    ) -> tuple[ModelIntentExecutionResult, ...]:
+        """Convert list/sequence to tuple for immutability.
+
+        This validator ensures explicit handling of all input types rather than
+        silent fallback to empty tuple, which could mask invalid input. In strict
+        mode, all elements must already be ModelIntentExecutionResult instances -
+        no silent type coercion from dicts or other types.
+
+        Args:
+            v: The input value to coerce. Must be either a tuple or a Sequence
+                (excluding str and bytes) containing only ModelIntentExecutionResult
+                instances.
+
+        Returns:
+            A tuple of ModelIntentExecutionResult items.
+
+        Raises:
+            ValueError: If the input is None, str, bytes, or any other non-sequence
+                type, OR if any element is not a ModelIntentExecutionResult instance.
+                This ensures invalid input types are explicitly rejected rather than
+                silently coerced.
+
+        Edge Cases:
+            - ``None``: Raises ValueError (explicit rejection)
+            - ``str`` or ``bytes``: Raises ValueError (not valid sequences for this field)
+            - Empty tuple ``()``: Passed through (same as default)
+            - Empty list ``[]``: Converted to empty tuple
+            - Other non-sequence types (int, dict, etc.): Raises ValueError
+            - Sequence with dict elements: Raises ValueError (strict mode - no coercion)
+            - Sequence with ModelIntentExecutionResult: Converts to tuple
+
+        Example:
+            >>> # Valid inputs
+            >>> _coerce_intent_results_to_tuple([result1, result2])
+            (result1, result2)
+            >>> _coerce_intent_results_to_tuple(())
+            ()
+            >>> # Invalid inputs raise ValueError
+            >>> _coerce_intent_results_to_tuple(None)  # Raises ValueError
+            >>> _coerce_intent_results_to_tuple("not a sequence")  # Raises ValueError
+            >>> _coerce_intent_results_to_tuple([{"target": "consul"}])  # Raises ValueError
+        """
+        if isinstance(v, tuple):
+            # Validate tuple contents in strict mode
+            for i, item in enumerate(v):
+                if not isinstance(item, ModelIntentExecutionResult):
+                    raise ValueError(
+                        f"intent_results[{i}] must be a ModelIntentExecutionResult, "
+                        f"got {type(item).__name__}"
+                    )
+            return v  # type: ignore[return-value]  # NOTE: runtime type validated above
+        if isinstance(v, Sequence) and not isinstance(v, str | bytes):
+            # Validate and convert to tuple - strict mode requires model instances
+            result: list[ModelIntentExecutionResult] = []
+            for i, item in enumerate(v):
+                if not isinstance(item, ModelIntentExecutionResult):
+                    raise ValueError(
+                        f"intent_results[{i}] must be a ModelIntentExecutionResult, "
+                        f"got {type(item).__name__}"
+                    )
+                result.append(item)
+            return tuple(result)
+        raise ValueError(
+            f"intent_results must be a tuple or Sequence (excluding str/bytes), "
+            f"got {type(v).__name__}"
+        )
+
+
+__all__ = ["ModelOrchestratorOutput"]