omnibase_infra 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

omnibase_infra/nodes/node_contract_persistence_effect/node.py

@@ -56,8 +56,14 @@ from omnibase_core.nodes.node_effect import NodeEffect
 
 if TYPE_CHECKING:
     from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.models.runtime.model_resolved_dependencies import (
+        ModelResolvedDependencies,
+    )
 
 
+# ONEX_EXCLUDE: declarative_node - OMN-1732 DEC-003 requires constructor injection
+# for protocol dependencies. The _resolved_dependencies instance variable stores
+# pre-resolved protocols from ContractDependencyResolver.
 class NodeContractPersistenceEffect(NodeEffect):
     """Declarative effect node for contract registry persistence.
 
@@ -76,6 +82,9 @@ class NodeContractPersistenceEffect(NodeEffect):
 
     Args:
         container: ONEX dependency injection container.
+        dependencies: Optional pre-resolved protocol dependencies. If provided,
+            the node will use these instead of resolving from container.
+            Part of OMN-1732 runtime dependency injection.
 
     Dependency Injection:
         Backend adapters (PostgreSQL) are resolved via container.
@@ -102,13 +111,21 @@ class NodeContractPersistenceEffect(NodeEffect):
         ```
     """
 
-    def __init__(self, container: ModelONEXContainer) -> None:
+    def __init__(
+        self,
+        container: ModelONEXContainer,
+        dependencies: ModelResolvedDependencies | None = None,
+    ) -> None:
         """Initialize effect node with container dependency injection.
 
         Args:
             container: ONEX dependency injection container.
+            dependencies: Optional pre-resolved protocol dependencies from
+                ContractDependencyResolver. If provided, the node uses these
+                instead of resolving from container. Part of OMN-1732.
         """
         super().__init__(container)
+        self._resolved_dependencies = dependencies
 
 
 __all__ = ["NodeContractPersistenceEffect"]

omnibase_infra/nodes/node_contract_persistence_effect/registry/registry_infra_contract_persistence_effect.py

@@ -24,10 +24,14 @@ Related:
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.models.runtime.model_resolved_dependencies import (
+        ModelResolvedDependencies,
+    )
     from omnibase_infra.nodes.node_contract_persistence_effect.node import (
         NodeContractPersistenceEffect,
     )
@@ -62,7 +66,10 @@ class RegistryInfraContractPersistenceEffect:
     """
 
     @staticmethod
-    def create(container: ModelONEXContainer) -> NodeContractPersistenceEffect:
+    def create(
+        container: ModelONEXContainer,
+        dependencies: ModelResolvedDependencies | None = None,
+    ) -> NodeContractPersistenceEffect:
         """Create a NodeContractPersistenceEffect instance with resolved dependencies.
 
         Factory method that creates a fully configured NodeContractPersistenceEffect
@@ -73,6 +80,10 @@ class RegistryInfraContractPersistenceEffect:
                 following protocols registered:
                 - ProtocolPostgresAdapter: PostgreSQL database operations
                 - ProtocolCircuitBreakerAware: Backend circuit breaker protection
+            dependencies: Optional pre-resolved protocol dependencies from
+                ContractDependencyResolver. If provided, the node uses these
+                instead of resolving from container. Part of OMN-1732 runtime
+                dependency injection.
 
         Returns:
             Configured NodeContractPersistenceEffect instance ready for operation.
@@ -84,14 +95,22 @@ class RegistryInfraContractPersistenceEffect:
             >>> container = ModelONEXContainer()
             >>> container.register(ProtocolPostgresAdapter, postgres_adapter)
             >>> effect = RegistryInfraContractPersistenceEffect.create(container)
+            >>>
+            >>> # With pre-resolved dependencies (OMN-1732)
+            >>> resolved = resolver.resolve(contract)
+            >>> effect = RegistryInfraContractPersistenceEffect.create(
+            ...     container, dependencies=resolved
+            ... )
 
         .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Added optional ``dependencies`` parameter for constructor injection (OMN-1732).
         """
         from omnibase_infra.nodes.node_contract_persistence_effect.node import (
             NodeContractPersistenceEffect,
         )
 
-        return NodeContractPersistenceEffect(container)
+        return NodeContractPersistenceEffect(container, dependencies=dependencies)
 
     @staticmethod
     def get_required_protocols() -> list[str]:
@@ -100,6 +119,11 @@ class RegistryInfraContractPersistenceEffect:
         Returns the protocol class names that must be registered in the
         container before creating a NodeContractPersistenceEffect instance.
 
+        .. deprecated:: 0.6.0
+            Use contract.yaml dependencies field instead. This method will be
+            removed in a future version. The contract is now the single source
+            of truth for protocol requirements (OMN-1732).
+
         Returns:
             List of protocol class names required for node operation.
 
@@ -111,6 +135,13 @@ class RegistryInfraContractPersistenceEffect:
 
         .. versionadded:: 0.5.0
         """
