omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_registration_reducer/registry/registry_infra_node_registration_reducer.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for NodeRegistrationReducer dependencies.
+
+This registry provides dependency injection configuration for the
+NodeRegistrationReducer node, following ONEX container-based DI pattern.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.nodes.node_registration_reducer.node import (
+        NodeRegistrationReducer,
+    )
+
+
+class RegistryInfraNodeRegistrationReducer:
+    """Registry for NodeRegistrationReducer dependency injection.
+
+    Why a class instead of a function?
+        ONEX registry pattern (CLAUDE.md) requires registry classes with
+        the naming convention ``RegistryInfra<NodeName>``. This enables:
+
+        - **Future extension**: Additional factory methods can be added
+          (e.g., ``create_reducer_with_cache()``, ``create_test_reducer()``)
+        - **Service registry resolution**: Classes can be registered in the
+          ONEX service registry for container-based resolution
+        - **Consistent pattern**: All node registries follow the same class-based
+          structure, making the codebase predictable and navigable
+        - **Container lifecycle management**: The registry can implement caching,
+          scoping, or other lifecycle behaviors in the future
+
+    Provides factory methods for creating NodeRegistrationReducer instances
+    with properly configured dependencies from the ONEX container.
+
+    Usage:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_registration_reducer.registry import (
+            RegistryInfraNodeRegistrationReducer,
+        )
+
+        # Create container and registry
+        container = ModelONEXContainer()
+        registry = RegistryInfraNodeRegistrationReducer(container)
+
+        # Create reducer instance
+        reducer = registry.create_reducer()
+
+        # Use reducer
+        result = await reducer.process(input_data)
+        ```
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the registry with ONEX container.
+
+        Args:
+            container: ONEX dependency injection container
+        """
+        self._container = container
+
+    def create_reducer(self) -> NodeRegistrationReducer:
+        """Create a NodeRegistrationReducer instance.
+
+        Returns:
+            Configured NodeRegistrationReducer instance.
+        """
+        from omnibase_infra.nodes.node_registration_reducer.node import (
+            NodeRegistrationReducer,
+        )
+
+        return NodeRegistrationReducer(self._container)
+
+
+__all__ = ["RegistryInfraNodeRegistrationReducer"]

