omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_orchestrator/models/model_postgres_intent_payload.py

@@ -0,0 +1,235 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL intent payload model for registration orchestrator.
+
+This module provides the typed payload model for PostgreSQL registration intents.
+
+Design Note:
+    This model uses strongly-typed ModelNodeCapabilities and ModelNodeMetadata
+    instead of generic dict[str, JsonType] to adhere to ONEX "no Any types"
+    principle. The JsonType type alias contains list[Any] and dict[str, Any]
+    internally, which violates strict typing requirements.
+
+    Using the same typed models as ModelNodeIntrospectionEvent ensures:
+    1. Type safety throughout the registration pipeline
+    2. Consistent validation between event source and database persistence
+    3. No implicit Any types in the payload structure
+
+Thread Safety:
+    This model is fully immutable (frozen=True) with immutable field types.
+    The ``endpoints`` field uses tuple of key-value pairs instead of dict
+    to ensure complete immutability for thread-safe concurrent access.
+
+    For dict-like access to endpoints, use the ``endpoints_dict`` property
+    which returns a MappingProxyType (read-only view).
+
+Edge Case Behavior:
+    The ``endpoints`` field validator explicitly handles the following cases:
+    - ``None``: Raises ValueError (invalid input, not silently ignored)
+    - Empty Mapping ``{}``: Logs warning and converts to empty tuple
+    - Invalid types (int, str, list, etc.): Raises ValueError
+    - Tuple: Passed through as-is
+    - Non-empty Mapping: Converted to tuple of (key, value) pairs
+    - Non-string keys/values: Raises ValueError (strict mode)
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from collections.abc import Mapping
+from types import MappingProxyType
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+from omnibase_infra.models.registration.model_node_metadata import ModelNodeMetadata
+
+# Module-level initialization (after all imports)
+logger = logging.getLogger(__name__)
+
+
+class ModelPostgresIntentPayload(BaseModel):
+    """Payload for PostgreSQL registration intents.
+
+    Contains the full node introspection data to upsert into the
+    registration database. This is a typed representation of the
+    data previously passed via model_dump().
+
+    Uses strongly-typed capability and metadata models matching
+    ModelNodeIntrospectionEvent for type-safe pipeline processing.
+
+    This model is fully immutable to support thread-safe concurrent access.
+    All collection fields use immutable types (tuple instead of dict).
+
+    Attributes:
+        node_id: Unique node identifier.
+        node_type: ONEX node type (effect, compute, reducer, orchestrator).
+        node_version: Semantic version of the node.
+        capabilities: Strongly-typed node capabilities.
+        endpoints: Immutable tuple of (name, URL) pairs for exposed endpoints.
+            Use the ``endpoints_dict`` property for dict-like read access.
+        node_role: Optional role descriptor.
+        metadata: Strongly-typed node metadata.
+        correlation_id: Correlation ID for distributed tracing.
+        network_id: Network/cluster identifier.
+        deployment_id: Deployment/release identifier.
+        epoch: Registration epoch for ordering.
+        timestamp: Event timestamp as ISO string.
+
+    Example:
+        >>> from omnibase_core.enums import EnumNodeKind
+        >>> payload = ModelPostgresIntentPayload(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     endpoints={"health": "/health", "api": "/api/v1"},
+        ...     correlation_id=uuid4(),
+        ...     timestamp="2025-01-01T00:00:00Z",
+        ... )
+        >>> payload.endpoints
+        (('health', '/health'), ('api', '/api/v1'))
+        >>> payload.endpoints_dict["health"]
+        '/health'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    node_id: UUID = Field(..., description="Unique node identifier")
+    # Design Note: node_type uses EnumNodeKind for type-safe ONEX node type validation.
+    # This ensures only valid ONEX node types can be persisted to PostgreSQL.
+    node_type: EnumNodeKind = Field(..., description="ONEX node type")
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node",
+    )
+    capabilities: ModelNodeCapabilities = Field(
+        default_factory=ModelNodeCapabilities,
+        description="Strongly-typed node capabilities",
+    )
+    endpoints: tuple[tuple[str, str], ...] = Field(
+        default=(),
+        description="Immutable tuple of (name, URL) pairs for exposed endpoints",
+    )
+    node_role: str | None = Field(default=None, description="Node role")
+    metadata: ModelNodeMetadata = Field(
+        default_factory=ModelNodeMetadata,
+        description="Strongly-typed node metadata",
+    )
+    correlation_id: UUID = Field(..., description="Correlation ID for tracing")
+    network_id: str | None = Field(default=None, description="Network identifier")
+    deployment_id: str | None = Field(default=None, description="Deployment identifier")
+    epoch: int | None = Field(default=None, ge=0, description="Registration epoch")
+    timestamp: str = Field(..., description="Event timestamp as ISO string")
+
+    @field_validator("endpoints", mode="before")
+    @classmethod
+    def _coerce_endpoints_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 ``{}``: Logs warning, 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
+
+        Example:
+            >>> # Valid inputs
+            >>> _coerce_endpoints_to_tuple({"health": "/health"})
+            (('health', '/health'),)
+            >>> _coerce_endpoints_to_tuple(())
+            ()
+            >>> # Invalid inputs raise ValueError
+            >>> _coerce_endpoints_to_tuple(None)  # Raises ValueError
+            >>> _coerce_endpoints_to_tuple([])    # Raises ValueError (list not Mapping)
+            >>> _coerce_endpoints_to_tuple({1: "/health"})  # Raises ValueError (non-string key)
+        """
+        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"endpoints[{i}] must be a (key, value) tuple, "
+                        f"got {type(item).__name__}"
+                    )
+                key, val = item
+                if not isinstance(key, str):
+                    raise ValueError(
+                        f"endpoints[{i}][0] (key) must be a string, "
+                        f"got {type(key).__name__}"
+                    )
+                if not isinstance(val, str):
+                    raise ValueError(
+                        f"endpoints[{i}][1] (value) must be a string, "
+                        f"got {type(val).__name__}"
+                    )
+            return v  # type: ignore[return-value]  # NOTE: runtime type validated by Pydantic
+        if isinstance(v, Mapping):
+            if len(v) == 0:
+                # Log warning for empty Mapping to help detect potentially missing data.
+                # This is different from the default empty tuple - it's an explicit
+                # empty Mapping input that gets coerced.
+                warning_msg = (
+                    "Empty Mapping provided for endpoints, coercing to empty tuple. "
+                    "If this is intentional, consider using default=() instead."
+                )
+                logger.warning(warning_msg)
+                warnings.warn(warning_msg, UserWarning, stacklevel=2)
+                return ()
+            # 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"endpoints key must be a string, got {type(key).__name__}"
+                    )
+                if not isinstance(val, str):
+                    raise ValueError(
+                        f"endpoints[{key!r}] value must be a string, "
+                        f"got {type(val).__name__}"
+                    )
+                result.append((key, val))
+            return tuple(result)
+        raise ValueError(
+            f"endpoints must be a tuple or Mapping, got {type(v).__name__}"
+        )
+
+    @property
+    def endpoints_dict(self) -> MappingProxyType[str, str]:
+        """Return a read-only dict view of the endpoints.
+
+        Returns:
+            MappingProxyType providing dict-like read access to endpoints.
+        """
+        return MappingProxyType(dict(self.endpoints))
+
+
+__all__ = [
+    "ModelPostgresIntentPayload",
+]

