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

omnibase_infra/runtime/kafka_contract_source.py

@@ -21,9 +21,12 @@ Event Topics (Platform Reserved):
     - Registration: {env}.{TOPIC_SUFFIX_CONTRACT_REGISTERED}
     - Deregistration: {env}.{TOPIC_SUFFIX_CONTRACT_DEREGISTERED}
 
-    Topic suffixes are imported from omnibase_core.constants for single source of truth.
+    Topic suffixes are imported from omnibase_core.constants. For runtime subscription
+    wiring, use baseline_subscriptions.BASELINE_CONTRACT_TOPICS which aggregates the
+    platform-reserved contract topics.
 
 See Also:
+    - baseline_subscriptions: Baseline topic assembly for runtime wiring
     - HandlerContractSource: Filesystem-based discovery
     - RegistryContractSource: Consul KV-based discovery
     - ProtocolContractSource: Protocol definition
@@ -76,10 +79,6 @@ from uuid import UUID, uuid4
 import yaml
 from pydantic import ValidationError
 
-from omnibase_core.constants import (
-    TOPIC_SUFFIX_CONTRACT_DEREGISTERED,
-    TOPIC_SUFFIX_CONTRACT_REGISTERED,
-)
 from omnibase_core.models.contracts.model_handler_contract import ModelHandlerContract
 from omnibase_core.models.errors import ModelOnexError
 from omnibase_core.models.events import (
@@ -94,6 +93,12 @@ from omnibase_infra.models.handlers import (
     ModelHandlerDescriptor,
     ModelHandlerIdentifier,
 )
+from omnibase_infra.runtime.baseline_subscriptions import (
+    BASELINE_CONTRACT_TOPICS,
+    BASELINE_PLATFORM_TOPICS,
+    TOPIC_SUFFIX_CONTRACT_DEREGISTERED,
+    TOPIC_SUFFIX_CONTRACT_REGISTERED,
+)
 from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
 logger = logging.getLogger(__name__)
@@ -979,6 +984,9 @@ __all__ = [
     # Re-exported from omnibase_core for convenience
     "ModelContractDeregisteredEvent",
     "ModelContractRegisteredEvent",
+    # Re-exported from baseline_subscriptions for runtime wiring (OMN-1696)
+    "BASELINE_CONTRACT_TOPICS",
+    "BASELINE_PLATFORM_TOPICS",
     "TOPIC_SUFFIX_CONTRACT_DEREGISTERED",
     "TOPIC_SUFFIX_CONTRACT_REGISTERED",
 ]

omnibase_infra/runtime/service_message_dispatch_engine.py

@@ -1420,6 +1420,118 @@ class MessageDispatchEngine:
                 output_events=[],
             )
 
