omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/node_registration_reducer/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Reducer - FSM-driven declarative reducer for node registration."""
+
+from omnibase_infra.nodes.node_registration_reducer.models import ModelValidationResult
+from omnibase_infra.nodes.node_registration_reducer.node import NodeRegistrationReducer
+from omnibase_infra.nodes.node_registration_reducer.registry import (
+    RegistryInfraNodeRegistrationReducer,
+)
+
+__all__ = [
+    "ModelValidationResult",
+    "NodeRegistrationReducer",
+    "RegistryInfraNodeRegistrationReducer",
+]

omnibase_infra/nodes/node_registration_reducer/contract.yaml

@@ -0,0 +1,301 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# ONEX Node Contract - Registration Reducer Node
+#
+# This reducer follows the pure function pattern for node registration workflows:
+#   reduce(state, event) -> ModelReducerOutput[state + intents]
+#
+# The FSM defines state transitions for the registration lifecycle:
+#   idle -> pending -> partial -> complete
+#                  \           \
+#                   -> failed <-
+#
+# All state transition logic is driven by this contract.
+# =============================================================================
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "1.0.0"
+name: "node_registration_reducer"
+node_type: "REDUCER_GENERIC"
+# Enum Usage (CLAUDE.md reference):
+#   - node_type uses EnumNodeOutputType.REDUCER for validation
+#   - Reducer outputs are PROJECTION type (state + intents) via EnumNodeOutputType
+#   - Incoming messages are routed via EnumMessageCategory (EVENT/COMMAND)
+#   - PROJECTION exists only in EnumNodeOutputType and is only valid for REDUCER nodes
+#   - See: docs/decisions/adr-enum-message-category-vs-node-output-type.md
+description: "Pure reducer for node registration workflow - processes introspection events and emits registration intents for Consul and PostgreSQL backends."
+input_model:
+  name: "ModelReducerInput"
+  module: "omnibase_core.models.reducer.model_reducer_input"
+  description: "Reducer input containing introspection event and trigger."
+output_model:
+  name: "ModelReducerOutput"
+  module: "omnibase_core.models.reducer.model_reducer_output"
+  description: "Reducer output containing new state and registration intents."
+# FSM State Machine Definition
+# ============================
+# The registration reducer uses an FSM to manage the registration lifecycle.
+# This is the SINGLE SOURCE OF TRUTH for all state transition logic.
+#
+# State Diagram:
+#   +-------+   introspection   +---------+
+#   | idle  | ----------------> | pending |
+#   +-------+                   +---------+
+#      ^                         |       |
+#      |       consul confirmed  |       | postgres confirmed
+#      |       (first)          v       v (first)
+#      |                  +---------+
+#      |                  | partial |
+#      |                  +---------+
+#      |                    |       |
+#      |   remaining        |       | error received
+#      |   confirmed        v       v
+#      |              +---------+ +---------+
+#      +---reset------| complete| | failed  |---reset---+
+#                     +---------+ +---------+           |
+#                                                       v
+#                                                 +-------+
+#                                                 | idle  |
+#                                                 +-------+
+#
+state_machine:
+  state_machine_name: "registration_fsm"
+  initial_state: "idle"
+  states:
+    - state_name: "idle"
+      description: "Initial state - waiting for introspection event"
+      entry_actions: []
+      exit_actions: []
+      required_data: []
+    - state_name: "pending"
+      description: "Registration initiated - waiting for backend confirmations"
+      entry_actions:
+        - "emit_consul_intent"
+        - "emit_postgres_intent"
+      exit_actions: []
+      required_data:
+        - "node_id"
+        - "correlation_id"
+    - state_name: "partial"
+      description: "One backend confirmed - waiting for remaining confirmation"
+      entry_actions: []
+      exit_actions: []
+      required_data:
+        - "node_id"
+        - "correlation_id"
+    - state_name: "complete"
+      description: "Both backends confirmed - registration successful"
+      is_terminal: false # Can be reset for re-registration
+      entry_actions: []
+      exit_actions: []
+      required_data:
+        - "node_id"
+    - state_name: "failed"
+      description: "Registration failed - recoverable via reset"
+      is_terminal: false # Can be reset for retry
+      entry_actions: []
+      exit_actions: []
+      required_data:
+        - "failure_reason"
+  transitions:
+    # idle -> pending: On introspection event
+    - from_state: "idle"
+      to_state: "pending"
+      trigger: "introspection_received"
+      description: "Start registration on introspection event"
+      conditions:
+        - expression: "node_id is_present"
+          required: true
+        - expression: "node_type is_valid"
+          required: true
+      actions:
+        - action_name: "build_consul_intent"
+          action_type: "intent_emission"
+        - action_name: "build_postgres_intent"
+          action_type: "intent_emission"
+    # pending -> partial: On first confirmation
+    - from_state: "pending"
+      to_state: "partial"
+      trigger: "consul_confirmed"
+      description: "Consul registration confirmed"
+      actions:
+        - action_name: "mark_consul_confirmed"
+          action_type: "state_update"
+    - from_state: "pending"
+      to_state: "partial"
+      trigger: "postgres_confirmed"
+      description: "PostgreSQL registration confirmed"
+      actions:
+        - action_name: "mark_postgres_confirmed"
+          action_type: "state_update"
+    # pending -> failed: On error
+    - from_state: "pending"
+      to_state: "failed"
+      trigger: "error_received"
+      description: "Registration failed from pending state"
+      actions:
+        - action_name: "record_failure"
+          action_type: "state_update"
+    # partial -> complete: On second confirmation
+    - from_state: "partial"
+      to_state: "complete"
+      trigger: "consul_confirmed"
+      description: "Consul confirmed after postgres - registration complete"
+      conditions:
+        - expression: "postgres_confirmed is_true"
+          required: true
+    - from_state: "partial"
+      to_state: "complete"
+      trigger: "postgres_confirmed"
+      description: "PostgreSQL confirmed after consul - registration complete"
+      conditions:
+        - expression: "consul_confirmed is_true"
+          required: true
+    # partial -> failed: On error
+    - from_state: "partial"
+      to_state: "failed"
+      trigger: "error_received"
+      description: "Registration failed from partial state"
+      actions:
+        - action_name: "record_failure"
+          action_type: "state_update"
+    # Reset transitions: failed/complete -> idle
+    - from_state: "failed"
+      to_state: "idle"
+      trigger: "reset"
+      description: "Reset from failed state for retry"
+      actions:
+        - action_name: "clear_state"
+          action_type: "state_update"
+    - from_state: "complete"
+      to_state: "idle"
+      trigger: "reset"
+      description: "Reset from complete state for re-registration"
+      actions:
+        - action_name: "clear_state"
+          action_type: "state_update"
+    # Validation failure: idle -> failed
+    - from_state: "idle"
+      to_state: "failed"
+      trigger: "validation_failed"
+      description: "Event validation failed"
+      actions:
+        - action_name: "record_validation_failure"
+          action_type: "state_update"
+  # NOTE: persistence_enabled controls FSM intent emission (implemented in omnibase_core
+  # fsm_executor.py). When true, FSM transitions emit "persist_state" intents. However,
+  # the generic intent dispatch handler for these intents is NOT YET IMPLEMENTED.
+  # Current workaround: Handlers call RegistrationProjector.persist_state_transition()
+  # directly instead of relying on intent-based persistence. This flag is kept true
+  # for forward compatibility when generic state persistence dispatch is implemented.
+  # See: omnibase_core/utils/fsm_executor.py:168 for intent emission logic.
+  persistence_enabled: true
+  terminal_states: []
+  # Note: complete and failed are NOT true terminals - they can reset to idle
+  # This list is empty because all states can transition (via reset)
+# Intent Emission Configuration
+# ============================
+# The reducer emits intents for Effect layer execution.
+# These intents are NOT executed by the reducer - they are returned
+# in the ModelReducerOutput for the Runtime to publish.
+intent_emission:
+  enabled: true
+  intents:
+    - intent_type: "consul.register"
+      target_pattern: "consul://service/{service_name}"
+      payload_model: "ModelPayloadConsulRegister"
+      payload_module: "omnibase_infra.nodes.reducers.models.model_payload_consul_register"
+      description: "Register node with Consul service discovery"
+    - intent_type: "postgres.upsert_registration"
+      target_pattern: "postgres://node_registrations/{node_id}"
+      payload_model: "ModelPayloadPostgresUpsertRegistration"
+      payload_module: "omnibase_infra.nodes.reducers.models.model_payload_postgres_upsert_registration"
+      description: "Upsert node registration record in PostgreSQL"
+# State Model Configuration
+# =========================
+# The reducer uses ModelRegistrationState for immutable state management.
+state_model:
+  name: "ModelRegistrationState"
+  module: "omnibase_infra.nodes.reducers.models.model_registration_state"
+  description: "Immutable state model for pure reducer pattern"
+# Validation Configuration
+# ========================
+# Event validation rules applied before state transitions.
+validation:
+  enabled: true
+  rules:
+    - field: "node_id"
+      required: true
+      error_code: "missing_node_id"
+      error_message: "node_id is required for registration identity"
+    - field: "node_type"
+      required: true
+      valid_values:
+        - "effect"
+        - "compute"
+        - "reducer"
+        - "orchestrator"
+      error_code: "missing_node_type"
+      invalid_error_code: "invalid_node_type"
+      error_message: "node_type is required for service categorization"
+# Performance Configuration
+# =========================
+# Performance thresholds for monitoring.
+# Values can be overridden via environment variables.
+performance:
+  thresholds:
+    reduce_ms:
+      default: 300.0
+      env_var: "ONEX_PERF_THRESHOLD_REDUCE_MS"
+      description: "Target processing time for reduce() method"
+    intent_build_ms:
+      default: 50.0
+      env_var: "ONEX_PERF_THRESHOLD_INTENT_BUILD_MS"
+      description: "Target processing time for intent building"
+    idempotency_check_ms:
+      default: 1.0
+      env_var: "ONEX_PERF_THRESHOLD_IDEMPOTENCY_CHECK_MS"
+      description: "Target processing time for idempotency check"
+# Idempotency Configuration
+# =========================
+# The reducer supports idempotent event processing via event_id tracking.
+idempotency:
+  enabled: true
+  strategy: "event_id_tracking"
+  derivation: "deterministic_hash"
+  hash_fields:
+    - "node_id"
+    - "node_type"
+    - "timestamp"
+  description: "Skip duplicate events based on event_id or derived hash"
+# Dependencies
+# ============
+dependencies:
+  - name: "container"
+    type: "ModelONEXContainer"
+    module: "omnibase_core.models.container.model_onex_container"
+    description: "ONEX dependency injection container"
+# Health Check
+# ============
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+# Metadata
+# ========
+metadata:
+  author: "OmniNode Team"
+  created: "2025-12-28"
+  updated: "2026-01-06"
+  tags:
+    - "reducer"
+    - "registration"
+    - "fsm"
+    - "pure-function"
+    - "mvp"
+  related_tickets:
+    - "OMN-889"
+    - "OMN-1104"
+    - "OMN-1263" # Pre-existing test failures and integration test coverage tracking

omnibase_infra/nodes/node_registration_reducer/models/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for NodeRegistrationReducer.
+
+This module exports models used by the NodeRegistrationReducer (FSM-driven pattern).
+
+Available Models:
+    - ModelValidationResult: Validation result with error details
+    - ModelRegistrationState: Immutable state for reducer FSM
+    - ModelRegistrationConfirmation: Confirmation event from Effect layer
+    - ModelPayloadConsulRegister: Payload for Consul registration intents
+    - ModelPayloadPostgresUpsertRegistration: Payload for PostgreSQL upsert intents
+"""
+
+# Node-specific model
+from omnibase_infra.nodes.node_registration_reducer.models.model_validation_result import (
+    ModelValidationResult,
+    ValidationErrorCode,
+    ValidationResult,
+)
+
+# Re-export shared models from the reducers module for convenience
+from omnibase_infra.nodes.reducers.models import (
+    ModelPayloadConsulRegister,
+    ModelPayloadPostgresUpsertRegistration,
+    ModelRegistrationConfirmation,
+    ModelRegistrationState,
+)
+
+__all__ = [
+    "ModelPayloadConsulRegister",
+    "ModelPayloadPostgresUpsertRegistration",
+    "ModelRegistrationConfirmation",
+    "ModelRegistrationState",
+    "ModelValidationResult",
+    "ValidationErrorCode",
+    "ValidationResult",
+]

