omnibase_infra 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

omnibase_infra/nodes/node_intent_storage_effect/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Intent Storage Effect - Capability-oriented intent storage node.
+
+This package provides the NodeIntentStorageEffect, a capability-oriented
+effect node for intent storage operations using Memgraph graph database.
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+    Named by capability (intent.storage), not by specific backend implementation.
+    Uses Memgraph for graph-based intent persistence.
+
+Capabilities:
+    - intent.storage: Store, query, and analyze intents
+    - intent.storage.store: Store classified intents as graph nodes
+    - intent.storage.query_session: Query intents by session identifier
+    - intent.storage.query_distribution: Get intent distribution statistics
+
+Event Topics:
+    Consumed:
+        - {env}.{namespace}.onex.evt.intent-classified.v1
+        - {env}.{namespace}.onex.cmd.intent-query-session.v1
+        - {env}.{namespace}.onex.cmd.intent-query-distribution.v1
+    Published:
+        - {env}.{namespace}.onex.evt.intent-stored.v1
+        - {env}.{namespace}.onex.evt.intent-session-query-result.v1
+        - {env}.{namespace}.onex.evt.intent-distribution-result.v1
+
+Available Exports:
+    - NodeIntentStorageEffect: The declarative effect node
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_intent_storage_effect import (
+    ...     NodeIntentStorageEffect,
+    ... )
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeIntentStorageEffect(container)
+
+Related Modules:
+    - models: Pydantic models for intent storage operations
+    - registry: Dependency injection registration
+    - HandlerIntent: Handler for graph operations (omnibase_infra.handlers)
+"""
+
+from .node import NodeIntentStorageEffect
+
+__all__ = ["NodeIntentStorageEffect"]

omnibase_infra/nodes/node_intent_storage_effect/contract.yaml

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeIntentStorageEffect
+#
+# Capability-oriented effect node for intent storage operations.
+# Wraps HandlerIntent for graph-based intent persistence in Memgraph.
+#
+# This contract defines the interface for storing and querying intents
+# as graph nodes, enabling session-based intent retrieval and distribution
+# analysis.
+#
+# Related Tickets:
+#   - OMN-1509: Intent Processing System
+#   - WS-1: Intent Storage Effect Node
+# Contract identifiers
+name: "node_intent_storage_effect"
+contract_name: "node_intent_storage_effect"
+node_name: "node_intent_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 intent storage operations. Handles storing classified intents in Memgraph graph database and querying intents by session or distribution statistics.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelIntentStorageInput"
+  module: "omnibase_infra.nodes.node_intent_storage_effect.models"
+  description: "Input model for intent storage operations (classified intent event)."
+output_model:
+  name: "ModelIntentStorageOutput"
+  module: "omnibase_infra.nodes.node_intent_storage_effect.models"
+  description: "Output model for intent storage results (storage confirmation)."
+# Capability declaration (capability-oriented naming)
+capabilities:
+  - name: "intent.storage"
+    description: "Store, query, and analyze intents in graph database"
+    version: "1.0.0"
+  - name: "intent.storage.store"
+    description: "Store classified intents as graph nodes"
+  - name: "intent.storage.query_session"
+    description: "Query intents by session identifier"
+  - name: "intent.storage.query_distribution"
+    description: "Get intent distribution statistics"
+# Event-driven topic configuration
+# Uses {env}.{namespace} placeholders for environment-aware topics
+consumed_events:
+  - topic: "{env}.{namespace}.onex.evt.intent-classified.v1"
+    event_type: "IntentClassifiedEvent"
+    description: "Classified intent ready for storage"
+  - topic: "{env}.{namespace}.onex.cmd.intent-query-session.v1"
+    event_type: "IntentQuerySessionCommand"
+    message_category: "COMMAND"
+    description: "Command to query intents by session"
+  - topic: "{env}.{namespace}.onex.cmd.intent-query-distribution.v1"
+    event_type: "IntentQueryDistributionCommand"
+    message_category: "COMMAND"
+    description: "Command to get intent distribution statistics"
+published_events:
+  - topic: "{env}.{namespace}.onex.evt.intent-stored.v1"
+    event_type: "IntentStoredEvent"
+    description: "Confirmation that intent was stored successfully"
+  - topic: "{env}.{namespace}.onex.evt.intent-session-query-result.v1"
+    event_type: "IntentSessionQueryResultEvent"
+    description: "Result of session-based intent query"
+  - topic: "{env}.{namespace}.onex.evt.intent-distribution-result.v1"
+    event_type: "IntentDistributionResultEvent"
+    description: "Result of intent distribution statistics query"
+# IO operations (EFFECT node specific)
+# Note: correlation_id is required (UUID) for all operations.
+# Callers must provide a correlation_id for tracing.
+io_operations:
+  - operation: "intent.store"
+    description: "Store a classified intent as a graph node"
+    input_fields:
+      - intent_type: "str"
+      - session_id: "str | None"
+      - payload: "dict[str, object]"
+      - correlation_id: "UUID"
+    output_fields:
+      - node_id: "str"
+      - element_id: "str"
+      - success: "bool"
+    # Not idempotent: Each call creates a new graph node with unique element_id.
+    # Duplicate calls with same input will create multiple nodes.
+    # Use correlation_id for deduplication at the caller level if needed.
+    idempotent: false
+  - operation: "intent.query_session"
+    description: "Query intents by session identifier"
+    input_fields:
+      - session_id: "str"
+      - correlation_id: "UUID"
+    output_fields:
+      - intents: "list[dict]"
+      - count: "int"
+    idempotent: true
+  - operation: "intent.query_distribution"
+    description: "Get intent count and distribution by intent_type"
+    input_fields:
+      - correlation_id: "UUID"
+    output_fields:
+      - total_count: "int"
+      - distribution: "dict[str, int]"
+    idempotent: true
+# Handler routing (wraps HandlerIntent which wraps HandlerGraph)
+handler_routing:
+  routing_strategy: "operation_match"
+  default_handler: "memgraph"
+  handlers:
+    - handler_type: "memgraph"
+      handler:
+        name: "HandlerIntent"
+        module: "omnibase_infra.handlers.handler_intent"
+      description: "Memgraph graph database handler for intent storage"
+      supported_operations:
+        - "intent.store"
+        - "intent.query_session"
+        - "intent.query_distribution"
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "handler_intent"
+    type: "handler"
+    class_name: "HandlerIntent"
+    module: "omnibase_infra.handlers.handler_intent"
+    description: "Intent handler for graph operations"
+  - name: "handler_graph"
+    type: "handler"
+    class_name: "HandlerGraph"
+    module: "omnibase_infra.handlers.handler_graph"
+    description: "Underlying graph handler (Memgraph)"
+    transitive: true
+# 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: "GraphConnectionError"
+      description: "Unable to connect to Memgraph"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "GraphTimeoutError"
+      description: "Graph operation timed out"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "IntentNotFoundError"
+      description: "Intent not found in graph"
+      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: "graph_backend"
+      type: "connection"
+      critical: true
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2026-01-26"
+  tags:
+    - effect
+    - intent
+    - storage
+    - graph
+    - memgraph
+    - capability-oriented

omnibase_infra/nodes/node_intent_storage_effect/models/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Models for Intent Storage Effect Node.
+
+This module exports models used by the NodeIntentStorageEffect for
+capability-oriented intent storage operations in Memgraph.
+
+Available Models:
+    - ModelIntentStorageInput: Input model for intent storage (classified intent data)
+    - ModelIntentStorageOutput: Output model for storage results (node ID, success)
+
+All models are:
+    - Frozen (immutable after creation)
+    - Extra="forbid" (no extra fields allowed)
+    - Strongly typed (no Any types)
+"""
+
+from .model_intent_storage_input import ModelIntentStorageInput
+from .model_intent_storage_output import ModelIntentStorageOutput
+
+__all__ = [
+    "ModelIntentStorageInput",
+    "ModelIntentStorageOutput",
+]

omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_input.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Intent Storage Input Model for Intent Storage Operations.
+
+This module provides ModelIntentStorageInput, representing the input
+for storing a classified intent in the graph database.
+
+Architecture:
+    ModelIntentStorageInput is constructed from IntentClassifiedEvent payloads
+    and contains:
+    - intent_type: The classified intent type
+    - session_id: Optional session identifier for grouping
+    - payload: Intent-specific data to store as node properties
+    - correlation_id: Required correlation ID for tracing (fail-fast validation)
+
+    This model serves as the canonical input for the intent.store operation.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that processes this input
+    - ModelIntentStorageOutput: Output model containing storage result
+    - HandlerIntent: Handler that executes storage operations
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_core.errors import OnexError
+from omnibase_core.types import JsonType
+
+
+class ModelIntentStorageInput(BaseModel):
+    """Input model for intent storage operations.
+
+    Defines the required fields for storing a classified intent as a
+    graph node in Memgraph.
+
+    Immutability:
+        This model uses frozen=True to ensure inputs are immutable
+        once created, enabling safe reuse and caching.
+
+    Attributes:
+        intent_type: The classified intent type (e.g., "query", "action").
+        session_id: Optional session identifier for grouping related intents.
+        payload: Intent-specific data to store as node properties.
+        correlation_id: Required correlation ID for request tracing.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> input_model = ModelIntentStorageInput(
+        ...     intent_type="query",
+        ...     session_id="sess-12345",
+        ...     payload={"query": "What is ONEX?", "confidence": 0.95},
+        ...     correlation_id=uuid4(),
+        ... )
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: str = Field(
+        ...,
+        description="The classified intent type",
+        min_length=1,
+        max_length=256,
+    )
+    session_id: str | None = Field(
+        default=None,
+        description="Optional session identifier for grouping related intents",
+        max_length=256,
+    )
+    payload: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Intent-specific data to store as node properties",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for request tracing (required for observability)",
+    )
+
+    @field_validator("payload")
+    @classmethod
+    def validate_no_reserved_keys(cls, v: dict[str, JsonType]) -> dict[str, JsonType]:
+        """Validate payload does not contain reserved keys.
+
+        Reserved keys (intent_type, session_id, correlation_id) are used as
+        structured fields and cannot appear in the payload to prevent conflicts
+        during storage property merging.
+
+        Args:
+            v: The payload dictionary to validate.
+
+        Returns:
+            The validated payload dictionary.
+
+        Raises:
+            OnexError: If payload contains any reserved keys.
+        """
+        reserved_keys = {"intent_type", "session_id", "correlation_id"}
+        conflicting = reserved_keys & v.keys()
+        if conflicting:
+            raise OnexError(
+                message=f"Payload cannot contain reserved keys: {sorted(conflicting)}",
+                error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+            )
+        return v
+
+    def has_session(self) -> bool:
+        """Check if this input has a session identifier.
+
+        Returns:
+            True if session_id is provided.
+        """
+        return self.session_id is not None
+
+    def to_storage_properties(self) -> dict[str, JsonType]:
+        """Convert input to storage-friendly properties dict.
+
+        Returns:
+            Dictionary containing all intent properties for graph storage,
+            including intent_type, correlation_id, and session_id merged with payload.
+
+        Note:
+            Reserved key validation (intent_type, session_id, correlation_id)
+            is performed at model construction time via field_validator,
+            so this method can safely merge payload with structured fields.
+        """
+        properties: dict[str, JsonType] = {
+            "intent_type": self.intent_type,
+            "correlation_id": str(self.correlation_id),
+        }
+        if self.session_id:
+            properties["session_id"] = self.session_id
+
+        properties.update(self.payload)
+        return properties
+
+
+__all__ = ["ModelIntentStorageInput"]

omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_output.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Intent Storage Output Model for Intent Storage Operations.
+
+This module provides ModelIntentStorageOutput, representing the result
+of storing a classified intent in the graph database.
+
+Architecture:
+    ModelIntentStorageOutput is returned from intent.store operations
+    and contains:
+    - success: Whether the storage operation succeeded
+    - node_id: The graph node ID of the stored intent
+    - element_id: The graph element ID for the stored intent
+    - labels: Graph labels applied to the node
+    - properties: The stored properties (echoed back for verification)
+    - correlation_id: Correlation ID for request tracing
+    - error: Sanitized error message if operation failed
+
+    This model serves as the canonical output for the intent.store operation.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that produces this output
+    - ModelIntentStorageInput: Input model for storage operations
+    - HandlerIntent: Handler that executes storage operations
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelIntentStorageOutput(BaseModel):
+    """Output model for intent storage operations.
+
+    Contains the result of storing a classified intent as a graph node,
+    including the assigned node ID and stored properties.
+
+    Immutability:
+        This model uses frozen=True to ensure outputs are immutable
+        once created, enabling safe sharing and caching.
+
+    Attributes:
+        success: Whether the storage operation completed successfully.
+        node_id: The graph database node ID of the stored intent.
+        element_id: The graph element ID for the stored intent.
+        labels: Graph labels applied to the node (e.g., ["Intent"]).
+        properties: The stored properties (for verification).
+        correlation_id: Correlation ID for request tracing (required).
+        error: Sanitized error message if operation failed.
+        duration_ms: Time taken for the operation in milliseconds.
+
+    Example:
+        >>> output = ModelIntentStorageOutput(
+        ...     success=True,
+        ...     node_id="123",
+        ...     element_id="4:abc:123",
+        ...     labels=("Intent",),
+        ...     properties={"intent_type": "query", "session_id": "sess-12345"},
+        ...     correlation_id=correlation_id,
+        ...     duration_ms=15.2,
+        ... )
+        >>> if output:  # Uses custom __bool__
+        ...     print(f"Stored intent: {output.node_id}")
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the storage operation completed successfully",
+    )
+    node_id: str | None = Field(
+        default=None,
+        description="The graph database node ID of the stored intent",
+    )
+    element_id: str | None = Field(
+        default=None,
+        description="The graph element ID for the stored intent",
+    )
+    labels: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Graph labels applied to the node",
+    )
+    properties: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="The stored properties (for verification)",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for request tracing (required for traceability)",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Sanitized error message if operation failed",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if the storage operation succeeded.
+
+        Warning:
+            This is non-standard Pydantic behavior. Normally bool(model)
+            returns True for any instance. This override enables idiomatic
+            `if result:` checks for success validation.
+
+            See: docs/decisions/adr-custom-bool-result-models.md
+
+        Returns:
+            True if success is True, False otherwise.
+        """
+        return self.success
+
+    def has_node_id(self) -> bool:
+        """Check if a node ID was assigned.
+
+        Returns:
+            True if node_id is present.
+        """
+        return self.node_id is not None
+
+
+__all__ = ["ModelIntentStorageOutput"]

omnibase_infra/nodes/node_intent_storage_effect/node.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Intent Storage Effect - Capability-oriented intent storage node.
+
+This effect node provides intent storage capabilities using Memgraph graph database.
+Named by capability ("intent.storage"), not by vendor (e.g., Memgraph).
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom storage logic - all behavior from handler (HandlerIntent)
+    - Lightweight shell that delegates to HandlerIntent -> HandlerGraph
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for external I/O operations.
+All storage logic is 100% driven by handler implementations, not Python code.
+
+Capabilities:
+    - intent.storage: Store, query, and analyze intents
+    - intent.storage.store: Store classified intents as graph nodes
+    - intent.storage.query_session: Query intents by session identifier
+    - intent.storage.query_distribution: Get intent distribution statistics
+
+Event Topics:
+    Consumed:
+        - {env}.{namespace}.onex.evt.intent-classified.v1
+        - {env}.{namespace}.onex.cmd.intent-query-session.v1
+        - {env}.{namespace}.onex.cmd.intent-query-distribution.v1
+    Published:
+        - {env}.{namespace}.onex.evt.intent-stored.v1
+        - {env}.{namespace}.onex.evt.intent-session-query-result.v1
+        - {env}.{namespace}.onex.evt.intent-distribution-result.v1
+
+Handler Stack:
+    NodeIntentStorageEffect -> HandlerIntent -> HandlerGraph -> Memgraph
+
+Design Decisions:
+    - 100% Contract-Driven: All capabilities in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: Handler wired externally
+    - Capability-Oriented: Named by what it does, not what it uses
+
+Related:
+    - contract.yaml: Capability definitions and IO operations
+    - HandlerIntent: Intent-specific graph operations handler
+    - HandlerGraph: Underlying Memgraph graph handler
+    - models/: Input, output models
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_effect import NodeEffect
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+
+class NodeIntentStorageEffect(NodeEffect):
+    """Effect node for intent storage operations.
+
+    Capability: intent.storage
+
+    Provides a capability-oriented interface for intent storage operations.
+    Uses Memgraph graph database for storing intents as nodes with properties.
+
+    This node is declarative - all behavior is defined in contract.yaml and
+    implemented through the handler (HandlerIntent). No custom storage logic
+    exists in this class.
+
+    Attributes:
+        container: ONEX dependency injection container
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> container = ModelONEXContainer()
+        >>> node = NodeIntentStorageEffect(container)
+        >>> # Handler must be wired externally via registry
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the intent storage effect node.
+
+        Args:
+            container: ONEX dependency injection container for resolving
+                dependencies defined in contract.yaml.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeIntentStorageEffect"]

