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

omnibase_infra/runtime/service_kernel.py

@@ -55,6 +55,7 @@ import signal
 import sys
 import time
 from collections.abc import Awaitable, Callable
+from functools import partial
 from importlib.metadata import version as get_package_version
 from pathlib import Path
 from typing import cast
@@ -75,7 +76,15 @@ from omnibase_infra.errors import (
 from omnibase_infra.event_bus.event_bus_inmemory import EventBusInmemory
 from omnibase_infra.event_bus.event_bus_kafka import EventBusKafka
 from omnibase_infra.event_bus.models.config import ModelKafkaEventBusConfig
+from omnibase_infra.event_bus.models.model_event_message import ModelEventMessage
 from omnibase_infra.models import ModelNodeIdentity
+from omnibase_infra.nodes.contract_registry_reducer.contract_registration_event_router import (
+    ContractRegistrationEventRouter,
+    ProtocolIntentEffect,
+)
+from omnibase_infra.nodes.contract_registry_reducer.reducer import (
+    ContractRegistryReducer,
+)
 from omnibase_infra.nodes.node_registration_orchestrator.dispatchers import (
     DispatcherNodeIntrospected,
 )
@@ -423,6 +432,11 @@ async def bootstrap() -> int:
     health_server: ServiceHealth | None = None
     postgres_pool: asyncpg.Pool | None = None
     introspection_unsubscribe: Callable[[], Awaitable[None]] | None = None
+    # Contract registry unsubscribe functions and router
+    contract_router: ContractRegistrationEventRouter | None = None
+    contract_unsub_registered: Callable[[], Awaitable[None]] | None = None
+    contract_unsub_deregistered: Callable[[], Awaitable[None]] | None = None
+    contract_unsub_heartbeat: Callable[[], Awaitable[None]] | None = None
     correlation_id = generate_correlation_id()
     bootstrap_start_time = time.time()
 
@@ -458,6 +472,7 @@ async def bootstrap() -> int:
 
         # 3. Create event bus
         # Dispatch based on configuration or environment variable:
+        # - ONEX_EVENT_BUS_TYPE env var overrides config.event_bus.type
         # - If KAFKA_BOOTSTRAP_SERVERS env var is set, use EventBusKafka
         # - If config.event_bus.type == "kafka", use EventBusKafka
         # - Otherwise, use EventBusInmemory for local development/testing
@@ -465,12 +480,54 @@ async def bootstrap() -> int:
         environment = os.getenv("ONEX_ENVIRONMENT") or config.event_bus.environment
         kafka_bootstrap_servers = os.getenv("KAFKA_BOOTSTRAP_SERVERS")
 
-        # Explicit bool evaluation (not truthy string) for kafka usage.
-        # KAFKA_BOOTSTRAP_SERVERS env var takes precedence over config.event_bus.type.
-        # This prevents implicit "kafka but localhost" fallback scenarios.
-        use_kafka: bool = (
-            bool(kafka_bootstrap_servers) or config.event_bus.type == "kafka"
-        )
+        # Check for ONEX_EVENT_BUS_TYPE environment variable override
+        # This allows CI/testing environments to force inmemory event bus
+        # even when the config file defaults to kafka.
+        event_bus_type_override = os.getenv("ONEX_EVENT_BUS_TYPE", "").lower()
+        if event_bus_type_override:
+            logger.debug(
+                "Event bus type override from ONEX_EVENT_BUS_TYPE=%s (correlation_id=%s)",
+                event_bus_type_override,
+                correlation_id,
+            )
+
+        # Determine effective event bus type with override precedence:
+        # 1. ONEX_EVENT_BUS_TYPE env var (highest priority)
+        # 2. KAFKA_BOOTSTRAP_SERVERS env var (if set, implies kafka)
+        # 3. config.event_bus.type (from runtime_config.yaml)
+        if event_bus_type_override == "inmemory":
+            # Explicit inmemory override - use inmemory regardless of other config
+            use_kafka = False
+            logger.info(
+                "Using inmemory event bus (ONEX_EVENT_BUS_TYPE override) (correlation_id=%s)",
+                correlation_id,
+            )
+        elif event_bus_type_override == "kafka":
+            # Explicit kafka override - validate that bootstrap_servers is available
+            use_kafka = True
+        elif event_bus_type_override and event_bus_type_override not in (
+            "inmemory",
+            "kafka",
+        ):
+            # Invalid override value - warn and fall back to config
+            logger.warning(
+                "Invalid ONEX_EVENT_BUS_TYPE value '%s', expected 'inmemory' or 'kafka'. "
+                "Falling back to config.event_bus.type='%s' (correlation_id=%s)",
+                event_bus_type_override,
+                config.event_bus.type,
+                correlation_id,
+            )
+            use_kafka = (
+                bool(kafka_bootstrap_servers) or config.event_bus.type == "kafka"
+            )
+        else:
+            # No override - use original logic
+            # Explicit bool evaluation (not truthy string) for kafka usage.
+            # KAFKA_BOOTSTRAP_SERVERS env var takes precedence over config.event_bus.type.
+            # This prevents implicit "kafka but localhost" fallback scenarios.
+            use_kafka = (
+                bool(kafka_bootstrap_servers) or config.event_bus.type == "kafka"
+            )
 
         # Validate bootstrap_servers is provided when kafka is requested via config
         # This prevents confusing implicit localhost:9092 fallback
@@ -931,6 +988,81 @@ async def bootstrap() -> int:
                         },
                     )
 
