omnibase_infra 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

omnibase_infra/nodes/node_registry_effect/node.py

@@ -22,17 +22,21 @@ Design Decisions:
     - 100% Contract-Driven: All routing logic in YAML, not Python
     - Zero Custom Routing: Base class handles handler dispatch via contract
     - Declarative Handlers: handler_routing section defines dispatch rules
-    - External Wiring: Handlers resolved via container dependency injection
+    - Container DI: Backend adapters resolved via container, not setter methods
 
 Node Responsibilities:
     - Define I/O model contract (ModelRegistryRequest -> ModelRegistryResponse)
-    - Provide dependency injection points for backend clients
     - Delegate all execution to handlers via base class
+    - NO custom logic - pure declarative shell
 
 The actual handler execution and routing is performed by:
     - NodeOrchestrator (for workflow coordination)
     - Or direct handler invocation by callers
 
+Handlers receive their dependencies directly via constructor injection:
+    - HandlerConsulRegister(consul_client)
+    - HandlerPostgresUpsert(postgres_adapter)
+
 Coroutine Safety:
     This node is async-safe. Handler coordination is performed by the
     orchestrator layer, not by this effect node.
@@ -43,32 +47,24 @@ Related Modules:
     - models/: Node-specific input/output models
     - NodeRegistrationOrchestrator: Coordinates handler execution
 
-Migration Notes (OMN-1103):
-    This declarative node replaces the imperative implementation.
-    All routing logic has been moved to contract.yaml handler_routing.
-    Callers should use handlers directly or via the orchestrator.
+Migration Notes (OMN-1726):
+    Refactored from setter-based dependency injection to pure declarative shell.
+    Backend adapters are now resolved via container, not via set_* methods.
+    Handlers receive dependencies directly via their constructors.
 """
 
 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
-    from omnibase_infra.nodes.effects.protocol_consul_client import ProtocolConsulClient
-    from omnibase_infra.nodes.effects.protocol_postgres_adapter import (
-        ProtocolPostgresAdapter,
-    )
-
 
+# ONEX_EXCLUDE: declarative_node - legacy effect node with direct adapter access (OMN-1725)
 class NodeRegistryEffect(NodeEffect):
     """Declarative effect node for dual-backend node registration.
 
     This effect node is a lightweight shell that defines the I/O contract
     for registration operations. All routing and execution logic is driven
-    by contract.yaml - this class contains no custom routing code.
+    by contract.yaml - this class contains NO custom routing code.
 
     Handler coordination is performed by:
         - NodeRegistrationOrchestrator for workflow-based execution
@@ -80,8 +76,9 @@ class NodeRegistryEffect(NodeEffect):
         - retry_partial_failure: Retry a specific backend after partial failure
 
     Dependency Injection:
