omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_orchestrator/models/model_reducer_state.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Reducer state model for the registration orchestrator."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelReducerState(BaseModel):
+    """State model for the registration reducer.
+
+    This model captures the reducer's internal state between reductions.
+    The orchestrator treats this as an opaque container that it passes
+    to the reducer but does not inspect.
+
+    Attributes:
+        last_event_timestamp: ISO timestamp of the last processed event.
+        processed_node_ids: Set of node IDs that have been processed.
+        pending_registrations: Count of registrations awaiting confirmation.
+
+    Note:
+        This is a minimal placeholder. The actual reducer (OMN-889) may
+        extend this with additional state fields for deduplication,
+        rate limiting, or batching logic.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    last_event_timestamp: str | None = Field(
+        default=None,
+        description="ISO timestamp of the last processed event",
+    )
+    processed_node_ids: frozenset[UUID] = Field(
+        default_factory=frozenset,
+        description="Set of node IDs that have been processed",
+    )
+    pending_registrations: int = Field(
+        default=0,
+        ge=0,
+        description="Count of registrations awaiting confirmation",
+    )
+
+    @classmethod
+    def initial(cls) -> ModelReducerState:
+        """Create an initial empty state.
+
+        Returns:
+            A fresh ModelReducerState with default values.
+        """
+        return cls()
+
+
+__all__ = ["ModelReducerState"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_registration_intent.py

@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration intent type aliases for the registration orchestrator.
+
+This module provides type aliases that aggregate the individual intent and
+payload models into discriminated unions. These aliases enable type narrowing
+based on the `kind` field in intent models.
+
+IMPORTANT - Union Sync Requirements (OMN-1007):
+    This module defines explicit union types that MUST stay in sync with the
+    RegistryIntent in model_registry_intent.py. There are two parallel systems:
+
+    1. **RegistryIntent** (dynamic): Decorator-based registration for runtime
+       type resolution. Used by ModelReducerExecutionResult for deserialization.
+
+    2. **ModelRegistrationIntent** (static): Annotated union for Pydantic field
+       validation. Used by ProtocolEffect.execute_intent() and similar APIs.
+
+    When adding a new intent type, you MUST update BOTH:
+    - Register with @RegistryIntent.register("kind") on the model class
+    - Add the model to ModelRegistrationIntent union below
+
+    Use validate_union_registry_sync() in tests to verify consistency.
+
+    For function signatures, prefer ProtocolRegistrationIntent (duck-typed)
+    over ModelRegistrationIntent (union-typed) when possible.
+
+Design Note:
+    Rather than using a loose dict[str, JsonType] for payloads, we use
+    typed payload models that match the exact structure expected by each
+    infrastructure adapter. This follows the ONEX principle of "no Any types"
+    and provides compile-time validation of intent payloads.
+
+    The pattern uses Literal discriminators for the `kind` field, enabling
+    type narrowing in effect node handlers.
+
+Related:
+    - model_registry_intent.py: RegistryIntent and ModelRegistryIntent base
+    - protocols.py: ProtocolRegistrationIntent for duck-typed signatures
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_consul_intent_payload import (
+    ModelConsulIntentPayload,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_consul_registration_intent import (
+    ModelConsulRegistrationIntent,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_postgres_intent_payload import (
+    ModelPostgresIntentPayload,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_postgres_upsert_intent import (
+    ModelPostgresUpsertIntent,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.models.model_registry_intent import (
+    RegistryIntent,
+)
+
+# Type alias for intent payloads
+IntentPayload = ModelConsulIntentPayload | ModelPostgresIntentPayload
+
+# =============================================================================
+# Discriminated Union Definitions
+#
+# SYNC REQUIREMENT: These unions MUST stay in sync with RegistryIntent.
+# When adding a new intent type:
+#   1. Create model inheriting from ModelRegistryIntent
+#   2. Register with @RegistryIntent.register("kind")
+#   3. Add model to the union below
+#   4. Run validate_union_registry_sync() to verify
+# =============================================================================
+
+# Discriminated union of all intent types using Annotated pattern
+# This enables type narrowing based on the `kind` field
+# SYNC: Must include all types registered in RegistryIntent
+ModelRegistrationIntent = Annotated[
+    ModelConsulRegistrationIntent | ModelPostgresUpsertIntent,
+    Field(discriminator="kind"),
+]
+
+# Explicit list of intent model classes in the union
+# Used by validate_union_registry_sync() for verification
+_UNION_INTENT_TYPES: tuple[type, ...] = (
+    ModelConsulRegistrationIntent,
+    ModelPostgresUpsertIntent,
+)
+
+
+def validate_union_registry_sync() -> tuple[bool, list[str]]:
+    """Validate that ModelRegistrationIntent union matches RegistryIntent.
+
+    This function checks that:
+    1. All types in the union are registered in RegistryIntent
+    2. All types in RegistryIntent are included in the union
+
+    Use this in tests to catch sync issues early.
+
+    Returns:
+        Tuple of (is_valid, list of error messages).
+        If is_valid is True, error list is empty.
+
+    Example:
+        >>> is_valid, errors = validate_union_registry_sync()
+        >>> if not is_valid:
+        ...     for error in errors:
+        ...         print(f"ERROR: {error}")
+
+    .. versionadded:: 0.7.1
+        Created as part of OMN-1007 union sync fix.
+    """
+    errors: list[str] = []
+    registry_types = RegistryIntent.get_all_types()
+
+    # Check 1: All union types are registered
+    for union_type in _UNION_INTENT_TYPES:
+        # Get the kind from the class default
+        kind_default = getattr(union_type, "model_fields", {}).get("kind")
+        if kind_default is None:
+            errors.append(
+                f"Invalid union type '{union_type.__name__}': expected 'kind' field, got None"
+            )
+            continue
+
+        # Get the default value from the field
+        kind_value = kind_default.default
+        if kind_value not in registry_types:
+            errors.append(
+                f"Union type {union_type.__name__} (kind='{kind_value}') "
+                f"is not registered in RegistryIntent"
+            )
+        elif registry_types[kind_value] is not union_type:
+            errors.append(
+                f"Kind '{kind_value}' is registered to "
+                f"{registry_types[kind_value].__name__}, "
+                f"but union contains {union_type.__name__}"
+            )
+
+    # Check 2: All registered types are in union
+    union_type_set = set(_UNION_INTENT_TYPES)
+    for kind, registered_type in registry_types.items():
+        if registered_type not in union_type_set:
+            errors.append(
+                f"Registered type {registered_type.__name__} (kind='{kind}') "
+                f"is missing from ModelRegistrationIntent union. "
+                f"Add it to the union in model_registration_intent.py"
+            )
+
+    return len(errors) == 0, errors
+
+
+def get_union_intent_types() -> tuple[type, ...]:
+    """Get the tuple of intent model types in the ModelRegistrationIntent union.
+
+    Returns:
+        Tuple of intent model classes that are part of the union.
+
+    .. versionadded:: 0.7.1
+    """
+    return _UNION_INTENT_TYPES
+
+
+__all__ = [
+    "IntentPayload",
+    "ModelConsulIntentPayload",
+    "ModelConsulRegistrationIntent",
+    "ModelPostgresIntentPayload",
+    "ModelPostgresUpsertIntent",
+    "ModelRegistrationIntent",
+    "get_union_intent_types",
+    "validate_union_registry_sync",
+]

omnibase_infra/nodes/node_registration_orchestrator/models/model_registry_intent.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry-based intent model for dynamic type resolution.
+
+This module provides:
+- ModelRegistryIntent: Base model for all registration intents
+- RegistryIntent: Decorator-based registry for intent type discovery
+
+Design Pattern:
+    Instead of maintaining explicit union types like:
+        _IntentUnion = ModelConsulIntent | ModelPostgresIntent
+
+    Intent models self-register via decorator:
+        @RegistryIntent.register("consul")
+        class ModelConsulRegistrationIntent(ModelRegistryIntent): ...
+
+    The registry resolves types dynamically during Pydantic validation,
+    enabling new intent types to be added without modifying existing code.
+
+IMPORTANT - Union Sync Requirement (OMN-1007):
+    When adding a new intent type, you MUST update BOTH:
+
+    1. Register with @RegistryIntent.register("kind") decorator (this file)
+    2. Add the model to ModelRegistrationIntent union in model_registration_intent.py
+
+    The RegistryIntent enables dynamic type resolution for ModelReducerExecutionResult,
+    while ModelRegistrationIntent is a static discriminated union used for Pydantic
+    field type hints in protocols (e.g., ProtocolEffect.execute_intent).
+
+    Use validate_union_registry_sync() from model_registration_intent.py in tests
+    to verify the two systems stay in sync.
+
+Related:
+    - model_registration_intent.py: ModelRegistrationIntent discriminated union
+    - ProtocolRegistrationIntent: Protocol for duck-typed function signatures
+    - validate_union_registry_sync(): Test helper for sync validation
+    - OMN-1007: Union reduction refactoring
+"""
+
+from __future__ import annotations
+
+import threading
+import warnings
+from collections.abc import Callable
+from typing import ClassVar
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+
+class RegistryIntent:
+    """Registry for intent model types with decorator-based registration.
+
+    This registry enables dynamic type resolution for Pydantic validation
+    without requiring explicit union type definitions.
+
+    Example:
+        @RegistryIntent.register("consul")
+        class ModelConsulRegistrationIntent(ModelRegistryIntent):
+            kind: Literal["consul"] = "consul"
+            ...
+
+        # Later, resolve type from kind
+        intent_cls = RegistryIntent.get_type("consul")
+        intent = intent_cls.model_validate(data)
+
+    Thread Safety:
+        All registration and mutation operations are protected by a class-level
+        threading.Lock to ensure thread-safe access. Read operations (get_type,
+        get_all_types, is_registered) are atomic dictionary operations and safe
+        for concurrent access. The lock ensures that check-and-set operations
+        in register() are atomic, preventing race conditions.
+    """
+
+    _types: ClassVar[dict[str, type[ModelRegistryIntent]]] = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    @classmethod
+    def register(cls, kind: str) -> Callable[[type], type]:
+        """Decorator to register an intent model type.
+
+        Args:
+            kind: The intent kind identifier (e.g., "consul", "postgres").
+                  Must match the model's `kind` field value.
+
+        Returns:
+            Decorator function that registers the class and returns it unchanged.
+
+        Raises:
+            ValueError: If kind is already registered (prevents duplicates).
+
+        Example:
+            @RegistryIntent.register("consul")
+            class ModelConsulRegistrationIntent(ModelRegistryIntent):
+                kind: Literal["consul"] = "consul"
+                service_name: str
+                ...
+        """
+
+        def decorator(intent_cls: type) -> type:
+            # Thread-safe registration with atomic check-and-set
+            with cls._lock:
+                if kind in cls._types:
+                    context = ModelInfraErrorContext(
+                        transport_type=EnumInfraTransportType.RUNTIME,
+                        operation="register_intent",
+                        correlation_id=uuid4(),
+                    )
+                    raise ProtocolConfigurationError(
+                        f"Intent kind '{kind}' already registered to {cls._types[kind].__name__}. "
+                        f"Cannot register {intent_cls.__name__}.",
+                        context=context,
+                    )
+                cls._types[kind] = intent_cls
+            return intent_cls
+
+        return decorator
+
+    @classmethod
+    def get_type(cls, kind: str) -> type[ModelRegistryIntent]:
+        """Get the intent model class for a given kind.
+
+        Args:
+            kind: The intent kind identifier.
+
+        Returns:
+            The registered intent model class.
+
+        Raises:
+            KeyError: If kind is not registered.
+
+        Example:
+            intent_cls = RegistryIntent.get_type("consul")
+            intent = intent_cls.model_validate({"kind": "consul", ...})
+        """
+        if kind not in cls._types:
+            registered = ", ".join(sorted(cls._types.keys())) or "(none)"
+            raise KeyError(
+                f"Unknown intent kind '{kind}'. Registered kinds: {registered}"
+            )
+        return cls._types[kind]
+
+    @classmethod
+    def get_all_types(cls) -> dict[str, type[ModelRegistryIntent]]:
+        """Get all registered intent types.
+
+        Returns:
+            Dict mapping kind strings to intent model classes.
+
+        Example:
+            all_types = RegistryIntent.get_all_types()
+            for kind, intent_cls in all_types.items():
+                print(f"{kind}: {intent_cls.__name__}")
+        """
+        return dict(cls._types)
+
+    @classmethod
+    def is_registered(cls, kind: str) -> bool:
+        """Check if a kind is registered.
+
+        Args:
+            kind: The intent kind identifier.
+
+        Returns:
+            True if registered, False otherwise.
+
+        Example:
+            if RegistryIntent.is_registered("consul"):
+                intent_cls = RegistryIntent.get_type("consul")
+        """
+        return kind in cls._types
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered types.
+
+        Warning:
+            This method is intended for **testing purposes only**.
+            Calling it in production code will emit a warning.
+            It breaks the immutability guarantee after startup.
+
+        Thread Safety:
+            This method is protected by the class-level lock to ensure
+            thread-safe clearing of the registry.
+        """
+        warnings.warn(
+            "RegistryIntent.clear() is intended for testing only. "
+            "Do not use in production code.",
+            UserWarning,
+            stacklevel=2,
+        )
+        with cls._lock:
+            cls._types.clear()
+
+
+class ModelRegistryIntent(BaseModel):
+    """Base model for all registry-managed registration intents.
+
+    All concrete intent models MUST:
+    1. Inherit from this base class
+    2. Use @RegistryIntent.register("kind") decorator
+    3. Define kind as Literal["kind"] with matching default
+    4. Be frozen (immutable) for thread safety
+
+    This base class defines the common interface that all intents share,
+    enabling type-safe access to common fields without type narrowing.
+
+    Example:
+        @RegistryIntent.register("consul")
+        class ModelConsulRegistrationIntent(ModelRegistryIntent):
+            kind: Literal["consul"] = "consul"
+            service_name: str
+            ...
+
+    Attributes:
+        kind: Intent kind identifier used for type discrimination.
+        operation: The operation to perform (e.g., 'register', 'upsert', 'deregister').
+        node_id: The node ID this intent applies to.
+        correlation_id: Correlation ID for distributed tracing.
+
+    Related:
+        - RegistryIntent: Registration decorator and type lookup
+        - ProtocolRegistrationIntent: Protocol for duck-typed signatures
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    kind: str
+    """Intent kind identifier used for type discrimination."""
+
+    operation: str
+    """The operation to perform (e.g., 'register', 'upsert', 'deregister')."""
+
+    node_id: UUID
+    """The node ID this intent applies to."""
+
+    correlation_id: UUID
+    """Correlation ID for distributed tracing."""
+
+
+__all__ = [
+    "RegistryIntent",
+    "ModelRegistryIntent",
+]