omnibase_infra/nodes/node_registration_reducer/models/model_validation_result.py

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validation result model for registration reducer.
+
+This model represents the result of event validation with detailed error
+information. It follows the ONEX pattern of using sentinel values instead
+of nullable unions to minimize union count (OMN-1004).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+# Validation error codes for distinct error identification
+ValidationErrorCode = Literal[
+    "missing_node_id",
+    "missing_node_type",
+    "invalid_node_type",
+]
+
+# Sentinel value for "not set" state
+_SENTINEL_STR: str = ""
+
+
+class ModelValidationResult(BaseModel):
+    """Result of event validation with detailed error information.
+
+    This Pydantic model follows ONEX requirements for Pydantic-based
+    data structures with sentinel values instead of nullable unions
+    (OMN-1004).
+
+    Sentinel Values:
+        - Empty string ("") for field_name and error_message means "not set"
+        - None for error_code (unavoidable for Literal type safety)
+        - Use ``has_field_name``, ``has_error_message`` to check
+
+    Input Normalization:
+        Constructors accept ``None`` for string fields and convert to sentinel
+        for developer convenience. This is NOT backwards compatibility (per
+        CLAUDE.md policy) - it is input normalization that may be removed in
+        future versions without notice.
+
+    Attributes:
+        is_valid: Whether the event passed validation.
+        error_code: Distinct code identifying the validation failure (if any).
+        field_name: Name of the field that failed validation. Empty string if not set.
+        error_message: Human-readable error message for logging. Empty string if not set.
+
+    .. versionchanged:: 0.7.0
+        Refactored to use sentinel values for string fields (OMN-1004).
+        Extracted to separate file (OMN-1104).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    is_valid: bool
+    error_code: ValidationErrorCode | None = None
+    field_name: str = _SENTINEL_STR
+    error_message: str = _SENTINEL_STR
+
+    # ---- Validators for None-to-Sentinel Conversion ----
+    @field_validator("field_name", "error_message", mode="before")
+    @classmethod
+    def _convert_none_to_str_sentinel(cls, v: object) -> str:
+        """Convert None to empty string sentinel for input normalization."""
+        if v is None:
+            return _SENTINEL_STR
+        if isinstance(v, str):
+            return v
+        return str(v)
+
+    # ---- Sentinel Check Properties ----
+    @property
+    def has_field_name(self) -> bool:
+        """Check if field_name is set (not empty string)."""
+        return self.field_name != _SENTINEL_STR
+
+    @property
+    def has_error_message(self) -> bool:
+        """Check if error_message is set (not empty string)."""
+        return self.error_message != _SENTINEL_STR
+
+    @classmethod
+    def success(cls) -> ModelValidationResult:
+        """Create a successful validation result."""
+        return cls(is_valid=True)
+
+    @classmethod
+    def failure(
+        cls,
+        error_code: ValidationErrorCode,
+        field_name: str,
+        error_message: str,
+    ) -> ModelValidationResult:
+        """Create a failed validation result with error details."""
+        return cls(
+            is_valid=False,
+            error_code=error_code,
+            field_name=field_name,
+            error_message=error_message,
+        )
+
+
+# Convenience alias (not backwards compatibility - may be removed without notice)
+ValidationResult = ModelValidationResult
+
+__all__ = [
+    "ModelValidationResult",
+    "ValidationErrorCode",
+    "ValidationResult",
+]

omnibase_infra/nodes/node_registration_reducer/node.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration 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.
+
+FSM Pattern:
+    1. Receive introspection event (trigger: introspection_received)
+    2. FSM transitions idle -> pending (emits registration intents)
+    3. Receive confirmation events (triggers: consul_confirmed, postgres_confirmed)
+    4. FSM transitions pending -> partial -> complete
+    5. On errors, FSM transitions to failed
+    6. Reset events allow retry (failed/complete -> idle)
+
+All state transitions, intent emission, and validation are handled by the
+NodeReducer base class using contract.yaml FSM configuration.
+
+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/: Validation result and state models
+    - registry/: Dependency injection registry
+
+Testing Notes:
+    - Unit tests: tests/unit/nodes/node_registration_reducer/
+    - Integration tests: REQUIRED before production (OMN-1263)
+        WARNING: This reducer MUST NOT be deployed to production without
+        the following integration tests implemented and passing:
+        * Intent emission through RuntimeHostProcess
+        * End-to-end registration workflow with Consul/PostgreSQL mocks
+        * FSM state persistence via RegistrationProjector
+    - Test coverage matrix: docs/decisions/adr-any-type-pydantic-workaround.md
+
+Tracking:
+    - OMN-1104: Declarative reducer refactoring
+    - OMN-1263: Integration test coverage (https://linear.app/omninode/issue/OMN-1263)
+        Pre-production blocker - prioritize before deployment
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_reducer import NodeReducer
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+    # Import needed for string annotation in class definition (NodeReducer["ModelRegistrationState", ...])
+    from omnibase_infra.nodes.node_registration_reducer.models.model_registration_state import (
+        ModelRegistrationState,
+    )
+
+
+class NodeRegistrationReducer(
+    NodeReducer["ModelRegistrationState", "ModelRegistrationState"]
+):
+    """Registration reducer - FSM state transitions driven by contract.yaml.
+
+    This reducer processes node registration workflows by:
+    1. Receiving introspection events (via process() method)
+    2. Executing FSM transitions defined in contract.yaml
+    3. Emitting registration intents for Consul and PostgreSQL
+    4. Processing confirmation events to complete registration
+
+    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: registration_fsm
+          initial_state: idle
+          states:
+            - state_name: idle
+              description: "Waiting for introspection event"
+            - state_name: pending
+              description: "Registration initiated"
+              entry_actions:
+                - emit_consul_intent
+                - emit_postgres_intent
+            - state_name: partial
+              description: "One backend confirmed"
+            - state_name: complete
+              description: "Registration successful"
+            - state_name: failed
+              description: "Registration failed"
+          transitions:
+            - from_state: idle
+              to_state: pending
+              trigger: introspection_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 = NodeRegistrationReducer(container)
+
+        # Process input via FSM
+        input_data = ModelReducerInput(
+            data=introspection_event,
+            reduction_type=EnumReductionType.MERGE,
+            metadata=ModelReducerMetadata(trigger="introspection_received"),
+        )
+        result = await reducer.process(input_data)
+        ```
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the reducer.
+
+        Args:
+            container: ONEX dependency injection container
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeRegistrationReducer"]

omnibase_infra/nodes/node_registration_reducer/registry/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry module for NodeRegistrationReducer."""
+
+from omnibase_infra.nodes.node_registration_reducer.registry.registry_infra_node_registration_reducer import (
+    RegistryInfraNodeRegistrationReducer,
+)
+
+__all__ = ["RegistryInfraNodeRegistrationReducer"]