+        warnings.warn(
+            "get_required_protocols() is deprecated. Use contract.yaml dependencies "
+            "field instead. The contract is the single source of truth for protocol "
+            "requirements (OMN-1732).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return [
             "ProtocolPostgresAdapter",
             "ProtocolCircuitBreakerAware",

omnibase_infra/nodes/node_registration_orchestrator/models/model_postgres_intent_payload.py

@@ -26,7 +26,7 @@ Thread Safety:
 Edge Case Behavior:
     The ``endpoints`` field validator explicitly handles the following cases:
     - ``None``: Raises ValueError (invalid input, not silently ignored)
-    - Empty Mapping ``{}``: Logs warning and converts to empty tuple
+    - Empty Mapping ``{}``: Raises ValueError (use default=() for no endpoints)
     - Invalid types (int, str, list, etc.): Raises ValueError
     - Tuple: Passed through as-is
     - Non-empty Mapping: Converted to tuple of (key, value) pairs
@@ -36,7 +36,6 @@ Edge Case Behavior:
 from __future__ import annotations
 
 import logging
-import warnings
 from collections.abc import Mapping
 from types import MappingProxyType
 from uuid import UUID
@@ -153,7 +152,7 @@ class ModelPostgresIntentPayload(BaseModel):
 
         Edge Cases:
             - ``None``: Raises ValueError (explicit rejection)
-            - Empty Mapping ``{}``: Logs warning, returns empty tuple
+            - Empty Mapping ``{}``: Raises ValueError (use default=() for no endpoints)
             - Empty tuple ``()``: Passed through (same as default)
             - Invalid types (list, int, str): Raises ValueError
             - Non-string keys/values: Raises ValueError (strict mode)
@@ -192,16 +191,13 @@ class ModelPostgresIntentPayload(BaseModel):
             return v  # type: ignore[return-value]  # NOTE: runtime type validated by Pydantic
         if isinstance(v, Mapping):
             if len(v) == 0:
-                # Log warning for empty Mapping to help detect potentially missing data.
-                # This is different from the default empty tuple - it's an explicit
-                # empty Mapping input that gets coerced.
-                warning_msg = (
-                    "Empty Mapping provided for endpoints, coercing to empty tuple. "
-                    "If this is intentional, consider using default=() instead."
+                # Explicit empty Mapping is rejected - use default=() instead.
+                # This prevents silent coercion that could mask invalid input.
+                raise ValueError(
+                    "Empty Mapping provided for endpoints. "
+                    "If no endpoints are needed, omit the field to use default=() "
+                    "rather than passing an explicit empty Mapping."
                 )
-                logger.warning(warning_msg)
-                warnings.warn(warning_msg, UserWarning, stacklevel=2)
-                return ()
             # Validate and convert to tuple - strict mode requires string keys/values
             result: list[tuple[str, str]] = []
             for key, val in v.items():

omnibase_infra/nodes/node_slack_alerter_effect/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Slack Alerter Effect Node - Declarative Slack webhook alerting.
+
+This module exports the declarative NodeSlackAlerterEffect for sending
+infrastructure alerts to Slack via webhooks.
+
+Architecture:
+    This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom routing logic - all behavior from handler_routing
+    - Lightweight shell that delegates to HandlerSlackWebhook
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_slack_alerter_effect import NodeSlackAlerterEffect
+    >>> from omnibase_infra.handlers import HandlerSlackWebhook
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeSlackAlerterEffect(container)
+    >>>
+    >>> # Handler receives dependencies via constructor
+    >>> handler = HandlerSlackWebhook()
+    >>> # result = await handler.handle(alert)
+
+Related Tickets:
+    - OMN-1905: Add declarative Slack webhook handler to omnibase_infra
+"""
+
+from omnibase_infra.nodes.node_slack_alerter_effect.node import NodeSlackAlerterEffect
+
+__all__ = ["NodeSlackAlerterEffect"]

omnibase_infra/nodes/node_slack_alerter_effect/contract.yaml

@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeSlackAlerterEffect
+#
+# This contract defines the interface for the Slack Alerter Effect node,
+# which sends infrastructure alerts to Slack via webhooks. The node uses
+# declarative operation routing to dispatch operations to the handler.
+#
+# Related Tickets:
+#   - OMN-1905: Add declarative Slack webhook handler to omnibase_infra
+# Contract identifiers
+name: "node_slack_alerter_effect"
+contract_name: "node_slack_alerter_effect"
+node_name: "node_slack_alerter_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: >
+  Effect node for Slack webhook alerting. Sends infrastructure alerts to Slack channels using incoming webhooks with Block Kit formatting, retry with exponential backoff, and rate limit handling. Uses declarative operation routing to dispatch to the HandlerSlackWebhook.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelSlackAlert"
+  module: "omnibase_infra.handlers.models.model_slack_alert"
+  description: "Input model containing alert severity, message, and optional details."
+output_model:
+  name: "ModelSlackAlertResult"
+  module: "omnibase_infra.handlers.models.model_slack_alert"
+  description: "Output model containing delivery status, timing, and error information."
+# =============================================================================
+# HANDLER ROUTING (Declarative Handler Dispatch)
+# =============================================================================
+# This section defines how operations are routed to the Slack webhook handler.
+# The routing strategy determines handler selection based on operation type.
+#
+# Design Rationale:
+#   - Single handler for all Slack operations
+#   - Block Kit formatting for rich messages
+#   - Retry with exponential backoff for resilience
+#   - Rate limit handling for graceful degradation
+#
+# Execution Flow:
+#   1. Receive ModelSlackAlert with operation type
+#   2. Route to HandlerSlackWebhook based on operation
+#   3. Execute webhook delivery with retry logic
+#   4. Return ModelSlackAlertResult with delivery status
+# =============================================================================
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    # Send Alert - Formatted Block Kit message
+    # Sends a rich formatted alert with severity, message, and details.
+    - operation: "send_alert"
+      handler:
+        name: "HandlerSlackWebhook"
+        module: "omnibase_infra.handlers.handler_slack_webhook"
+      description: "Send formatted alert to Slack with Block Kit formatting"
+      output_fields:
+        - success
+        - duration_ms
+        - retry_count
+    # Send Message - Plain text message
+    # Sends a simple text message (uses same handler, alert formatting applied)
+    - operation: "send_message"
+      handler:
+        name: "HandlerSlackWebhook"
+        module: "omnibase_infra.handlers.handler_slack_webhook"
+      description: "Send message to Slack channel"
+      output_fields:
+        - success
+        - duration_ms
+        - retry_count
+# =============================================================================
+# ERROR HANDLING (Retry + Rate Limiting)
+# =============================================================================
+# Error handling configuration for Slack webhook operations.
+# Uses retry with exponential backoff and handles rate limiting gracefully.
+#
+# Note: The handler implements its own retry logic internally rather than
+# relying on external retry orchestration. This ensures consistent behavior
+# and proper rate limit handling.
+# =============================================================================
+error_handling:
+  # Retry policy with exponential backoff
+  retry_policy:
+    max_retries: 3
+    initial_delay_ms: 1000
+    max_delay_ms: 4000
+    exponential_base: 2
+    retry_on:
+      - "SLACK_RATE_LIMITED"
+      - "SLACK_TIMEOUT"
+      - "SLACK_CONNECTION_ERROR"
+      - "SLACK_CLIENT_ERROR"
+  # Error type definitions
+  error_types:
+    - name: "SLACK_NOT_CONFIGURED"
+      description: "SLACK_WEBHOOK_URL environment variable not set"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "SLACK_RATE_LIMITED"
+      description: "Slack returned HTTP 429 rate limit"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_TIMEOUT"
+      description: "Webhook request timed out"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_CONNECTION_ERROR"
+      description: "Failed to connect to Slack webhook"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_CLIENT_ERROR"
+      description: "HTTP client error during request"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_HTTP_4XX"
+      description: "Slack returned HTTP 4xx error (non-429)"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "SLACK_HTTP_5XX"
+      description: "Slack returned HTTP 5xx error"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+# IO operations (EFFECT node specific)
+io_operations:
+  - operation: "send_alert"
+    description: "Send a formatted alert to Slack with Block Kit formatting"
+    input_fields:
+      - severity
+      - message
+      - title
+      - details
+      - channel
+      - correlation_id
+    output_fields:
+      - success
+      - duration_ms
+      - correlation_id
+      - error
+      - error_code
+      - retry_count
+  - operation: "send_message"
+    description: "Send a plain text message to Slack"
+    input_fields:
+      - message
+      - channel
+      - correlation_id
+    output_fields:
+      - success
+      - duration_ms
+      - correlation_id
+      - error
+      - error_code
+      - retry_count
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "http_client"
+    type: "library"
+    library: "aiohttp"
+    description: "Async HTTP client for webhook requests"
+  - name: "slack_webhook_url"
+    type: "environment"
+    env_var: "SLACK_WEBHOOK_URL"
+    description: "Slack incoming webhook URL"
+    required: true
+# Capabilities provided by this node
+capabilities:
+  - name: "slack_alerting"
+    description: "Send infrastructure alerts to Slack channels"
+  - name: "block_kit_formatting"
+    description: "Format messages using Slack Block Kit for rich display"
+  - name: "retry_with_backoff"
+    description: "Retry failed requests with exponential backoff"
+  - name: "rate_limit_handling"
+    description: "Handle Slack rate limiting gracefully"
+# Model definitions
+definitions:
+  ModelSlackAlert:
+    type: object
+    description: "Input payload for Slack alert operations"
+    frozen: true
+    extra: "forbid"
+    properties:
+      severity:
+        type: enum
+        enum_class: "EnumAlertSeverity"
+        module: "omnibase_infra.handlers.models.model_slack_alert"
+        description: "Alert severity level for visual formatting"
+        default: "info"
+        enum:
+          - "critical"
+          - "error"
+          - "warning"
+          - "info"
+      message:
+        type: string
+        description: "Main alert message content"
+        min_length: 1
+        max_length: 3000
+      title:
+        type: string
+        nullable: true
+        default: null
+        max_length: 150
+        description: "Optional alert title"
+      details:
+        type: object
+        key_type: string
+        value_type: any
+        description: "Additional key-value details"
+        default_factory: "dict"
+      channel:
+        type: string
+        nullable: true
+        default: null
+        description: "Optional channel override"
+      correlation_id:
+        type: uuid
+        description: "UUID for distributed tracing"
+        default_factory: "uuid4"
+    required:
+      - message
+  ModelSlackAlertResult:
+    type: object
+    description: "Response from Slack webhook operations"
+    frozen: true
+    extra: "forbid"
+    properties:
+      success:
+        type: boolean
+        description: "Whether the alert was delivered successfully"
+      duration_ms:
+        type: float
+        description: "Time taken for the operation in milliseconds"
+        default: 0.0
+        ge: 0.0
+      correlation_id:
+        type: uuid
+        description: "UUID from the original request"
+      error:
+        type: string
+        nullable: true
+        default: null
+        description: "Sanitized error message if success is False"
+      error_code:
+        type: string
+        nullable: true
+        default: null
+        description: "Error code for programmatic handling"
+      retry_count:
+        type: integer
+        description: "Number of retry attempts made"
+        default: 0
+        ge: 0
+    required:
+      - success
+      - correlation_id
+# Health check configuration
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+  checks:
+    - name: "webhook_configured"
+      check_type: "environment"
+      env_var: "SLACK_WEBHOOK_URL"
+      description: "Verify SLACK_WEBHOOK_URL is configured"
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2026-02-04"
+  updated: "2026-02-04"
+  tags:
+    - effect
+    - slack
+    - alerting
+    - webhook
+    - infrastructure
+    - block-kit

omnibase_infra/nodes/node_slack_alerter_effect/node.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Slack Alerter Effect - Declarative effect node for Slack alerting.
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom routing logic - all behavior from handler_routing
+    - Lightweight shell that delegates to handlers via container resolution
+    - Used for ONEX-compliant runtime execution via RuntimeHostProcess
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for infrastructure I/O operations.
+All handler routing is 100% driven by contract.yaml, not Python code.
+
+Handler Routing Pattern:
+    1. Receive alert request (input_model in contract)
+    2. Route to appropriate handler based on operation (handler_routing)
+    3. Execute infrastructure I/O via handler (Slack webhook)
+    4. Return structured response (output_model in contract)
+
+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
+    - Container DI: Handler dependencies resolved via container
+
+Node Responsibilities:
+    - Define I/O model contract (ModelSlackAlert -> ModelSlackAlertResult)
+    - Delegate all execution to handlers via base class
+    - NO custom logic - pure declarative shell
+
+The actual handler execution and routing is performed by:
+    - Direct handler invocation by callers
+    - Or orchestrator layer for workflow coordination
+
+Handlers receive their dependencies directly via constructor injection:
+    - HandlerSlackWebhook(webhook_url, http_session)
+
+Coroutine Safety:
+    This node is async-safe. Handler coordination is performed by the
+    caller or orchestrator layer, not by this effect node.
+
+Related Modules:
+    - contract.yaml: Handler routing and I/O model definitions
+    - ../../handlers/handler_slack_webhook.py: Webhook handler implementation
+    - ../../handlers/models/model_slack_alert.py: Alert payload models
+
+Related Tickets:
+    - OMN-1905: Add declarative Slack webhook handler to omnibase_infra
+"""
+
+from __future__ import annotations
+
+from omnibase_core.nodes.node_effect import NodeEffect
+
+
+class NodeSlackAlerterEffect(NodeEffect):
+    """Declarative effect node for Slack webhook alerting.
+
+    This effect node is a lightweight shell that defines the I/O contract
+    for Slack alert operations. All routing and execution logic is driven
+    by contract.yaml - this class contains NO custom routing code.
+
+    Supported Operations (defined in contract.yaml handler_routing):
+        - send_alert: Send a formatted alert to Slack
+        - send_message: Send a plain text message to Slack
+
+    Dependency Injection:
+        The HandlerSlackWebhook is instantiated by callers with its
+        dependencies (webhook_url from env, optional http_session).
+        This node contains NO instance variables for the handler.
+
+    Example:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.node_slack_alerter_effect import NodeSlackAlerterEffect
+        from omnibase_infra.handlers import HandlerSlackWebhook
+        from omnibase_infra.handlers.models import ModelSlackAlert, EnumAlertSeverity
+
+        # Create effect node via container
+        container = ModelONEXContainer()
+        effect = NodeSlackAlerterEffect(container)
+
+        # Handler receives dependencies directly via constructor
+        handler = HandlerSlackWebhook()
+
+        # Create and send alert
+        alert = ModelSlackAlert(
+            severity=EnumAlertSeverity.ERROR,
+            message="Circuit breaker opened",
+            title="Infrastructure Alert",
+            details={"service": "consul", "threshold": "5"},
+        )
+        result = await handler.handle(alert)
+
+        if result.success:
+            print(f"Alert delivered in {result.duration_ms}ms")
+        else:
+            print(f"Alert failed: {result.error}")
+        ```
+    """
+
+    # Pure declarative shell - all behavior defined in contract.yaml
+
+
+__all__ = ["NodeSlackAlerterEffect"]

omnibase_infra/runtime/__init__.py

@@ -282,6 +282,11 @@ from omnibase_infra.runtime.baseline_subscriptions import (
     get_baseline_topics,
 )
 
+# Contract dependency resolver (OMN-1732)
+from omnibase_infra.runtime.contract_dependency_resolver import (
+    ContractDependencyResolver,
+)
+
 # Chain-aware dispatch (OMN-951) - must be imported LAST to avoid circular import
 from omnibase_infra.runtime.chain_aware_dispatch import (
     ChainAwareDispatcher,
@@ -458,4 +463,6 @@ __all__: list[str] = [
     "BASELINE_CONTRACT_TOPICS",
     "BASELINE_PLATFORM_TOPICS",
     "get_baseline_topics",
+    # Contract dependency resolver (OMN-1732)
+    "ContractDependencyResolver",
 ]

omnibase_infra/runtime/baseline_subscriptions.py

@@ -72,10 +72,13 @@ This subset excludes heartbeat topics and is appropriate when:
     - Heartbeat processing is handled separately
     - You want to minimize subscription overhead
 
+Note:
+    Topics are realm-agnostic in ONEX. The environment/realm is enforced via
+    envelope identity, not topic naming. Subscribe directly to the topic suffix.
+
 Example:
     >>> for topic_suffix in BASELINE_CONTRACT_TOPICS:
-    ...     full_topic = f"{environment}.{topic_suffix}"
-    ...     subscribe(full_topic)
+    ...     subscribe(topic_suffix)  # No environment prefix needed
 """
 
 # All platform baseline topics including heartbeat.
@@ -91,10 +94,13 @@ Includes:
     - Contract deregistered events
     - Node heartbeat events
 
+Note:
+    Topics are realm-agnostic in ONEX. The environment/realm is enforced via
+    envelope identity, not topic naming. Subscribe directly to the topic suffix.
+
 Example:
     >>> for topic_suffix in BASELINE_PLATFORM_TOPICS:
-    ...     full_topic = f"{environment}.{topic_suffix}"
-    ...     subscribe(full_topic)
+    ...     subscribe(topic_suffix)  # No environment prefix needed
 """
 
 
@@ -111,8 +117,9 @@ def get_baseline_topics(*, include_heartbeat: bool = True) -> frozenset[str]:
             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.
+        A frozenset of topic suffix strings. Topics are realm-agnostic in ONEX;
+        subscribe directly to these suffixes without environment prefix.
+        The environment/realm is enforced via envelope identity, not topic naming.
 
     Example:
         >>> # For full platform observability