+                # 4.9. Wire ContractRegistrationEventRouter if contract_registry.enabled
+                # This router subscribes to contract lifecycle events (registration,
+                # deregistration, heartbeat) and routes them to the ContractRegistryReducer.
+                # The router also runs an internal tick timer for staleness computation.
+                if config.contract_registry.enabled and postgres_pool is not None:
+                    # Import postgres handlers for contract persistence
+                    # Deferred import to avoid loading heavy dependencies when not needed
+                    from omnibase_infra.nodes.node_contract_persistence_effect.handlers import (
+                        HandlerPostgresCleanupTopics,
+                        HandlerPostgresContractUpsert,
+                        HandlerPostgresDeactivate,
+                        HandlerPostgresHeartbeat,
+                        HandlerPostgresMarkStale,
+                        HandlerPostgresTopicUpdate,
+                    )
+
+                    # Create effect handlers keyed by intent_type
+                    # These handlers execute PostgreSQL operations for intents from the reducer
+                    # Note: Handlers implement ProtocolIntentEffect duck-typing style with
+                    # more specific payload types. Cast tells mypy they satisfy the protocol.
+                    contract_effect_handlers: dict[str, ProtocolIntentEffect] = {
+                        "postgres.upsert_contract": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresContractUpsert(postgres_pool),
+                        ),
+                        "postgres.update_topic": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresTopicUpdate(postgres_pool),
+                        ),
+                        "postgres.mark_stale": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresMarkStale(postgres_pool),
+                        ),
+                        "postgres.update_heartbeat": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresHeartbeat(postgres_pool),
+                        ),
+                        "postgres.deactivate_contract": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresDeactivate(postgres_pool),
+                        ),
+                        "postgres.cleanup_topic_references": cast(
+                            "ProtocolIntentEffect",
+                            HandlerPostgresCleanupTopics(postgres_pool),
+                        ),
+                    }
+
+                    # Create reducer and router
+                    contract_reducer = ContractRegistryReducer()
+                    contract_router = ContractRegistrationEventRouter(
+                        container=container,
+                        reducer=contract_reducer,
+                        effect_handlers=contract_effect_handlers,
+                        event_bus=event_bus,
+                        tick_interval_seconds=config.contract_registry.tick_interval_seconds,
+                    )
+
+                    logger.info(
+                        "ContractRegistrationEventRouter created (correlation_id=%s)",
+                        correlation_id,
+                        extra={
+                            "tick_interval_seconds": config.contract_registry.tick_interval_seconds,
+                            "handler_count": len(contract_effect_handlers),
+                        },
+                    )
+                else:
+                    logger.debug(
+                        "Contract registry disabled or no postgres_pool (correlation_id=%s)",
+                        correlation_id,
+                        extra={
+                            "contract_registry_enabled": config.contract_registry.enabled,
+                            "postgres_pool_available": postgres_pool is not None,
+                        },
+                    )
+
             except Exception as pool_error:
                 # Log warning but continue without registration support
                 # Use sanitize_error_message to prevent credential leakage in logs
@@ -1298,6 +1430,84 @@ async def bootstrap() -> int:
                 },
             )
 