-        Backend clients are injected via setter methods. The orchestrator
-        or caller is responsible for wiring these dependencies.
+        Backend adapters (Consul, PostgreSQL) are resolved via container.
+        Handlers receive their dependencies directly via constructor injection.
+        This node contains NO instance variables for backend clients.
 
     Example:
         ```python
@@ -92,15 +89,14 @@ class NodeRegistryEffect(NodeEffect):
             HandlerPostgresUpsert,
         )
 
-        # Create effect node
+        # Create effect node via container
         container = ModelONEXContainer()
         effect = NodeRegistryEffect(container)
 
-        # Wire backend clients
-        effect.set_consul_client(consul_client)
-        effect.set_postgres_adapter(postgres_adapter)
+        # Handlers receive dependencies directly via constructor
+        consul_client = container.resolve(ProtocolConsulClient)
+        postgres_adapter = container.resolve(ProtocolPostgresAdapter)
 
-        # Execute via handlers directly
         consul_handler = HandlerConsulRegister(consul_client)
         postgres_handler = HandlerPostgresUpsert(postgres_adapter)
 
@@ -110,56 +106,7 @@ class NodeRegistryEffect(NodeEffect):
         ```
     """
 
-    def __init__(self, container: ModelONEXContainer) -> None:
-        """Initialize the effect node.
-
-        Args:
-            container: ONEX dependency injection container providing:
-                - Backend adapters (Consul client, PostgreSQL adapter)
-                - Handler instances
-                - Configuration
-        """
-        super().__init__(container)
-
-        # Backend adapters (injected via setter methods)
-        self._consul_client: ProtocolConsulClient | None = None
-        self._postgres_adapter: ProtocolPostgresAdapter | None = None
-
-    def set_consul_client(self, client: ProtocolConsulClient) -> None:
-        """Set the Consul client for service registration.
-
-        Args:
-            client: Protocol-compliant Consul client implementation.
-        """
-        self._consul_client = client
-
-    def set_postgres_adapter(self, adapter: ProtocolPostgresAdapter) -> None:
-        """Set the PostgreSQL adapter for registration persistence.
-
-        Args:
-            adapter: Protocol-compliant PostgreSQL adapter implementation.
-        """
-        self._postgres_adapter = adapter
-
-    @property
-    def consul_client(self) -> ProtocolConsulClient | None:
-        """Get the Consul client if configured."""
-        return self._consul_client
-
-    @property
-    def postgres_adapter(self) -> ProtocolPostgresAdapter | None:
-        """Get the PostgreSQL adapter if configured."""
-        return self._postgres_adapter
-
-    @property
-    def has_consul_client(self) -> bool:
-        """Check if Consul client is configured."""
-        return self._consul_client is not None
-
-    @property
-    def has_postgres_adapter(self) -> bool:
-        """Check if PostgreSQL adapter is configured."""
-        return self._postgres_adapter is not None
+    # Pure declarative shell - all behavior defined in contract.yaml
 
 
 __all__ = ["NodeRegistryEffect"]

omnibase_infra/protocols/protocol_dispatch_engine.py

@@ -150,3 +150,93 @@ class ProtocolDispatchEngine(Protocol):
                     await dispatch_engine.dispatch(topic, envelope)
         """
         ...
+
+    async def dispatch_with_transaction(
+        self,
+        *,
+        topic: str,
+        envelope: ModelEventEnvelope[object],
+        tx: object,
+    ) -> ModelDispatchResult | None:
+        """Dispatch an event envelope with database transaction context.
+
+        This method enables transaction-scoped dispatch for correct idempotency
+        semantics. The transaction parameter allows handlers to participate in
+        the same database transaction as the idempotency insert, ensuring
+        exactly-once processing.
+
+        Design Decision:
+            The ``tx`` parameter is typed as ``object`` rather than a specific
+            database type (e.g., ``asyncpg.Connection``) to avoid leaking
+            infrastructure types into the protocol. This keeps the protocol
+            generic and allows future flexibility for different database backends.
+
+            Implementers should type-narrow ``tx`` via duck-typing (checking for
+            required methods) rather than isinstance checks, per ONEX conventions:
+
+            .. code-block:: python
+
+                from omnibase_core.errors import OnexError
+
+                async def dispatch_with_transaction(
+                    self,
+                    *,
+                    topic: str,
+                    envelope: ModelEventEnvelope[object],
+                    tx: object,
+                ) -> ModelDispatchResult | None:
+                    # Duck-type check for required database connection methods
+                    if not (hasattr(tx, 'execute') and callable(tx.execute)):
+                        raise OnexError(
+                            "Transaction object must implement execute() method"
+                        )
+                    # Use tx with duck-typed interface...
+
+        Thread Safety:
+            This method MUST be safe for concurrent calls from multiple
+            coroutines. The transaction context (``tx``) is typically
+            connection-scoped and should not be shared across coroutines.
+
+        Args:
+            topic: The full topic name from which the envelope was consumed.
+                Used for routing and logging context.
+                Example: "dev.onex.evt.node.introspected.v1"
+            envelope: The deserialized event envelope containing the payload.
+                The payload type varies by topic/event type.
+            tx: Database transaction/connection context. Typed as ``object``
+                to avoid infrastructure type leakage; implementations should
+                type-narrow based on their database backend (e.g.,
+                ``asyncpg.Connection``, ``aiosqlite.Connection``).
+
+        Returns:
+            ModelDispatchResult if the implementation returns dispatch metrics/results,
+            None if the implementation does not track results. Callers should not
+            depend on the return value for correctness.
+
+        Raises:
+            InfraDispatchError: If no handler is registered for the topic/message type.
+            OnexError: For handler execution failures or if ``tx`` does not implement
+                the required database connection interface (duck-type validation).
+
+        Example:
+            .. code-block:: python
+
+                # Idempotency consumer with transaction context
+                async with pool.acquire() as conn:
+                    async with conn.transaction():
+                        # Insert idempotency record and dispatch in same transaction
+                        await insert_idempotency_record(conn, message_id)
+                        await dispatch_engine.dispatch_with_transaction(
+                            topic=topic,
+                            envelope=envelope,
+                            tx=conn,
+                        )
+                        # Both committed atomically
+
+        Related:
+            - OMN-1740: Transaction-scoped dispatch for idempotency
+            - dispatch(): Non-transactional dispatch method
+
+        .. versionadded:: 0.2.9
+        """
+        ...