+    async def dispatch_with_transaction(
+        self,
+        *,
+        topic: str,
+        envelope: ModelEventEnvelope[object],
+        tx: object,
+    ) -> ModelDispatchResult:
+        """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.
+
+        Current Implementation:
+            This initial implementation delegates to the standard ``dispatch()``
+            method. The ``tx`` parameter is stored in the dispatch context for
+            handlers that need transactional access. Future iterations may pass
+            ``tx`` directly to handlers via a context object.
+
+        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. Handlers that need the
+            transaction should type-narrow based on their database backend.
+
+        Thread Safety:
+            This method is safe for concurrent calls from multiple coroutines.
+            However, 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; handlers should type-
+                narrow based on their database backend (e.g.,
+                ``asyncpg.Connection``, ``aiosqlite.Connection``).
+
+        Returns:
+            ModelDispatchResult with dispatch status, metrics, and dispatcher outputs.
+
+        Raises:
+            ModelOnexError: If engine is not frozen (INVALID_STATE)
+            ModelOnexError: If topic is empty (INVALID_PARAMETER)
+            ModelOnexError: If envelope is None (INVALID_PARAMETER)
+
+        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)
+                        result = await 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
+        """
+        # Enforce freeze contract (same as dispatch())
+        if not self._frozen:
+            raise ModelOnexError(
+                message="dispatch_with_transaction() called before freeze(). "
+                "Registration MUST complete and freeze() MUST be called before dispatch. "
+                "This is required for thread safety.",
+                error_code=EnumCoreErrorCode.INVALID_STATE,
+            )
+
+        # Validate inputs (same as dispatch())
+        if not topic or not topic.strip():
+            raise ModelOnexError(
+                message="Topic cannot be empty or whitespace.",
+                error_code=EnumCoreErrorCode.INVALID_PARAMETER,
+            )
+
+        if envelope is None:
+            raise ModelOnexError(
+                message="Cannot dispatch None envelope. ModelEventEnvelope is required.",
+                error_code=EnumCoreErrorCode.INVALID_PARAMETER,
+            )
+
+        # Log transaction context at DEBUG level for traceability
+        correlation_id = envelope.correlation_id or uuid4()
+        self._logger.debug(
+            "dispatch_with_transaction called with tx context (tx_type=%s)",
+            type(tx).__name__,
+            extra=self._build_log_context(
+                topic=topic,
+                correlation_id=correlation_id,
+                trace_id=envelope.trace_id,
+            ),
+        )
+
+        # Current implementation: delegate to standard dispatch()
+        # The tx parameter is available for future handler context injection
+        # TODO(OMN-1740): Pass tx to handlers via dispatch context when needed
+        _ = tx  # Explicitly acknowledge tx parameter for future use
+
+        return await self.dispatch(topic=topic, envelope=envelope)
+
     def _find_matching_dispatchers(
         self,
         topic: str,

omnibase_infra/runtime/service_runtime_host_process.py

@@ -2730,18 +2730,12 @@ class RuntimeHostProcess:
         # Import architecture validator components
         from omnibase_infra.errors import ArchitectureViolationError
         from omnibase_infra.nodes.architecture_validator import (
+            HandlerArchitectureValidation,
             ModelArchitectureValidationRequest,
-            NodeArchitectureValidatorCompute,
         )
 
-        # Create or get container
-        container = self._get_or_create_container()
-
-        # Instantiate validator with rules
-        validator = NodeArchitectureValidatorCompute(
-            container=container,
-            rules=self._architecture_rules,
-        )
+        # Create handler with rules (declarative pattern - handler owns the logic)
+        handler = HandlerArchitectureValidation(rules=self._architecture_rules)
 
         # Build validation request
         # Note: At this point, handlers haven't been instantiated yet (that happens
@@ -2769,8 +2763,8 @@ class RuntimeHostProcess:
             handlers=tuple(handler_classes),
         )
 
-        # Execute validation
-        result = validator.compute(request)
+        # Execute validation via handler
+        result = handler.validate_architecture(request)
 
         # Separate blocking and non-blocking violations
         blocking_violations = tuple(v for v in result.violations if v.blocks_startup())
@@ -2924,6 +2918,7 @@ class RuntimeHostProcess:
             event_bus=cast("ProtocolEventBusSubscriber", self._event_bus),
             dispatch_engine=self._dispatch_engine,
             environment=environment,
+            node_name="runtime-host",
         )
 
         # Wire subscriptions for each handler with a contract

omnibase_infra/services/__init__.py

@@ -13,6 +13,7 @@ Exports:
     ModelTimeoutEmissionResult: Result model for timeout emission processing
     ModelTimeoutQueryResult: Result model for timeout queries
     ServiceCapabilityQuery: Query nodes by capability, not by name
+    ServiceContractPublisher: Publish contracts to Kafka for dynamic discovery
     ServiceNodeSelector: Select nodes from candidates using various strategies
     ServiceSnapshot: Generic snapshot service for point-in-time state capture
     ServiceTimeoutEmitter: Emitter for timeout events with markers
