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

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/validation/__init__.py

@@ -91,13 +91,22 @@ Security Design (Intentional Fail-Open Architecture):
     - validator_routing_coverage.py: Routing gap detection (module docstring)
 """
 
+# Topic suffix validation models (OMN-1537)
+from omnibase_core.models.validation import (
+    ModelTopicSuffixParts,
+    ModelTopicValidationResult,
+)
 from omnibase_core.validation import (
     CircularImportValidator,
     ModelModuleImportResult,
+    compose_full_topic,
+    is_valid_topic_suffix,
+    parse_topic_suffix,
     validate_all,
     validate_architecture,
     validate_contracts,
     validate_patterns,
+    validate_topic_suffix,
     validate_union_usage,
 )
 
@@ -222,6 +231,13 @@ __all__: list[str] = [
     "NODE_ARCHETYPE_EXPECTED_CATEGORIES",  # Node archetype categories
     "TOPIC_CATEGORY_PATTERNS",  # Topic category patterns
     "TOPIC_SUFFIXES",  # Topic suffix constants
+    # Topic suffix validation (OMN-1537)
+    "ModelTopicSuffixParts",  # Topic suffix parsed parts
+    "ModelTopicValidationResult",  # Topic validation result
+    "compose_full_topic",  # Compose full topic from parts
+    "is_valid_topic_suffix",  # Check if topic suffix is valid
+    "parse_topic_suffix",  # Parse topic suffix into parts
+    "validate_topic_suffix",  # Validate topic suffix format
     # Errors
     "ChainPropagationError",  # Chain propagation error (OMN-951)
     "ExecutionShapeViolationError",  # Execution shape violation

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omnibase_infra
-Version: 0.2.3
+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.4,<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.3.dist-info → omnibase_infra-0.2.5.dist-info}/RECORD

@@ -88,7 +88,7 @@ omnibase_infra/handlers/filesystem/model_file_system_result.py,sha256=qrQyZCuxHi
 omnibase_infra/handlers/handler_consul.py,sha256=F2u4-f8eW8Nli5drg1oH6sZJkw3EfuaycnvzmEXeOQI,31409
 omnibase_infra/handlers/handler_db.py,sha256=toaT1DS-J76J47isXsRSkcB7QFD5-8SaDbOqVEIhMmQ,44871
 omnibase_infra/handlers/handler_filesystem.py,sha256=J71cMTmWpQP4Y2h2nxy4jLmDKbvg9Xwbubjb-_ZFqGo,58333
-omnibase_infra/handlers/handler_graph.py,sha256=12Nulsm-xIuFJZP61IilS-SuNupRFhHWWYAtLbQzwhs,44692
+omnibase_infra/handlers/handler_graph.py,sha256=SuBH4XRgGUTPFD46jZDiGC5rkCfbVJy4-gpavfX5ZaU,79794
 omnibase_infra/handlers/handler_http.py,sha256=1HAl26wtTpql1GNlLw9ZwjhOm32Oif4TOguAam16y5s,37899
 omnibase_infra/handlers/handler_intent.py,sha256=aoX8Prgum2GbqI-exNA2e2kASA1b8cVpeXcR6JtuMIg,13992
 omnibase_infra/handlers/handler_manifest_persistence.contract.yaml,sha256=kkkcDL88RcmK0ZaAa4eDcSajKwwU4iia0LN7o_zqRD8,6397
@@ -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
@@ -706,7 +714,7 @@ omnibase_infra/utils/util_error_sanitization.py,sha256=FxoHw40HCu9SO83jXuGQ5L349
 omnibase_infra/utils/util_pydantic_validators.py,sha256=7i8mgUyy-ObUCw0ICVY_N_sSoxIFfDkGsk182riQUqo,16271
 omnibase_infra/utils/util_retry_optimistic.py,sha256=hSCUGNJgECaKN3PBf44r3Y7Lh0m8BQPDk0YTSJyWtOo,10967
 omnibase_infra/utils/util_semver.py,sha256=ceTeLo753aAkyyI847XlceajdMvBIn3XJq1X1Fkfz78,7661
-omnibase_infra/validation/__init__.py,sha256=Ws8xI8hQ-0D87gxrWRoUwYMO1jHRPJuHgK7hzit9tXs,12640
+omnibase_infra/validation/__init__.py,sha256=_HyFyYgxncjbWzbKs1Fi7jADh31SAlOB5x8QqOKNbzM,13295
 omnibase_infra/validation/contracts/security.validation.yaml,sha256=NixKgUo7KliQr1yJBY65j2WaxJv_XKoUSCA6pB77DiQ,3858
 omnibase_infra/validation/enums/__init__.py,sha256=J4vRP14R2lHaixXCk1MH5Bzh3Vd0pZmySpN8PkqJc4c,278
 omnibase_infra/validation/enums/enum_contract_violation_severity.py,sha256=beR4vRNXtQ7ckOSOYZHn3NAacZBNTX1csG9_Y6SPd7M,414
@@ -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.3.dist-info/METADATA,sha256=H7cdWfmx6qcKKqLO9H9wR73cQhNcLopSeAjpNHnqwus,7553
-omnibase_infra-0.2.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-omnibase_infra-0.2.3.dist-info/entry_points.txt,sha256=NlZEQIMp4I5S2f0l286hLyA48oQB92S0ISrn1rfFP30,110
-omnibase_infra-0.2.3.dist-info/licenses/LICENSE,sha256=CwYWppeN0neFHYdbbUdHbR4_PiyTYnmk6ufFWuVsL7I,1070
-omnibase_infra-0.2.3.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,,