+        # 9.6. Start contract registry event consumer if router is available
+        # This consumer subscribes to 3 Kafka topics for contract lifecycle events
+        # and routes them to the ContractRegistryReducer for projection.
+        if contract_router is not None and has_subscribe:
+            # Create typed node identity for contract registry subscriptions
+            contract_node_identity = ModelNodeIdentity(
+                env=environment,
+                service=config.name or "onex-kernel",
+                node_name="contract-registry",
+                version=config.contract_version or "v1",
+            )
+
+            # Subscribe to 3 contract lifecycle topics with same identity
+            contract_subscribe_start_time = time.time()
+
+            # Derive environment-aware topic names (avoid hardcoded "dev." prefix)
+            contract_registered_topic = (
+                f"{environment}.onex.evt.platform.contract-registered.v1"
+            )
+            contract_deregistered_topic = (
+                f"{environment}.onex.evt.platform.contract-deregistered.v1"
+            )
+            node_heartbeat_topic = f"{environment}.onex.evt.platform.node-heartbeat.v1"
+
+            logger.info(
+                "Subscribing to contract registry events on event bus (correlation_id=%s)",
+                correlation_id,
+                extra={
+                    "topics": [
+                        contract_registered_topic,
+                        contract_deregistered_topic,
+                        node_heartbeat_topic,
+                    ],
+                    "node_identity": {
+                        "env": contract_node_identity.env,
+                        "service": contract_node_identity.service,
+                        "node_name": contract_node_identity.node_name,
+                        "version": contract_node_identity.version,
+                    },
+                    "purpose": EnumConsumerGroupPurpose.CONTRACT_REGISTRY.value,
+                },
+            )
+
+            contract_unsub_registered = await event_bus.subscribe(
+                topic=contract_registered_topic,
+                node_identity=contract_node_identity,
+                on_message=contract_router.handle_message,
+                purpose=EnumConsumerGroupPurpose.CONTRACT_REGISTRY,
+            )
+            contract_unsub_deregistered = await event_bus.subscribe(
+                topic=contract_deregistered_topic,
+                node_identity=contract_node_identity,
+                on_message=contract_router.handle_message,
+                purpose=EnumConsumerGroupPurpose.CONTRACT_REGISTRY,
+            )
+            contract_unsub_heartbeat = await event_bus.subscribe(
+                topic=node_heartbeat_topic,
+                node_identity=contract_node_identity,
+                on_message=contract_router.handle_message,
+                purpose=EnumConsumerGroupPurpose.CONTRACT_REGISTRY,
+            )
+
+            # Start the router's tick timer
+            await contract_router.start()
+
+            contract_subscribe_duration = time.time() - contract_subscribe_start_time
+            logger.info(
+                "Contract registry event consumers started successfully in %.3fs (correlation_id=%s)",
+                contract_subscribe_duration,
+                correlation_id,
+                extra={
+                    "topics_count": 3,
+                    "tick_interval_seconds": contract_router.tick_interval_seconds,
+                    "subscribe_duration_seconds": contract_subscribe_duration,
+                    "event_bus_type": event_bus_type,
+                },
+            )
+
         # Calculate total bootstrap time
         bootstrap_duration = time.time() - bootstrap_start_time
 
@@ -1309,14 +1519,24 @@ async def bootstrap() -> int:
                 registration_status = "enabled (PostgreSQL only)"
         else:
             registration_status = "disabled"
+
+        # Contract registry status for banner
+        if contract_router is not None:
+            contract_registry_status = (
+                f"enabled (tick: {config.contract_registry.tick_interval_seconds}s)"
+            )
+        else:
+            contract_registry_status = "disabled"
+
         banner_lines = [
             "=" * 60,
             f"ONEX Runtime Kernel v{KERNEL_VERSION}",
             f"Environment: {environment}",
             f"Contracts: {contracts_dir}",
             f"Event Bus: {event_bus_type} (group: {config.consumer_group})",
-            f"Topics: {config.input_topic} → {config.output_topic}",
+            f"Topics: {config.input_topic} -> {config.output_topic}",
             f"Registration: {registration_status}",
+            f"Contract Registry: {contract_registry_status}",
             f"Health endpoint: http://0.0.0.0:{http_port}/health",
             f"Bootstrap time: {bootstrap_duration:.3f}s",
             f"Correlation ID: {correlation_id}",
@@ -1367,6 +1587,47 @@ async def bootstrap() -> int:
                 )
             introspection_unsubscribe = None
 