@@ -24,6 +25,25 @@ Exports:
 """
 
 from omnibase_infra.enums import EnumSelectionStrategy
+
+# Contract publisher service (OMN-1752)
+from omnibase_infra.services.contract_publisher import (
+    ContractPublisherError,
+    ContractPublishingInfraError,
+    ContractSourceNotConfiguredError,
+    ModelContractError,
+    ModelContractPublisherConfig,
+    ModelDiscoveredContract,
+    ModelInfraError,
+    ModelPublishResult,
+    ModelPublishStats,
+    NoContractsFoundError,
+    ProtocolContractPublisherSource,
+    ServiceContractPublisher,
+    SourceContractComposite,
+    SourceContractFilesystem,
+    SourceContractPackage,
+)
 from omnibase_infra.services.corpus_capture import CorpusCapture
 from omnibase_infra.services.service_capability_query import ServiceCapabilityQuery
 from omnibase_infra.services.service_node_selector import (
@@ -86,4 +106,20 @@ __all__ = [
     "SessionEventConsumer",
     "SessionSnapshotStore",
     "SessionStoreNotInitializedError",
+    # Contract publisher service (OMN-1752)
+    "ContractPublisherError",
+    "ContractPublishingInfraError",
+    "ContractSourceNotConfiguredError",
+    "ModelContractError",
+    "ModelContractPublisherConfig",
+    "ModelDiscoveredContract",
+    "ModelInfraError",
+    "ModelPublishResult",
+    "ModelPublishStats",
+    "NoContractsFoundError",
+    "ProtocolContractPublisherSource",
+    "ServiceContractPublisher",
+    "SourceContractComposite",
+    "SourceContractFilesystem",
+    "SourceContractPackage",
 ]

omnibase_infra/services/contract_publisher/__init__.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Publisher Service Module.
+
+Provides infrastructure for bulk contract discovery and publishing to Kafka.
+This service discovers contracts from configured sources (filesystem, package)
+and publishes them to the contract registration topic for dynamic discovery.
+
+Moved from omniclaude as part of OMN-1752 (ARCH-002 compliance).
+
+Design Principle:
+    Infra standardizes the publishing *engine*; apps provide *source configuration*.
+
+Flow:
+    Source → Validate → Normalize → Publish → Report
+    - Sources provide origin (filesystem, package)
+    - Event bus provides distribution (broadcast plane)
+
+Example:
+    >>> from omnibase_infra.services.contract_publisher import (
+    ...     ServiceContractPublisher,
+    ...     ModelContractPublisherConfig,
+    ... )
+    >>> config = ModelContractPublisherConfig(
+    ...     mode="filesystem",
+    ...     filesystem_root=Path("/app/contracts/handlers"),
+    ... )
+    >>> publisher = await ServiceContractPublisher.from_container(container, config)
+    >>> result = await publisher.publish_all()
+    >>> if result:
+    ...     print(f"Published {len(result.published)} contracts")
+    ... else:
+    ...     print(f"No contracts published, {len(result.contract_errors)} errors")
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+# Config
+from omnibase_infra.services.contract_publisher.config import (
+    ModelContractPublisherConfig,
+)
+
+# Errors
+from omnibase_infra.services.contract_publisher.errors import (
+    ContractPublisherError,
+    ContractPublishingInfraError,
+    ContractSourceNotConfiguredError,
+    NoContractsFoundError,
+)
+
+# Result models
+from omnibase_infra.services.contract_publisher.models import (
+    ModelContractError,
+    ModelInfraError,
+    ModelPublishResult,
+    ModelPublishStats,
+)
+
+# Service
+from omnibase_infra.services.contract_publisher.service import (
+    ServiceContractPublisher,
+)
+
+# Sources
+from omnibase_infra.services.contract_publisher.sources import (
+    ModelDiscoveredContract,
+    ProtocolContractPublisherSource,
+    SourceContractComposite,
+    SourceContractFilesystem,
+    SourceContractPackage,
+)
+
+__all__ = [
+    # Service
+    "ServiceContractPublisher",
+    # Config
+    "ModelContractPublisherConfig",
+    # Result models
+    "ModelPublishResult",
+    "ModelPublishStats",
+    "ModelContractError",
+    "ModelInfraError",
+    # Errors
+    "ContractPublisherError",
+    "ContractSourceNotConfiguredError",
+    "ContractPublishingInfraError",
+    "NoContractsFoundError",
+    # Sources
+    "ProtocolContractPublisherSource",
+    "ModelDiscoveredContract",
+    "SourceContractFilesystem",
+    "SourceContractPackage",
+    "SourceContractComposite",
+]

omnibase_infra/services/contract_publisher/config.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Publisher Configuration Model.
+
+This module defines the configuration model for contract publishing operations.
+Configuration is validated at construction time using Pydantic model validators.
+
+Configuration Options:
+    mode: Publishing source mode (filesystem, package, composite)
+    filesystem_root: Root directory for filesystem mode
+    package_module: Module name for package mode
+    fail_fast: Whether to raise on infrastructure errors
+    allow_zero_contracts: Whether to allow empty publish results
+    environment: Environment prefix for Kafka topics
+
+Environment Resolution:
+    The environment is resolved with precedence:
+    1. config.environment (if provided)
+    2. ONEX_ENV environment variable
+    3. Default "dev"
+
+Related:
+    - OMN-1752: Extract ContractPublisher to omnibase_infra
+    - ARCH-002: Runtime owns all Kafka plumbing
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ModelContractPublisherConfig(BaseModel):
+    """Configuration for contract publishing.
+
+    Defines the source mode and configuration for discovering and
+    publishing contracts to Kafka.
+
+    Source Modes:
+        filesystem: Discover contracts from a directory tree
+        package: Discover contracts from installed package resources
+        composite: Merge both sources with conflict detection
+
+    Configuration Rules (enforced by validator):
+        - filesystem mode requires filesystem_root
+        - package mode requires package_module
+        - composite mode requires at least one of filesystem_root or package_module
+
+    Attributes:
+        mode: Publishing source mode
+        filesystem_root: Root directory for filesystem discovery
+        package_module: Module name for package resource discovery
+        fail_fast: If True, raise immediately on infrastructure errors
+        allow_zero_contracts: If True, allow empty publish results
+        environment: Environment prefix for topics (defaults via resolve_environment)
+
+    Example:
+        >>> config = ModelContractPublisherConfig(
+        ...     mode="filesystem",
+        ...     filesystem_root=Path("/app/contracts/handlers"),
+        ...     fail_fast=True,
+        ...     allow_zero_contracts=False,
+        ... )
+        >>> env = config.resolve_environment()
+        >>> print(f"Publishing to {env}.onex.evt.contract-registered.v1")
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    mode: Literal["filesystem", "package", "composite"] = Field(
+        description="Publishing source mode"
+    )
+    filesystem_root: Path | None = Field(
+        default=None,
+        description="Root directory for filesystem discovery",
+    )
+    package_module: str | None = Field(
+        default=None,
+        description="Module name for package resource discovery (e.g., 'myapp.contracts')",
+    )
+    fail_fast: bool = Field(
+        default=True,
+        description="If True, raise immediately on infrastructure errors",
+    )
+    allow_zero_contracts: bool = Field(
+        default=False,
+        description="If True, allow empty publish results without raising",
+    )
+    environment: str | None = Field(
+        default=None,
+        description="Environment prefix for topics (resolved via resolve_environment)",
+    )
+
+    @model_validator(mode="after")
+    def validate_source_configured(self) -> Self:
+        """Validate that required source fields are configured for the mode.
+
+        Rules:
+            - filesystem mode requires filesystem_root
+            - package mode requires package_module
+            - composite mode requires at least one source
+
+        Returns:
+            Self if validation passes
+
+        Raises:
+            ValueError: If required source configuration is missing
+        """
+        match self.mode:
+            case "filesystem":
+                if not self.filesystem_root:
+                    raise ValueError("filesystem mode requires filesystem_root")
+            case "package":
+                if not self.package_module:
+                    raise ValueError("package mode requires package_module")
+            case "composite":
+                if not self.filesystem_root and not self.package_module:
+                    raise ValueError(
+                        "composite mode requires at least one source "
+                        "(filesystem_root or package_module)"
+                    )
+        return self
+
+    def resolve_environment(self) -> str:
+        """Resolve environment with precedence: config > env var > 'dev'.
+
+        Resolution Order:
+            1. self.environment (if provided and non-empty after normalization)
+            2. ONEX_ENV environment variable (if set and non-empty after normalization)
+            3. Default "dev"
+
+        Normalization:
+            - Whitespace is stripped
+            - Trailing dots are removed (to prevent "dev..topic" issues)
+
+        Note:
+            Whitespace-only strings (e.g., "   ") are treated as empty and
+            fall through to the next priority level.
+
+        Returns:
+            Resolved environment string, normalized
+
+        Example:
+            >>> config = ModelContractPublisherConfig(
+            ...     mode="filesystem",
+            ...     filesystem_root=Path("/app"),
+            ...     environment="prod",
+            ... )
+            >>> config.resolve_environment()
+            'prod'
+
+            >>> # With no config.environment and ONEX_ENV=staging
+            >>> config2 = ModelContractPublisherConfig(
+            ...     mode="filesystem",
+            ...     filesystem_root=Path("/app"),
+            ... )
+            >>> # Returns "staging" if ONEX_ENV is set, else "dev"
+        """
+        # Priority 1: Explicit config (if non-empty after normalization)
+        if self.environment:
+            normalized = self._normalize_environment(self.environment)
+            if normalized:
+                return normalized
+
+        # Priority 2: Environment variable (if non-empty after normalization)
+        env_var = os.getenv("ONEX_ENV", "")
+        if env_var:
+            normalized = self._normalize_environment(env_var)
+            if normalized:
+                return normalized
+
+        # Priority 3: Default
+        return "dev"
+
+    @staticmethod
+    def _normalize_environment(value: str) -> str:
+        """Normalize environment string.
+
+        Strips whitespace and removes trailing dots to prevent
+        topic formatting issues like "dev..topic".
+
+        Args:
+            value: Raw environment value
+
+        Returns:
+            Normalized environment string
+        """
+        return value.strip().rstrip(".")
+
+
+__all__ = ["ModelContractPublisherConfig"]