omnibase_infra/nodes/node_registration_storage_effect/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Storage Effect - Capability-oriented storage node.
+
+This package provides the NodeRegistrationStorageEffect, a capability-oriented
+effect node for registration storage operations.
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+    Named by capability (registration.storage), not by specific backend implementation.
+    Supports pluggable backends through the handler protocol.
+
+Capabilities:
+    - registration.storage: Store, query, update, delete registration records
+    - registration.storage.query: Query with filtering and pagination
+    - registration.storage.upsert: Idempotent insert/update operations
+    - registration.storage.delete: Delete by node ID
+    - registration.storage.health: Backend health checks
+
+Available Exports:
+    - NodeRegistrationStorageEffect: The declarative effect node
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_registration_storage_effect import (
+    ...     NodeRegistrationStorageEffect,
+    ... )
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeRegistrationStorageEffect(container)
+
+Related Modules:
+    - models: Pydantic models for storage operations
+    - protocols: Handler protocol for pluggable backends
+    - registry: Dependency injection registration
+"""
+
+from .node import NodeRegistrationStorageEffect
+
+__all__ = ["NodeRegistrationStorageEffect"]

omnibase_infra/nodes/node_registration_storage_effect/contract.yaml

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeRegistrationStorageEffect
+#
+# Capability-oriented effect node for registration storage operations.
+# Named by capability ("registration.storage"), not by vendor (e.g., PostgreSQL).
+# Principle: "I'm interested in what you do, not what you are"
+#
+# This contract defines the interface for storage operations with pluggable backends.
+# Handlers implementing ProtocolRegistrationPersistence can be swapped without
+# changing the node interface.
+# Contract identifiers
+name: "node_registration_storage_effect"
+contract_name: "node_registration_storage_effect"
+node_name: "node_registration_storage_effect"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 1
+  minor: 0
+  patch: 0
+# Node type
+node_type: "EFFECT_GENERIC"
+# Description
+description: >
+  Capability-oriented effect node for registration storage operations. Handles store, query, update, and delete operations for node registrations with pluggable backend handlers (e.g., PostgreSQL).
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelStorageQuery"
+  module: "omnibase_infra.nodes.node_registration_storage_effect.models"
+  description: "Input model for storage query operations."
+output_model:
+  name: "ModelStorageResult"
+  module: "omnibase_infra.nodes.node_registration_storage_effect.models"
+  description: "Output model containing query results and metadata."
+# Capability declaration (capability-oriented naming)
+capabilities:
+  - name: "registration.storage"
+    description: "Store, query, update, and delete node registration records"
+    version: "1.0.0"
+  - name: "registration.storage.query"
+    description: "Query registration records with filtering and pagination"
+  - name: "registration.storage.upsert"
+    description: "Insert or update registration records idempotently"
+  - name: "registration.storage.delete"
+    description: "Delete registration records by node ID"
+  - name: "registration.storage.health"
+    description: "Health check for storage backend connectivity"
+# IO operations (EFFECT node specific)
+# Note: correlation_id is optional (UUID | None) for all operations.
+# If not provided, implementations should generate one for tracing.
+io_operations:
+  - operation: "store_registration"
+    description: "Store a new registration record or update existing"
+    input_fields:
+      - record: "ModelRegistrationRecord"
+      - correlation_id: "UUID | None"
+    output_fields:
+      - result: "ModelUpsertResult"
+    idempotent: true
+  - operation: "query_registrations"
+    description: "Query registration records with optional filters"
+    input_fields:
+      - query: "ModelStorageQuery"
+      - correlation_id: "UUID | None"
+    output_fields:
+      - result: "ModelStorageResult"
+    idempotent: true
+  - operation: "update_registration"
+    description: "Update specific fields of a registration record"
+    input_fields:
+      - node_id: "UUID"
+      - updates: "ModelRegistrationUpdate"
+      - correlation_id: "UUID | None"
+    output_fields:
+      - result: "ModelUpsertResult"
+    idempotent: true
+  - operation: "delete_registration"
+    description: "Delete a registration record by node ID"
+    input_fields:
+      - node_id: "UUID"
+      - correlation_id: "UUID | None"
+    output_fields:
+      - success: "bool"
+    idempotent: true
+  - operation: "health_check"
+    description: "Check storage backend health and connectivity"
+    input_fields:
+      - correlation_id: "UUID | None"
+    output_fields:
+      - result: "ModelStorageHealthCheckResult"
+    idempotent: true
+# Database schema definition (for PostgreSQL backend)
+database_schema:
+  table_name: "node_registrations"
+  columns:
+    - name: "node_id"
+      type: "UUID"
+      constraints: "PRIMARY KEY"
+      description: "Unique identifier for the registered node"
+    - name: "node_type"
+      type: "VARCHAR(64)"
+      constraints: "NOT NULL"
+      description: "Node archetype (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)"
+    - name: "node_version"
+      type: "VARCHAR(32)"
+      constraints: "NOT NULL"
+      description: "Semantic version of the node"
+    - name: "capabilities"
+      type: "JSONB"
+      constraints: "NOT NULL DEFAULT '[]'"
+      description: "Array of capability identifiers the node provides"
+    - name: "endpoints"
+      type: "JSONB"
+      constraints: "NOT NULL DEFAULT '{}'"
+      description: "Map of endpoint names to URLs"
+    - name: "metadata"
+      type: "JSONB"
+      constraints: "NOT NULL DEFAULT '{}'"
+      description: "Additional key-value metadata"
+    - name: "created_at"
+      type: "TIMESTAMPTZ"
+      constraints: "NOT NULL DEFAULT NOW()"
+      description: "Timestamp when the registration was created"
+    - name: "updated_at"
+      type: "TIMESTAMPTZ"
+      constraints: "NOT NULL DEFAULT NOW()"
+      description: "Timestamp when the registration was last updated"
+  indexes:
+    - name: "idx_node_registrations_type"
+      columns: ["node_type"]
+      description: "Index for filtering by node type"
+    - name: "idx_node_registrations_updated"
+      columns: ["updated_at"]
+      description: "Index for ordering by recency"
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "protocol_registration_storage_handler"
+    type: "protocol"
+    class_name: "ProtocolRegistrationPersistence"
+    module: "omnibase_infra.nodes.node_registration_storage_effect.protocols"
+    description: "Protocol for registration storage backends (e.g., PostgreSQL, mock)"
+    pluggable: true
+    implementations:
+      - name: "postgresql"
+        description: "PostgreSQL implementation for registration storage"
+      - name: "mock"
+        description: "Mock implementation for testing and development"
+# Handler routing (for pluggable backends)
+handler_routing:
+  routing_strategy: "handler_type_match"
+  default_handler: "postgresql"
+  handlers:
+    - handler_type: "postgresql"
+      handler:
+        name: "HandlerRegistrationStoragePostgres"
+        module: "omnibase_infra.handlers.registration_storage.handler_registration_storage_postgres"
+      description: "PostgreSQL storage handler"
+    - handler_type: "mock"
+      handler:
+        name: "HandlerRegistrationStorageMock"
+        module: "omnibase_infra.handlers.registration_storage.handler_registration_storage_mock"
+      description: "Mock storage handler for testing"
+# Error handling configuration
+error_handling:
+  retry_policy:
+    max_retries: 3
+    initial_delay_ms: 100
+    max_delay_ms: 5000
+    exponential_base: 2
+    retry_on:
+      - "InfraConnectionError"
+      - "InfraTimeoutError"
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout_ms: 60000
+  error_types:
+    - name: "StorageConnectionError"
+      description: "Unable to connect to storage backend"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "StorageTimeoutError"
+      description: "Storage operation timed out"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "RecordNotFoundError"
+      description: "Registration record not found"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "ValidationError"
+      description: "Input validation failed"
+      recoverable: false
+      retry_strategy: "none"
+# Health check configuration
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+  timeout_ms: 5000
+  checks:
+    - name: "storage_backend"
+      type: "connection"
+      critical: true
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-06"
+  tags:
+    - effect
+    - registration
+    - storage
+    - capability-oriented
+    - pluggable-backend

omnibase_infra/nodes/node_registration_storage_effect/models/__init__.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for Registration Storage Effect Node.
+
+This module exports models used by the NodeRegistrationStorageEffect for
+capability-oriented storage operations.
+
+Available Models:
+    - ModelDeleteResult: Delete operation result
+    - ModelRegistrationRecord: Complete registration record for storage
+    - ModelRegistrationUpdate: Partial update parameters
+    - ModelStorageHealthCheckDetails: Backend-specific health check diagnostics
+    - ModelStorageHealthCheckResult: Health check result for storage backends
+    - ModelStorageQuery: Query parameters with filtering and pagination
+    - ModelStorageResult: Query results with records and metadata
+    - ModelUpsertResult: Insert/update operation result
+
+All models are:
+    - Frozen (immutable after creation)
+    - Extra="forbid" (no extra fields allowed)
+    - Strongly typed (no Any types, no dict primitives in signatures)
+"""
+
+from .model_delete_result import ModelDeleteResult
+from .model_registration_record import ModelRegistrationRecord
+from .model_registration_update import ModelRegistrationUpdate
+from .model_storage_health_check_details import ModelStorageHealthCheckDetails
+from .model_storage_health_check_result import (
+    ModelStorageHealthCheckResult,
+)
+from .model_storage_query import ModelStorageQuery
+from .model_storage_result import ModelStorageResult
+from .model_upsert_result import ModelUpsertResult
+
+__all__ = [
+    "ModelDeleteResult",
+    "ModelRegistrationRecord",
+    "ModelRegistrationUpdate",
+    "ModelStorageHealthCheckDetails",
+    "ModelStorageHealthCheckResult",
+    "ModelStorageQuery",
+    "ModelStorageResult",
+    "ModelUpsertResult",
+]