+        # Stop contract registry router and consumers
+        if contract_router is not None:
+            try:
+                await contract_router.stop()
+                logger.debug(
+                    "Contract registry router stopped (correlation_id=%s)",
+                    correlation_id,
+                )
+            except Exception as router_stop_error:
+                logger.warning(
+                    "Failed to stop contract registry router: %s (correlation_id=%s)",
+                    sanitize_error_message(router_stop_error),
+                    correlation_id,
+                )
+            contract_router = None
+
+        # Unsubscribe from contract registry topics
+        for unsub_name, unsub_func in [
+            ("contract-registered", contract_unsub_registered),
+            ("contract-deregistered", contract_unsub_deregistered),
+            ("node-heartbeat", contract_unsub_heartbeat),
+        ]:
+            if unsub_func is not None:
+                try:
+                    await unsub_func()
+                    logger.debug(
+                        "Contract registry consumer %s stopped (correlation_id=%s)",
+                        unsub_name,
+                        correlation_id,
+                    )
+                except Exception as unsub_error:
+                    logger.warning(
+                        "Failed to stop contract registry consumer %s: %s (correlation_id=%s)",
+                        unsub_name,
+                        sanitize_error_message(unsub_error),
+                        correlation_id,
+                    )
+        contract_unsub_registered = None
+        contract_unsub_deregistered = None
+        contract_unsub_heartbeat = None
+
         # Stop health server (fast, non-blocking)
         if health_server is not None:
             try:
@@ -1492,7 +1753,7 @@ async def bootstrap() -> int:
 
     finally:
         # Guard cleanup - stop all resources if not already stopped
-        # Order: introspection consumer -> health server -> runtime -> pool
+        # Order: introspection consumer -> contract registry -> health server -> runtime -> pool
 
         if introspection_unsubscribe is not None:
             try:
@@ -1504,6 +1765,32 @@ async def bootstrap() -> int:
                     correlation_id,
                 )
 
+        # Cleanup contract registry router and consumers
+        if contract_router is not None:
+            try:
+                await contract_router.stop()
+            except Exception as cleanup_error:
+                logger.warning(
+                    "Failed to stop contract registry router during cleanup: %s (correlation_id=%s)",
+                    sanitize_error_message(cleanup_error),
+                    correlation_id,
+                )
+
+        for unsub_func in [
+            contract_unsub_registered,
+            contract_unsub_deregistered,
+            contract_unsub_heartbeat,
+        ]:
+            if unsub_func is not None:
+                try:
+                    await unsub_func()
+                except Exception as cleanup_error:
+                    logger.warning(
+                        "Failed to stop contract registry consumer during cleanup: %s (correlation_id=%s)",
+                        sanitize_error_message(cleanup_error),
+                        correlation_id,
+                    )
+
         if health_server is not None:
             try:
                 await health_server.stop()

omnibase_infra/services/registry_api/models/__init__.py

@@ -13,11 +13,18 @@ Design Principles:
 
 Related Tickets:
     - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+    - OMN-1845: Contract Registry Persistence
 """
 
 from omnibase_infra.services.registry_api.models.model_capability_widget_mapping import (
     ModelCapabilityWidgetMapping,
 )
+from omnibase_infra.services.registry_api.models.model_contract_ref import (
+    ModelContractRef,
+)
+from omnibase_infra.services.registry_api.models.model_contract_view import (
+    ModelContractView,
+)
 from omnibase_infra.services.registry_api.models.model_pagination_info import (
     ModelPaginationInfo,
 )
@@ -36,12 +43,24 @@ from omnibase_infra.services.registry_api.models.model_registry_node_view import
 from omnibase_infra.services.registry_api.models.model_registry_summary import (
     ModelRegistrySummary,
 )
+from omnibase_infra.services.registry_api.models.model_response_contracts import (
+    ModelResponseListContracts,
+)
 from omnibase_infra.services.registry_api.models.model_response_list_instances import (
     ModelResponseListInstances,
 )
 from omnibase_infra.services.registry_api.models.model_response_list_nodes import (
     ModelResponseListNodes,
 )
+from omnibase_infra.services.registry_api.models.model_response_topics import (
+    ModelResponseListTopics,
+)
+from omnibase_infra.services.registry_api.models.model_topic_summary import (
+    ModelTopicSummary,
+)
+from omnibase_infra.services.registry_api.models.model_topic_view import (
+    ModelTopicView,
+)
 from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
 from omnibase_infra.services.registry_api.models.model_widget_defaults import (
     ModelWidgetDefaults,
@@ -52,14 +71,20 @@ from omnibase_infra.services.registry_api.models.model_widget_mapping import (
 
 __all__ = [
     "ModelCapabilityWidgetMapping",
+    "ModelContractRef",
+    "ModelContractView",
     "ModelPaginationInfo",
     "ModelRegistryDiscoveryResponse",
     "ModelRegistryHealthResponse",
     "ModelRegistryInstanceView",
     "ModelRegistryNodeView",
     "ModelRegistrySummary",
+    "ModelResponseListContracts",
     "ModelResponseListInstances",
     "ModelResponseListNodes",
+    "ModelResponseListTopics",
+    "ModelTopicSummary",
+    "ModelTopicView",
     "ModelWarning",
     "ModelWidgetDefaults",
     "ModelWidgetMapping",

omnibase_infra/services/registry_api/models/model_contract_ref.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract reference model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractRef(BaseModel):
+    """Lightweight contract reference.
+
+    Used to reference a contract without including full details,
+    suitable for embedding in topic views.
+
+    Attributes:
+        contract_id: Unique identifier in format node_name:major.minor.patch
+        node_name: Name of the node this contract belongs to
+        version: Semantic version string in format major.minor.patch
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ...,
+        description="Unique identifier in format node_name:major.minor.patch",
+    )
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(
+        ...,
+        description="Name of the node this contract belongs to",
+    )
+    version: str = Field(
+        ...,
+        description="Semantic version string in format major.minor.patch",
+    )
+
+
+__all__ = ["ModelContractRef"]

