feat(OMN-1752): Extract ContractPublisher service to omnibase_infra

pyproject.toml

@@ -36,7 +36,7 @@ python = "^3.12"
 #   omnibase-core = { git = "https://github.com/org/omnibase_core.git", rev = "SHA" }
 # Remember to switch back to PyPI versions before merging to main.
 #
-# omnibase-core v0.10.2: Adds TOPIC_SUFFIX_CONTRACT_* constants
+# omnibase-core v0.10.2: Adds TOPIC_SUFFIX_CONTRACT_* constants and request_response schema (OMN-1760)
 omnibase-core = "^0.10.2"
 # omnibase-spi v0.6.4: Version bump
 omnibase-spi = "^0.6.4"

src/omnibase_infra/services/__init__.py

@@ -13,6 +13,7 @@
     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 @@
 """
 
 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 @@
     "SessionEventConsumer",
     "SessionSnapshotStore",
     "SessionStoreNotInitializedError",
+    # Contract publisher service (OMN-1752)
+    "ContractPublisherError",
+    "ContractPublishingInfraError",
+    "ContractSourceNotConfiguredError",
+    "ModelContractError",
+    "ModelContractPublisherConfig",
+    "ModelDiscoveredContract",
+    "ModelInfraError",
+    "ModelPublishResult",
+    "ModelPublishStats",
+    "NoContractsFoundError",
+    "ProtocolContractPublisherSource",
+    "ServiceContractPublisher",
+    "SourceContractComposite",
+    "SourceContractFilesystem",
+    "SourceContractPackage",
 ]

src/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",
+]

src/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"]