omnibase_infra/nodes/node_intent_storage_effect/registry/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for Intent Storage Effect Node.
+
+This module exports the RegistryInfraIntentStorage for dependency registration
+with the ONEX container. The registry wires up the NodeIntentStorageEffect
+with its handler dependencies (HandlerIntent -> HandlerGraph -> Memgraph).
+
+Architecture:
+    The registry follows the ONEX container-based dependency injection pattern:
+    - Registers NodeIntentStorageEffect with the container
+    - Wires handler dependencies defined in contract.yaml
+    - Enables capability-oriented resolution (intent.storage)
+
+    Registration Flow:
+        Container -> RegistryInfraIntentStorage.register() -> NodeIntentStorageEffect
+                                                           -> HandlerIntent (resolved)
+
+Usage:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_intent_storage_effect.registry import (
+    ...     RegistryInfraIntentStorage,
+    ... )
+    >>> container = ModelONEXContainer()
+    >>> RegistryInfraIntentStorage.register(container)
+
+Related:
+    - NodeIntentStorageEffect: The effect node registered by this registry
+    - HandlerIntent: Handler wired for intent storage operations
+    - ModelONEXContainer: ONEX dependency injection container
+"""
+
+from .registry_infra_intent_storage import RegistryInfraIntentStorage
+
+__all__ = ["RegistryInfraIntentStorage"]

omnibase_infra/nodes/node_intent_storage_effect/registry/registry_infra_intent_storage.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for Intent Storage Node Dependencies.
+
+This module provides RegistryInfraIntentStorage, which registers
+dependencies for the NodeIntentStorageEffect node.
+
+Architecture:
+    The registry follows ONEX container-based dependency injection:
+    - Registers HandlerIntent with ModelONEXContainer
+    - Supports initialization with pre-configured HandlerGraph
+    - Enables runtime handler resolution via container
+
+    Registration is typically called during application bootstrap.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that uses these dependencies
+    - HandlerIntent: Intent handler for graph operations
+    - HandlerGraph: Underlying Memgraph graph handler
+    - ModelONEXContainer: ONEX dependency injection container
+
+Testing:
+    This module uses module-level state (``_HANDLER_STORAGE``, ``_PROTOCOL_METADATA``)
+    for handler storage. Tests MUST call ``RegistryInfraIntentStorage.clear()`` in
+    setup and teardown fixtures to prevent test pollution between test cases.
+
+    Failure to clear state can cause:
+    - Tests passing in isolation but failing when run together
+    - Handlers from previous tests leaking into subsequent tests
+    - Flaky test behavior that is difficult to debug
+
+    Recommended fixture pattern:
+
+    .. code-block:: python
+
+        @pytest.fixture(autouse=True)
+        def clear_registry():
+            RegistryInfraIntentStorage.clear()
+            yield
+            RegistryInfraIntentStorage.clear()
+
+Note:
+    This registry uses a module-level dict for handler storage because the
+    ServiceRegistry in omnibase_core v1.0 doesn't support dict-style access
+    or string-keyed multi-handler routing. The handlers are still validated
+    but stored separately.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, cast
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.handlers.handler_intent import HandlerIntent
+
+__all__ = ["RegistryInfraIntentStorage"]
+
+# TODO(ServiceRegistry-v2): Migrate to container.service_registry once v2.0
+# supports dict-style access for multi-handler routing. Current module-level
+# storage is a workaround for v1.0 limitations. See docstring Note section.
+#
+# Module-level storage for handlers and metadata
+# ServiceRegistry in v1.0 doesn't support dict-style access needed for
+# handler routing
+_HANDLER_STORAGE: dict[str, object] = {}
+_PROTOCOL_METADATA: dict[str, dict[str, object]] = {}
+
+
+class RegistryInfraIntentStorage:
+    """Registry for intent storage node dependencies.
+
+    Registers handler implementations with the ONEX container.
+    Supports the HandlerIntent which wraps HandlerGraph for Memgraph operations.
+
+    Usage:
+        .. code-block:: python
+
+            from omnibase_core.models.container import ModelONEXContainer
+            from omnibase_infra.nodes.node_intent_storage_effect.registry import (
+                RegistryInfraIntentStorage,
+            )
+
+            # Create container
+            container = ModelONEXContainer()
+
+            # Register dependencies
+            RegistryInfraIntentStorage.register(container)
+
+            # Register the handler (must have graph_handler configured)
+            RegistryInfraIntentStorage.register_handler(
+                container,
+                handler=intent_handler,
+            )
+
+    Note:
+        This registry does NOT instantiate handlers. Handlers must be
+        created externally with their specific dependencies (HandlerGraph)
+        and then registered via register_handler().
+    """
+
+    # Handler key for container registration
+    HANDLER_KEY = "handler_intent"
+
+    # Default handler type
+    DEFAULT_HANDLER_TYPE = "memgraph"
+
+    @staticmethod
+    def _is_registered(handler_key: str) -> bool:
+        """Check if a handler is already registered for the given key.
+
+        This is a private helper method used to detect re-registration
+        attempts, which may indicate container lifecycle issues or
+        missing clear() calls in tests.
+
+        Args:
+            handler_key: The handler key to check (e.g., "handler_intent.memgraph").
+
+        Returns:
+            True if a handler is already registered for this key, False otherwise.
+        """
+        return handler_key in _HANDLER_STORAGE
+
+    @staticmethod
+    def register(_container: ModelONEXContainer) -> None:
+        """Register intent storage dependencies with the container.
+
+        Registers the handler key for later handler binding. This method
+        sets up the infrastructure but does not bind a specific handler.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access
+                for multi-handler routing. The parameter is retained for API
+                consistency with other registry methods and future migration.
+
+        Example:
+            >>> from omnibase_core.models.container import ModelONEXContainer
+            >>> container = ModelONEXContainer()
+            >>> RegistryInfraIntentStorage.register(container)
+        """
+        # Register handler metadata for discovery
+        # Actual handler binding happens via register_handler()
+        _PROTOCOL_METADATA[RegistryInfraIntentStorage.HANDLER_KEY] = {
+            "handler": "HandlerIntent",
+            "module": "omnibase_infra.handlers.handler_intent",
+            "description": "Handler for intent storage operations in Memgraph",
+            "capabilities": [
+                "intent.storage",
+                "intent.storage.store",
+                "intent.storage.query_session",
+                "intent.storage.query_distribution",
+            ],
+        }
+
+    @staticmethod
+    def register_handler(
+        _container: ModelONEXContainer,
+        handler: HandlerIntent,
+    ) -> None:
+        """Register a specific intent handler with the container.
+
+        Binds a concrete HandlerIntent implementation to the handler key.
+        The handler must already be initialized with a HandlerGraph.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access.
+                The parameter is retained for API consistency.
+            handler: HandlerIntent instance to register (must be initialized).
+
+        Raises:
+            ProtocolConfigurationError: If handler does not implement the required
+                protocol methods (initialize, shutdown, execute).
+
+        Example:
+            >>> from omnibase_infra.handlers.handler_intent import HandlerIntent
+            >>> handler = HandlerIntent(container)
+            >>> await handler.initialize({"graph_handler": graph_handler})
+            >>> RegistryInfraIntentStorage.register_handler(container, handler)
+        """
+        from omnibase_infra.enums import EnumInfraTransportType
+        from omnibase_infra.errors import (
+            ModelInfraErrorContext,
+            ProtocolConfigurationError,
+        )
+
+        # NOTE: Protocol-based duck typing is used here per ONEX conventions.
+        # We verify the handler implements required methods rather than checking
+        # concrete class inheritance. This enables:
+        # 1. Fail-fast validation: Immediately reject invalid handlers
+        # 2. Duck typing: Any object with the required methods is accepted
+        # 3. Testability: Mock handlers can be injected without subclassing
+        required_methods = ["initialize", "shutdown", "execute"]
+        missing = [
+            m for m in required_methods if not callable(getattr(handler, m, None))
+        ]
+        if missing:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="register_handler",
+                target_name="intent_handler",
+            )
+            raise ProtocolConfigurationError(
+                f"Handler missing required protocol methods: {missing}. "
+                f"Got {type(handler).__name__}",
+                context=context,
+            )
+
+        # Store handler in module-level storage
+        handler_key = (
+            f"{RegistryInfraIntentStorage.HANDLER_KEY}."
+            f"{RegistryInfraIntentStorage.DEFAULT_HANDLER_TYPE}"
+        )
+
+        # Warn if re-registering over an existing handler
+        if RegistryInfraIntentStorage._is_registered(handler_key):
+            logger.warning(
+                "Re-registering handler '%s'. This may indicate container lifecycle "
+                "issues or missing clear() calls in tests.",
+                handler_key,
+            )
+
+        _HANDLER_STORAGE[handler_key] = handler
+
+        # Also register as default
+        default_key = RegistryInfraIntentStorage.HANDLER_KEY + ".default"
+        if RegistryInfraIntentStorage._is_registered(default_key):
+            logger.warning(
+                "Re-registering handler '%s'. This may indicate container lifecycle "
+                "issues or missing clear() calls in tests.",
+                default_key,
+            )
+        _HANDLER_STORAGE[default_key] = handler
+
+    @staticmethod
+    def get_handler(
+        _container: ModelONEXContainer,
+        handler_type: str | None = None,
+    ) -> HandlerIntent | None:
+        """Retrieve a registered intent handler from the container.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access.
+                The parameter is retained for API consistency.
+            handler_type: Specific handler type to retrieve. If None, returns default.
+
+        Returns:
+            The registered HandlerIntent, or None if not found.
+
+        Example:
+            >>> handler = RegistryInfraIntentStorage.get_handler(container)
+            >>> if handler:
+            ...     result = await handler.execute(envelope)
+        """
+        if handler_type is not None:
+            handler_key = f"{RegistryInfraIntentStorage.HANDLER_KEY}.{handler_type}"
+        else:
+            handler_key = RegistryInfraIntentStorage.HANDLER_KEY + ".default"
+
+        result = _HANDLER_STORAGE.get(handler_key)
+        return cast("HandlerIntent | None", result)
+
+    @staticmethod
+    def clear() -> None:
+        """Clear all registered handlers and protocol metadata.
+
+        Resets all module-level state to empty dicts. This method is essential
+        for test isolation.
+
+        Warning:
+            This method MUST be called in test setup and teardown to prevent
+            test pollution. Module-level state persists across test cases within
+            the same Python process. Failing to call this method can cause:
+
+            - Handlers from previous tests affecting subsequent tests
+            - Tests passing individually but failing when run together
+            - Non-deterministic test failures that are difficult to reproduce
+
+        Example:
+            .. code-block:: python
+
+                @pytest.fixture(autouse=True)
+                def clear_registry():
+                    RegistryInfraIntentStorage.clear()
+                    yield
+                    RegistryInfraIntentStorage.clear()
+        """
+        _HANDLER_STORAGE.clear()
+        _PROTOCOL_METADATA.clear()

{omnibase_infra-0.2.4.dist-info → omnibase_infra-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omnibase_infra
-Version: 0.2.4
+Version: 0.2.5
 Summary: ONEX Infrastructure - Service integration and database infrastructure tools
 License: MIT
 License-File: LICENSE
@@ -28,8 +28,8 @@ Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
 Requires-Dist: jsonschema (>=4.20.0,<5.0.0)
 Requires-Dist: mcp (>=1.25.0,<2.0.0)
 Requires-Dist: neo4j (>=5.15.0,<6.0.0)
-Requires-Dist: omnibase-core (>=0.9.5,<0.10.0)
-Requires-Dist: omnibase-spi (>=0.6.0,<0.7.0)
+Requires-Dist: omnibase-core (>=0.9.6,<0.10.0)
+Requires-Dist: omnibase-spi (>=0.6.1,<0.7.0)
 Requires-Dist: opentelemetry-api (>=1.27.0,<2.0.0)
 Requires-Dist: opentelemetry-exporter-otlp (>=1.27.0,<2.0.0)
 Requires-Dist: opentelemetry-instrumentation (>=0.48b0,<0.49)

{omnibase_infra-0.2.4.dist-info → omnibase_infra-0.2.5.dist-info}/RECORD

@@ -390,6 +390,14 @@ omnibase_infra/nodes/effects/protocol_effect_idempotency_store.py,sha256=cGJmDLS
 omnibase_infra/nodes/effects/protocol_postgres_adapter.py,sha256=foLR6ZRv1EqfrZVxo9DTM5uunhkdCncnAr-6gqSEw8M,3198
 omnibase_infra/nodes/effects/registry_effect.py,sha256=dSoqw_9hF7GiYQ6a9KtF7bgEXCW2FqH5b3Ud3b5CQaM,20975
 omnibase_infra/nodes/effects/store_effect_idempotency_inmemory.py,sha256=6WXK7ZcWqPdpGLVpXbFzu-uIuc6vxCAgEpWTNHOy2Is,15566
+omnibase_infra/nodes/node_intent_storage_effect/__init__.py,sha256=CVxx3WtXt_BcSgEG5496N5n7ZCK8FZFmx4jt9sPwUjE,1864
+omnibase_infra/nodes/node_intent_storage_effect/contract.yaml,sha256=GSECd-8WAxytIwUQQTnP7167S0bD-1roAGaI08e_K9Q,6642
+omnibase_infra/nodes/node_intent_storage_effect/models/__init__.py,sha256=XZ6L3PLHjNvnxRmJnDtVVWCsmZVfKdxnrenQWdJ1_D8,778
+omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_input.py,sha256=hnAb6IQJVmJYubdg_MnB2afBk9df0bLV0gv1vnSyFug,4889
+omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_output.py,sha256=kRufInAdTi58pEtLM4sYWKrwvD7g-EGFKZxb6pTSRzo,4479
+omnibase_infra/nodes/node_intent_storage_effect/node.py,sha256=zfThTRPijnyrGyQLaHETC_yxdwn56IwnnS1cyH6QZD0,3475
+omnibase_infra/nodes/node_intent_storage_effect/registry/__init__.py,sha256=9sLDlHv4ySokV3Jhw6KTSgpWOfI3Lt1cg-jcO9-5Zjg,1443
+omnibase_infra/nodes/node_intent_storage_effect/registry/registry_infra_intent_storage.py,sha256=C095vuMER24eNHPzTxFpVR9c_DxepFO0inUGfrUOvOw,11499
 omnibase_infra/nodes/node_registration_orchestrator/README.md,sha256=DgmzwS7EkNi1ein4O1fG5FzIE_85fHCuN39J3N_3Wbk,18217
 omnibase_infra/nodes/node_registration_orchestrator/__init__.py,sha256=TEmJpSvnjYR4rO0xm-V7roVSZwEQDf6X_NIryXPiHLc,4545
 omnibase_infra/nodes/node_registration_orchestrator/contract.yaml,sha256=4amAy5T7LZgLx2-hODJ0UvKJpGNLttnGuAXWgO4pycs,26212
@@ -731,8 +739,8 @@ omnibase_infra/validation/validator_routing_coverage.py,sha256=51vYEi5NhU6wqohk2
 omnibase_infra/validation/validator_runtime_shape.py,sha256=9Xl37_dNDinT7nr-BoJ9fG3O5cT1_j6N-C7bojwQi3g,39033
 omnibase_infra/validation/validator_security.py,sha256=Yn_kwxBtPzEj1GzrW0OafL-bR-FgoqdeFzseQqF2_B8,20622
 omnibase_infra/validation/validator_topic_category.py,sha256=1y6STpSNIJsE2AmX5f8PVzPuOfoQmedgocSbEqOdtrM,48798
-omnibase_infra-0.2.4.dist-info/METADATA,sha256=tAKYTmhTovTzEDY5Wc_ah3RSUz_IMUt9e4skcm8tKK0,7553
-omnibase_infra-0.2.4.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-omnibase_infra-0.2.4.dist-info/entry_points.txt,sha256=NlZEQIMp4I5S2f0l286hLyA48oQB92S0ISrn1rfFP30,110
-omnibase_infra-0.2.4.dist-info/licenses/LICENSE,sha256=CwYWppeN0neFHYdbbUdHbR4_PiyTYnmk6ufFWuVsL7I,1070
-omnibase_infra-0.2.4.dist-info/RECORD,,
+omnibase_infra-0.2.5.dist-info/METADATA,sha256=jfps4nOkHND0EapFOjf-osUGKwledT6kvy6DSfM8R_4,7553
+omnibase_infra-0.2.5.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+omnibase_infra-0.2.5.dist-info/entry_points.txt,sha256=NlZEQIMp4I5S2f0l286hLyA48oQB92S0ISrn1rfFP30,110
+omnibase_infra-0.2.5.dist-info/licenses/LICENSE,sha256=CwYWppeN0neFHYdbbUdHbR4_PiyTYnmk6ufFWuVsL7I,1070
+omnibase_infra-0.2.5.dist-info/RECORD,,