omnibase_infra/nodes/node_registration_storage_effect/models/model_delete_result.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Delete Result Model for Registration Storage Operations.
+
+This module provides ModelDeleteResult, representing the result of a
+delete operation against registration storage.
+
+Architecture:
+    ModelDeleteResult captures:
+    - success: Whether the operation completed successfully
+    - node_id: ID of the record that was targeted for deletion
+    - deleted: Whether a record was actually deleted (vs not found)
+    - error: Error message if operation failed
+    - duration_ms: Time taken for the operation
+    - backend_type: The backend that handled the delete
+    - correlation_id: Correlation ID for distributed tracing
+
+    This model replaces primitive bool returns with a strongly-typed
+    result that provides richer diagnostics and traceability.
+
+Related:
+    - ModelRegistrationRecord: Record that was deleted
+    - ProtocolRegistrationStorageHandler: Protocol that produces results
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDeleteResult(BaseModel):
+    """Result model for registration storage delete operations.
+
+    Indicates the outcome of a delete operation. Success indicates the
+    operation completed without errors; deleted indicates whether a
+    record was actually found and removed.
+
+    Immutability:
+        This model uses frozen=True to ensure results are immutable
+        once created, enabling safe sharing and logging.
+
+    Attributes:
+        success: Whether the operation completed successfully (no errors).
+        node_id: UUID of the registration record targeted for deletion.
+        deleted: Whether a record was actually deleted (False if not found).
+        error: Error message if success is False (sanitized).
+        duration_ms: Time taken for the operation in milliseconds.
+        backend_type: The backend that handled the delete.
+        correlation_id: Correlation ID for request tracing.
+
+    Example (record deleted):
+        >>> result = ModelDeleteResult(
+        ...     success=True,
+        ...     node_id=some_uuid,
+        ...     deleted=True,
+        ...     duration_ms=12.5,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.was_deleted()
+        True
+
+    Example (record not found):
+        >>> result = ModelDeleteResult(
+        ...     success=True,
+        ...     node_id=some_uuid,
+        ...     deleted=False,
+        ...     duration_ms=8.3,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.was_deleted()
+        False
+
+    Example (operation failed):
+        >>> result = ModelDeleteResult(
+        ...     success=False,
+        ...     node_id=some_uuid,
+        ...     deleted=False,
+        ...     error="Connection timeout to database",
+        ...     duration_ms=5000.0,
+        ...     backend_type="postgresql",
+        ...     correlation_id=correlation_id,
+        ... )
+        >>> result.success
+        False
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the operation completed successfully (no errors)",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="UUID of the registration record targeted for deletion",
+    )
+    deleted: bool = Field(
+        ...,
+        description="Whether a record was actually deleted (False if not found)",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if success is False (sanitized - no secrets)",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+    backend_type: str = Field(
+        default="unknown",
+        description="The backend type that handled the delete",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for request tracing",
+    )
+
+    def was_deleted(self) -> bool:
+        """Check if this result represents a successful deletion.
+
+        Returns:
+            True if operation succeeded and a record was deleted.
+        """
+        return self.success and self.deleted
+
+
+__all__ = ["ModelDeleteResult"]