omnibase_infra/services/registry_api/models/model_contract_view.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract view model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractView(BaseModel):
+    """Contract detail for API responses.
+
+    Represents a registered contract from the contract registry,
+    flattened for dashboard consumption.
+
+    Attributes:
+        contract_id: Unique identifier in format node_name:major.minor.patch
+        node_name: Name of the node this contract belongs to
+        version: Semantic version string in format major.minor.patch
+        contract_hash: SHA-256 hash of contract content for integrity verification
+        is_active: Whether the contract is currently active
+        registered_at: Timestamp of initial registration
+        last_seen_at: Timestamp of last activity (heartbeat or event)
+        deregistered_at: Timestamp when contract was deregistered (None if active)
+        topics_published: List of topic suffixes this contract publishes to
+        topics_subscribed: List of topic suffixes this contract subscribes to
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ...,
+        description="Unique identifier in format node_name:major.minor.patch",
+    )
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(
+        ...,
+        description="Name of the node this contract belongs to",
+    )
+    version: str = Field(
+        ...,
+        description="Semantic version string in format major.minor.patch",
+    )
+    contract_hash: str = Field(
+        ...,
+        description="SHA-256 hash of contract content for integrity verification",
+    )
+    is_active: bool = Field(
+        ...,
+        description="Whether the contract is currently active",
+    )
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp of initial registration",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp of last activity (heartbeat or event)",
+    )
+    deregistered_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when contract was deregistered (None if active)",
+    )
+    topics_published: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="List of topic suffixes this contract publishes to",
+    )
+    topics_subscribed: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="List of topic suffixes this contract subscribes to",
+    )
+
+
+__all__ = ["ModelContractView"]

omnibase_infra/services/registry_api/models/model_response_contracts.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for list_contracts endpoint.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_contract_view import (
+    ModelContractView,
+)
+from omnibase_infra.services.registry_api.models.model_pagination_info import (
+    ModelPaginationInfo,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+
+
+class ModelResponseListContracts(BaseModel):
+    """Response model for the GET /registry/contracts endpoint.
+
+    Provides a paginated list of registered contracts with optional warnings
+    for partial success scenarios.
+
+    Attributes:
+        contracts: List of registered contracts matching the query
+        pagination: Pagination information for the result set
+        warnings: List of warnings for partial success scenarios
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    contracts: list[ModelContractView] = Field(
+        default_factory=list,
+        description="List of registered contracts matching the query",
+    )
+    pagination: ModelPaginationInfo = Field(
+        ...,
+        description="Pagination information for the result set",
+    )
+    warnings: list[ModelWarning] = Field(
+        default_factory=list,
+        description="Warnings for partial success scenarios",
+    )
+
+
+__all__ = ["ModelResponseListContracts"]

omnibase_infra/services/registry_api/models/model_response_topics.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for list_topics endpoint.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_pagination_info import (
+    ModelPaginationInfo,
+)
+from omnibase_infra.services.registry_api.models.model_topic_summary import (
+    ModelTopicSummary,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+
+
+class ModelResponseListTopics(BaseModel):
+    """Response model for the GET /registry/topics endpoint.
+
+    Provides a paginated list of topics with optional warnings
+    for partial success scenarios.
+
+    Attributes:
+        topics: List of topic summaries matching the query
+        pagination: Pagination information for the result set
+        warnings: List of warnings for partial success scenarios
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    topics: list[ModelTopicSummary] = Field(
+        default_factory=list,
+        description="List of topic summaries matching the query",
+    )
+    pagination: ModelPaginationInfo = Field(
+        ...,
+        description="Pagination information for the result set",
+    )
+    warnings: list[ModelWarning] = Field(
+        default_factory=list,
+        description="Warnings for partial success scenarios",
+    )
+
+
+__all__ = ["ModelResponseListTopics"]