omnibase_infra/nodes/node_registration_orchestrator/node.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Orchestrator - Declarative workflow coordinator.
+
+This orchestrator follows the ONEX declarative pattern:
+    - DECLARATIVE orchestrator driven by contract.yaml
+    - Zero custom routing logic - all behavior from workflow_definition
+    - Used for ONEX-compliant runtime execution via RuntimeHostProcess
+    - Pattern: "Contract-driven, handlers wired by registry"
+
+Extends NodeOrchestrator from omnibase_core for workflow-driven coordination.
+All workflow logic is 100% driven by contract.yaml, not Python code.
+
+Workflow Pattern:
+    1. Receive introspection event (consumed_events in contract)
+    2. Call reducer to compute intents (workflow_definition.execution_graph)
+    3. Execute intents via effect (workflow_definition.execution_graph)
+    4. Publish result events (published_events in contract)
+
+All workflow logic, retry policies, and result aggregation are handled
+by the NodeOrchestrator base class using contract.yaml configuration.
+
+Handler Routing:
+    Handler routing is defined declaratively in contract.yaml under
+    handler_routing section. The orchestrator does NOT contain custom
+    dispatch logic - the base class routes events based on:
+    - routing_strategy: "payload_type_match"
+    - handlers: mapping of event_model to handler_class
+
+    Handler routing is initialized by the RUNTIME (not this module) via
+    MixinHandlerRouting._init_handler_routing(), using the registry created
+    by RegistryInfraNodeRegistrationOrchestrator. This module only provides
+    the helper function _create_handler_routing_subcontract() for the runtime.
+
+Design Decisions:
+    - 100% Contract-Driven: All workflow logic in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: Workflow steps defined in execution_graph
+    - Retry at Base Class: NodeOrchestrator owns retry policy
+    - Contract-Driven Wiring: Handlers wired via handler_routing in contract.yaml
+    - Mixin-Based Routing: MixinHandlerRouting provides route_to_handlers()
+
+Coroutine Safety:
+    This orchestrator is NOT coroutine-safe. Each instance should handle one
+    workflow at a time. For concurrent workflows, create multiple instances.
+
+Related Modules:
+    - contract.yaml: Workflow definition, execution graph, and handler routing
+    - handlers/: Handler implementations (HandlerNodeIntrospected, etc.)
+    - registry/: RegistryInfraNodeRegistrationOrchestrator for handler wiring
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_orchestrator import NodeOrchestrator
+from omnibase_infra.models.routing import ModelRoutingSubcontract
+from omnibase_infra.runtime.contract_loaders import load_handler_routing_subcontract
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container import ModelONEXContainer
+
+logger = logging.getLogger(__name__)
+
+
+def _create_handler_routing_subcontract() -> ModelRoutingSubcontract:
+    """Load handler routing configuration from this node's contract.yaml.
+
+    Thin wrapper around the shared utility load_handler_routing_subcontract()
+    that provides the contract path for this node. This maintains the existing
+    function signature for internal callers while delegating to the shared
+    implementation.
+
+    Part of OMN-1316: Refactored to use shared handler routing loader utility.
+
+    Returns:
+        ModelRoutingSubcontract with entries mapping event models to handlers.
+
+    Raises:
+        ProtocolConfigurationError: If contract.yaml does not exist, contains invalid
+            YAML syntax, is empty, or handler_routing section is missing.
+    """
+    contract_path = Path(__file__).parent / "contract.yaml"
+    return load_handler_routing_subcontract(contract_path)
+
+
+class NodeRegistrationOrchestrator(NodeOrchestrator):
+    """Declarative orchestrator for node registration workflow.
+
+    All behavior is defined in contract.yaml - no custom logic here.
+    Handler routing is driven entirely by the contract and initialized
+    via MixinHandlerRouting from the base class.
+
+    Example YAML Contract (contract.yaml format):
+        ```yaml
+        handler_routing:
+          routing_strategy: "payload_type_match"
+          handlers:
+            - event_model:
+                name: "ModelNodeIntrospectionEvent"
+                module: "omnibase_infra.models.registration..."
+              handler:
+                name: "HandlerNodeIntrospected"
+                module: "omnibase_infra.nodes...handlers..."
+            - event_model:
+                name: "ModelRuntimeTick"
+                module: "omnibase_infra.runtime.models..."
+              handler:
+                name: "HandlerRuntimeTick"
+                module: "omnibase_infra.nodes...handlers..."
+
+        workflow_coordination:
+          workflow_definition:
+            workflow_metadata:
+              workflow_name: node_registration
+              workflow_version: {major: 1, minor: 0, patch: 0}
+              execution_mode: sequential
+              description: "Node registration workflow"
+
+            execution_graph:
+              nodes:
+                - node_id: "compute_intents"
+                  node_type: REDUCER_GENERIC
+                  description: "Compute registration intents"
+                - node_id: "execute_consul"
+                  node_type: EFFECT_GENERIC
+                  description: "Register with Consul"
+                - node_id: "execute_postgres"
+                  node_type: EFFECT_GENERIC
+                  description: "Register in PostgreSQL"
+
+            coordination_rules:
+              parallel_execution_allowed: false
+              failure_recovery_strategy: retry
+              max_retries: 3
+              timeout_ms: 30000
+        ```
+
+    Note on Handler Routing Field Names:
+        The contract.yaml uses a nested structure with ``event_model.name`` and
+        ``handler.name``, but ModelRoutingEntry uses flat fields:
+
+        - ``routing_key``: Corresponds to ``event_model.name``
+        - ``handler_key``: The handler's adapter ID in ServiceHandlerRegistry
+          (e.g., "handler-node-introspected"), NOT the class name
+
+        See ``_create_handler_routing_subcontract()`` for the translation.
+
+    Usage:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+
+        # Create and initialize
+        container = ModelONEXContainer()
+        orchestrator = NodeRegistrationOrchestrator(container)
+
+        # Workflow definition loaded from contract.yaml by runtime
+        # Handler routing initialized via runtime using registry factory
+        # Process input
+        result = await orchestrator.process(input_data)
+        ```
+
+    Handler Routing:
+        Handler routing is initialized by the runtime, not by this class.
+        The runtime uses RegistryInfraNodeRegistrationOrchestrator.create_registry()
+        to create the handler registry and calls _init_handler_routing() on
+        the orchestrator instance.
+
+    Runtime Initialization:
+        Handler routing is initialized by RuntimeHostProcess, not by this class.
+        The runtime performs the following sequence:
+
+        1. Creates handler registry via
+           RegistryInfraNodeRegistrationOrchestrator.create_registry()
+        2. Creates handler routing subcontract via
+           _create_handler_routing_subcontract()
+        3. Calls orchestrator._init_handler_routing(subcontract, registry)
+
+        This separation ensures the orchestrator remains purely declarative
+        with no custom initialization logic.
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize with container dependency injection.
+
+        Args:
+            container: ONEX dependency injection container.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeRegistrationOrchestrator"]