omnibase_infra/nodes/node_registration_orchestrator/models/model_postgres_upsert_intent.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL upsert intent model for registration orchestrator.
+
+This module provides the typed intent model for PostgreSQL upsert 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_postgres_intent_payload import (
+    ModelPostgresIntentPayload,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_registry_intent import (
+    ModelRegistryIntent,
+    RegistryIntent,
+)
+
+
+@RegistryIntent.register("postgres")
+class ModelPostgresUpsertIntent(ModelRegistryIntent):
+    """Intent to upsert node registration in PostgreSQL.
+
+    This model is registered with RegistryIntent for dynamic type resolution,
+    enabling Pydantic discriminated union validation without explicit union types.
+
+    Attributes:
+        kind: Literal discriminator, always "postgres".
+        operation: The operation type (e.g., "upsert", "delete").
+        node_id: Target node ID for the operation.
+        correlation_id: Correlation ID for distributed tracing.
+        payload: PostgreSQL-specific registration payload.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        from_attributes=True,
+    )
+
+    kind: Literal["postgres"] = Field(
+        default="postgres",
+        description="Intent type discriminator",
+    )
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Operation to perform (e.g., 'upsert', 'delete')",
+    )
+    payload: ModelPostgresIntentPayload = Field(
+        ...,
+        description="PostgreSQL-specific registration payload",
+    )
+
+
+__all__ = [
+    "ModelPostgresUpsertIntent",
+]

omnibase_infra/nodes/node_registration_orchestrator/models/model_reducer_execution_result.py

@@ -0,0 +1,384 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Reducer execution result model for the registration orchestrator.
+
+This model replaces the tuple pattern `tuple[ModelReducerState, tuple[ModelRegistrationIntent, ...]]`
+that was used for reducer return values. By using a single model type, we eliminate
+the tuple pattern while providing richer context and self-documenting field names.
+
+Design Pattern:
+    ModelReducerExecutionResult replaces tuple returns from ProtocolReducer.reduce()
+    with a strongly-typed, self-documenting model. This follows the ONEX principle
+    of using Pydantic models instead of tuple returns for method results.
+
+    The model is intentionally frozen (immutable) to ensure thread safety when
+    the same result is passed between components. The intents field uses an
+    immutable tuple rather than a mutable list to maintain full immutability.
+
+Intent Typing:
+    The intents field accepts any model inheriting from ModelRegistryIntent.
+    Intent types self-register via the @RegistryIntent.register() decorator,
+    enabling dynamic type resolution during deserialization without explicit unions.
+
+    This registry-based approach:
+    - Eliminates duplicate union definitions across modules
+    - Allows future intent types to be added by simply implementing ModelRegistryIntent
+      and registering with @RegistryIntent.register("kind")
+    - Uses the `kind` field as a discriminator for type resolution
+    - Follows ONEX duck typing principles while maintaining type safety
+
+    Current implementations:
+    - ModelConsulRegistrationIntent (kind="consul"): Consul service registration
+    - ModelPostgresUpsertIntent (kind="postgres"): PostgreSQL upsert operations
+
+    For type hints in external code, use ProtocolRegistrationIntent from
+    omnibase_infra.nodes.node_registration_orchestrator.protocols for duck-typed
+    signatures, or ModelRegistryIntent for concrete model requirements.
+
+Thread Safety:
+    ModelReducerExecutionResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access. All fields use immutable
+    types (ModelReducerState is also frozen, intents is a tuple).
+
+Example:
+    >>> from omnibase_infra.nodes.node_registration_orchestrator.models import (
+    ...     ModelReducerExecutionResult,
+    ...     ModelReducerState,
+    ... )
+    >>>
+    >>> # Create a result with no intents
+    >>> result = ModelReducerExecutionResult.empty()
+    >>> result.state.processed_node_ids
+    frozenset()
+    >>> result.intents
+    ()
+    >>>
+    >>> # Create from existing state with intents
+    >>> state = ModelReducerState(pending_registrations=2)
+    >>> result = ModelReducerExecutionResult(state=state, intents=(intent1, intent2))
+
+.. versionadded:: 0.7.0
+    Created as part of tuple-to-model conversion work (OMN-1007).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_reducer_state import (
+    ModelReducerState,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_registry_intent import (
+    ModelRegistryIntent,
+    RegistryIntent,
+)
+
+
+class ModelReducerExecutionResult(BaseModel):
+    """Result of reducer execution containing state and generated intents.
+
+    This model replaces the `tuple[ModelReducerState, tuple[ModelRegistrationIntent, ...]]`
+    pattern with a strongly-typed container that provides:
+    - Self-documenting field names (state, intents)
+    - Factory methods for common patterns (empty, no_change, with_intents)
+    - Full immutability for thread safety (frozen model with tuple intents)
+    - Protocol-based intent typing for extensibility (ProtocolRegistrationIntent)
+
+    Attributes:
+        state: The updated reducer state after processing an event.
+        intents: Tuple of registration intents to be executed by the effect node.
+            May be empty if no infrastructure operations are needed.
+
+    Warning:
+        **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to return
+        ``True`` only when intents are present (i.e., ``has_intents`` is True). This
+        differs from typical Pydantic model behavior where ``bool(model)`` always
+        returns ``True`` for any valid model instance.
+
+        This design enables idiomatic conditional checks for work to be done::
+
+            if result:
+                # Process intents - there is work to do
+                execute_intents(result.intents)
+            else:
+                # No intents - skip processing
+                pass
+
+        If you need to check model validity instead, use explicit attribute access::
+
+            # Check for intents (uses __bool__)
+            if result:
+                ...
+
+            # Check model is valid (always True for constructed instance)
+            if result is not None:
+                ...
+
+            # Explicit intent check (preferred for clarity)
+            if result.has_intents:
+                ...
+
+    Example:
+        >>> # Create result with state and intents
+        >>> state = ModelReducerState(pending_registrations=2)
+        >>> result = ModelReducerExecutionResult(
+        ...     state=state,
+        ...     intents=(consul_intent, postgres_intent),
+        ... )
+        >>> result.has_intents
+        True
+        >>> result.intent_count
+        2
+
+        >>> # Create empty result (no state changes, no intents)
+        >>> result = ModelReducerExecutionResult.empty()
+        >>> result.has_intents
+        False
+
+    .. versionadded:: 0.7.0
+        Created as part of OMN-1007 tuple-to-model conversion.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    state: ModelReducerState = Field(
+        ...,
+        description="The updated reducer state after processing the event.",
+    )
+    intents: tuple[ModelRegistryIntent, ...] = Field(
+        default=(),
+        description=(
+            "Tuple of registration intents to be executed by the effect node. "
+            "All intents must inherit from ModelRegistryIntent and be registered "
+            "with RegistryIntent."
+        ),
+    )
+    # Note: When serializing this model, use model_dump(serialize_as_any=True)
+    # to ensure intent fields (like 'payload') that exist only on concrete types
+    # are included. Without this, Pydantic serializes according to the declared
+    # base type (ModelRegistryIntent) which omits subclass-specific fields.
+
+    @field_validator("intents", mode="before")
+    @classmethod
+    def validate_intents(cls, v: object) -> tuple[ModelRegistryIntent, ...]:
+        """Resolve intent types dynamically from RegistryIntent.
+
+        When deserializing from JSON/dict, uses the 'kind' field to look up
+        the correct concrete intent class from the registry.
+
+        Args:
+            v: Raw input value (tuple, list, or sequence of dicts/models)
+
+        Returns:
+            Tuple of validated ModelRegistryIntent instances
+
+        Raises:
+            ValueError: If intent kind is not registered or dict missing 'kind' field
+        """
+        if v is None:
+            return ()
+
+        # Validate input is a proper sequence (not str/bytes)
+        if not isinstance(v, Sequence) or isinstance(v, str | bytes):
+            raise ValueError(
+                f"intents must be a tuple or Sequence (excluding str/bytes), "
+                f"got {type(v).__name__}"
+            )
+
+        result: list[ModelRegistryIntent] = []
+        for item in v:
+            if isinstance(item, dict):
+                kind = item.get("kind")
+                if kind is None:
+                    raise ValueError("Intent dict missing required 'kind' field")
+                try:
+                    intent_cls = RegistryIntent.get_type(kind)
+                except KeyError as e:
+                    raise ValueError(str(e)) from e
+                result.append(intent_cls.model_validate(item))
+            elif isinstance(item, ModelRegistryIntent):
+                result.append(item)
+            else:
+                raise ValueError(
+                    f"Intent must be dict or ModelRegistryIntent, got {type(item).__name__}"
+                )
+        return tuple(result)
+
+    @property
+    def has_intents(self) -> bool:
+        """Check if the result contains any intents.
+
+        Returns:
+            True if intents tuple is non-empty, False otherwise.
+
+        Example:
+            >>> ModelReducerExecutionResult.empty().has_intents
+            False
+            >>> result = ModelReducerExecutionResult(
+            ...     state=ModelReducerState.initial(),
+            ...     intents=(some_intent,),
+            ... )
+            >>> result.has_intents
+            True
+
+        .. versionadded:: 0.7.0
+        """
+        return len(self.intents) > 0
+
+    @property
+    def intent_count(self) -> int:
+        """Get the number of intents in the result.
+
+        Returns:
+            Number of intents in the intents tuple.
+
+        Example:
+            >>> ModelReducerExecutionResult.empty().intent_count
+            0
+
+        .. versionadded:: 0.7.0
+        """
+        return len(self.intents)
+
+    @classmethod
+    def empty(cls) -> ModelReducerExecutionResult:
+        """Create an empty result with initial state and no intents.
+
+        Use this factory when the reducer determines no action is needed
+        (e.g., duplicate event, filtered event).
+
+        Returns:
+            ModelReducerExecutionResult with initial state and empty intents.
+
+        Example:
+            >>> result = ModelReducerExecutionResult.empty()
+            >>> result.state.processed_node_ids
+            frozenset()
+            >>> result.intents
+            ()
+
+        .. versionadded:: 0.7.0
+        """
+        return cls(state=ModelReducerState.initial(), intents=())
+
+    @classmethod
+    def no_change(cls, state: ModelReducerState) -> ModelReducerExecutionResult:
+        """Create a result with existing state and no intents.
+
+        Use this factory when the reducer determines the event should be
+        filtered but state should be preserved (e.g., already processed node).
+
+        Args:
+            state: The current reducer state to preserve.
+
+        Returns:
+            ModelReducerExecutionResult with preserved state and empty intents.
+
+        Example:
+            >>> state = ModelReducerState(pending_registrations=5)
+            >>> result = ModelReducerExecutionResult.no_change(state)
+            >>> result.state.pending_registrations
+            5
+            >>> result.intents
+            ()
+
+        .. versionadded:: 0.7.0
+        """
+        return cls(state=state, intents=())
+
+    @classmethod
+    def with_intents(
+        cls,
+        state: ModelReducerState,
+        intents: Sequence[ModelRegistryIntent],
+    ) -> ModelReducerExecutionResult:
+        """Create a result with state and intents.
+
+        Args:
+            state: The updated reducer state.
+            intents: Sequence of registration intents to execute. Each intent
+                must inherit from ModelRegistryIntent and be registered with
+                RegistryIntent (e.g., ModelConsulRegistrationIntent,
+                ModelPostgresUpsertIntent). Will be converted to an immutable tuple.
+
+        Returns:
+            ModelReducerExecutionResult with the provided state and intents.
+
+        Example:
+            >>> state = ModelReducerState(pending_registrations=2)
+            >>> result = ModelReducerExecutionResult.with_intents(
+            ...     state=state,
+            ...     intents=[consul_intent, postgres_intent],
+            ... )
+            >>> result.intent_count
+            2
+
+        .. versionadded:: 0.7.0
+        """
+        return cls(state=state, intents=tuple(intents))
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context to check for pending work.
+
+        Returns True if the result contains any intents, indicating that
+        infrastructure operations need to be performed.
+
+        Warning:
+            This differs from typical Pydantic model behavior where ``bool(model)``
+            always returns ``True`` for any valid model instance. Here, ``bool(result)``
+            returns ``False`` for valid results with no intents.
+
+            Use ``result.has_intents`` for explicit, self-documenting code.
+            Use ``result is not None`` if you need to check model existence.
+
+        Returns:
+            True if intents tuple is non-empty, False otherwise.
+
+        Example:
+            >>> result_with_work = ModelReducerExecutionResult.with_intents(
+            ...     state=ModelReducerState.initial(),
+            ...     intents=(some_intent,),
+            ... )
+            >>> bool(result_with_work)
+            True
+
+            >>> result_no_work = ModelReducerExecutionResult.empty()
+            >>> bool(result_no_work)  # False even though model is valid!
+            False
+
+            >>> # Idiomatic usage
+            >>> if result_no_work:
+            ...     print("Has work to do")
+            ... else:
+            ...     print("No work needed")
+            No work needed
+
+        .. versionadded:: 0.7.0
+        """
+        return self.has_intents
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String showing state summary and intent count.
+
+        .. versionadded:: 0.7.0
+        """
+        processed = len(self.state.processed_node_ids)
+        pending = self.state.pending_registrations
+        return (
+            f"ModelReducerExecutionResult("
+            f"processed={processed}, "
+            f"pending={pending}, "
+            f"intents={self.intent_count})"
+        )
+
+
+__all__ = ["ModelReducerExecutionResult"]