omnibase_infra/runtime/__init__.py

@@ -272,6 +272,13 @@ from omnibase_infra.runtime.registry_contract_source import (
 # Kafka contract source (OMN-1654)
 from omnibase_infra.runtime.kafka_contract_source import KafkaContractSource
 
+# Baseline subscriptions (OMN-1696)
+from omnibase_infra.runtime.baseline_subscriptions import (
+    BASELINE_CONTRACT_TOPICS,
+    BASELINE_PLATFORM_TOPICS,
+    get_baseline_topics,
+)
+
 # Chain-aware dispatch (OMN-951) - must be imported LAST to avoid circular import
 from omnibase_infra.runtime.chain_aware_dispatch import (
     ChainAwareDispatcher,
@@ -442,4 +449,8 @@ __all__: list[str] = [
     "store_contract_in_consul",
     # Kafka contract source (OMN-1654)
     "KafkaContractSource",
+    # Baseline subscriptions (OMN-1696)
+    "BASELINE_CONTRACT_TOPICS",
+    "BASELINE_PLATFORM_TOPICS",
+    "get_baseline_topics",
 ]

omnibase_infra/runtime/baseline_subscriptions.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Baseline Subscriptions Assembly Module.
+
+Aggregates platform baseline topic constants from omnibase_core for use
+by the ONEX runtime when wiring Kafka subscriptions.
+
+Part of OMN-1696: Wire baseline topic constants from omnibase_core into
+omnibase_infra runtime subscription assembly.
+
+Platform Baseline Topics:
+    These topics are automatically subscribed to by the runtime during
+    initialization, providing core platform functionality:
+
+    - **Contract Registered**: Notifies when a new handler contract is registered.
+      Used by KafkaContractSource for dynamic contract discovery.
+
+    - **Contract Deregistered**: Notifies when a handler contract is removed.
+      Used by KafkaContractSource for cache invalidation.
+
+    - **Node Heartbeat**: Periodic health signals from running nodes.
+      Used for liveness monitoring and service discovery.
+
+Usage:
+    >>> from omnibase_infra.runtime.baseline_subscriptions import (
+    ...     BASELINE_CONTRACT_TOPICS,
+    ...     BASELINE_PLATFORM_TOPICS,
+    ...     get_baseline_topics,
+    ... )
+    >>>
+    >>> # Get contract-only topics (registration/deregistration)
+    >>> contract_topics = get_baseline_topics(include_heartbeat=False)
+    >>>
+    >>> # Get all platform baseline topics (including heartbeat)
+    >>> all_topics = get_baseline_topics(include_heartbeat=True)
+
+Related:
+    - KafkaContractSource: Consumes contract registration events
+    - RuntimeHostProcess: Wires baseline subscriptions on startup
+    - omnibase_core.constants: Source of truth for topic suffix constants
+
+Related Tickets:
+    - OMN-1696: Wire baseline topic constants from omnibase_core
+    - OMN-1652: Define platform baseline topic suffixes in omnibase_core
+    - OMN-1654: KafkaContractSource (cache + discovery)
+
+.. versionadded:: 0.2.9
+    Created as part of OMN-1696 baseline subscription wiring.
+"""
+
+from __future__ import annotations
+
+from omnibase_core.constants import (
+    PLATFORM_BASELINE_TOPIC_SUFFIXES,
+    TOPIC_SUFFIX_CONTRACT_DEREGISTERED,
+    TOPIC_SUFFIX_CONTRACT_REGISTERED,
+    TOPIC_SUFFIX_NODE_HEARTBEAT,
+)
+
+# Contract registration/deregistration topics only.
+# Use when you need to track contract lifecycle events but not node health.
+BASELINE_CONTRACT_TOPICS: frozenset[str] = frozenset(
+    {
+        TOPIC_SUFFIX_CONTRACT_REGISTERED,
+        TOPIC_SUFFIX_CONTRACT_DEREGISTERED,
+    }
+)
+"""Contract lifecycle topics (registration and deregistration).
+
+This subset excludes heartbeat topics and is appropriate when:
+    - You only need to track contract changes
+    - Heartbeat processing is handled separately
+    - You want to minimize subscription overhead
+
+Example:
+    >>> for topic_suffix in BASELINE_CONTRACT_TOPICS:
+    ...     full_topic = f"{environment}.{topic_suffix}"
+    ...     subscribe(full_topic)
+"""
+
+# All platform baseline topics including heartbeat.
+# Use when you need complete platform observability.
+BASELINE_PLATFORM_TOPICS: frozenset[str] = frozenset(PLATFORM_BASELINE_TOPIC_SUFFIXES)
+"""All platform baseline topics including heartbeat.
+
+This is the full set of platform-reserved topics that the runtime
+subscribes to automatically during initialization.
+
+Includes:
+    - Contract registered events
+    - Contract deregistered events
+    - Node heartbeat events
+
+Example:
+    >>> for topic_suffix in BASELINE_PLATFORM_TOPICS:
+    ...     full_topic = f"{environment}.{topic_suffix}"
+    ...     subscribe(full_topic)
+"""
+
+
+def get_baseline_topics(*, include_heartbeat: bool = True) -> frozenset[str]:
+    """Return the appropriate set of baseline topic suffixes.
+
+    This helper function provides a convenient way to select between
+    the full platform topic set or contract-only topics based on
+    runtime requirements.
+
+    Args:
+        include_heartbeat: If True (default), returns all platform baseline
+            topics including node heartbeat. If False, returns only contract
+            registration/deregistration topics.
+
+    Returns:
+        A frozenset of topic suffix strings. These are suffixes that should
+        be prefixed with the environment name to form complete topic names.
+
+    Example:
+        >>> # For full platform observability
+        >>> topics = get_baseline_topics(include_heartbeat=True)
+        >>> assert TOPIC_SUFFIX_NODE_HEARTBEAT in topics
+        >>>
+        >>> # For contract-only tracking
+        >>> topics = get_baseline_topics(include_heartbeat=False)
+        >>> assert TOPIC_SUFFIX_NODE_HEARTBEAT not in topics
+        >>> assert TOPIC_SUFFIX_CONTRACT_REGISTERED in topics
+
+    Note:
+        The returned frozenset is immutable and can be safely shared
+        across threads without synchronization.
+
+    .. versionadded:: 0.2.9
+        Created as part of OMN-1696.
+    """
+    if include_heartbeat:
+        return BASELINE_PLATFORM_TOPICS
+    return BASELINE_CONTRACT_TOPICS
+
+
+__all__: list[str] = [
+    # Topic sets
+    "BASELINE_CONTRACT_TOPICS",
+    "BASELINE_PLATFORM_TOPICS",
+    # Helper function
+    "get_baseline_topics",
+    # Re-exported constants from omnibase_core for convenience
+    "PLATFORM_BASELINE_TOPIC_SUFFIXES",
+    "TOPIC_SUFFIX_CONTRACT_DEREGISTERED",
+    "TOPIC_SUFFIX_CONTRACT_REGISTERED",
+    "TOPIC_SUFFIX_NODE_HEARTBEAT",
+]

omnibase_infra/runtime/db/__init__.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database runtime module for omnibase_infra.
+
+This module provides the PostgresRepositoryRuntime and associated models for
+database operations with safety constraints and deterministic query behavior.
+
+Components:
+    - PostgresRepositoryRuntime: Generic Postgres runtime for contract execution
+    - ModelRepositoryRuntimeConfig: Configuration for runtime behavior
+    - ModelDbRepositoryContract: Repository contract specification
+    - ModelDbOperation: Database operation specification
+    - ModelDbReturn: Return type specification
+
+The db module enables safe, configurable database operations with:
+    - Contract-driven operations (all ops defined in ModelDbRepositoryContract)
+    - Operation allowlisting (select, insert, update, upsert)
+    - Row limits for multi-row selects
+    - Query timeouts with asyncio.wait_for()
+    - Deterministic ORDER BY injection
+    - Metrics emission
+
+Example:
+    >>> import asyncpg
+    >>> from omnibase_infra.runtime.db import (
+    ...     PostgresRepositoryRuntime,
+    ...     ModelDbRepositoryContract,
+    ...     ModelDbOperation,
+    ...     ModelDbReturn,
+    ...     ModelRepositoryRuntimeConfig,
+    ... )
+    >>>
+    >>> # Define contract
+    >>> contract = ModelDbRepositoryContract(
+    ...     name="users",
+    ...     database_ref="primary",
+    ...     ops={
+    ...         "find_by_id": ModelDbOperation(
+    ...             mode="select",
+    ...             sql="SELECT * FROM users WHERE id = $1",
+    ...             params=["user_id"],
+    ...             returns=ModelDbReturn(many=False),
+    ...         ),
+    ...     },
+    ... )
+    >>>
+    >>> # Create runtime with pool
+    >>> pool = await asyncpg.create_pool(...)
+    >>> runtime = PostgresRepositoryRuntime(pool, contract)
+    >>>
+    >>> # Execute operation
+    >>> user = await runtime.call("find_by_id", 123)
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.runtime.db.models import (
+    ModelDbOperation,
+    ModelDbRepositoryContract,
+    ModelDbReturn,
+    ModelRepositoryRuntimeConfig,
+)
+from omnibase_infra.runtime.db.postgres_repository_runtime import (
+    PostgresRepositoryRuntime,
+)
+
+__all__: list[str] = [
+    "ModelDbOperation",
+    "ModelDbRepositoryContract",
+    "ModelDbReturn",
+    "ModelRepositoryRuntimeConfig",
+    "PostgresRepositoryRuntime",
+]

omnibase_infra/runtime/db/models/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database Runtime Models Module.
+
+This module exports Pydantic models for database runtime configuration.
+Contract models (ModelDbRepositoryContract, ModelDbOperation, ModelDbReturn)
+are imported from omnibase_core.models.contracts.
+
+Exports:
+    ModelRepositoryRuntimeConfig: Configuration for PostgresRepositoryRuntime
+        - Safety constraints (max_row_limit, timeout_ms)
+        - Operation allowlisting (select, insert, update, upsert)
+        - Feature flags (allow_raw_operations, allow_delete_operations)
+        - Determinism controls (primary_key_column, default_order_by)
+        - Metrics emission configuration
+
+    ModelDbRepositoryContract: (re-export from omnibase_core)
+    ModelDbOperation: (re-export from omnibase_core)
+    ModelDbReturn: (re-export from omnibase_core)
+"""
+
+from __future__ import annotations
+
+# Contract models from omnibase_core (canonical source)
+from omnibase_core.models.contracts import (
+    ModelDbOperation,
+    ModelDbRepositoryContract,
+    ModelDbReturn,
+)
+
+# Runtime config is local to omnibase_infra
+from omnibase_infra.runtime.db.models.model_repository_runtime_config import (
+    ModelRepositoryRuntimeConfig,
+)
+
+__all__: list[str] = [
+    "ModelDbOperation",
+    "ModelDbRepositoryContract",
+    "ModelDbReturn",
+    "ModelRepositoryRuntimeConfig",
+]