feat(BA-6891): add kernel scheduling-history v2 DTOs and service actions

The admin search is system-wide and unscoped, so its authorization is the
SUPERADMIN role gate rather than RBAC scope resolution: it is a
BaseGlobalAction run through GlobalActionProcessor, which applies the gate
on the action path behind the route's superadmin_required middleware. The
scoped counterpart resolves against an RBAC scope and stays on the plain
action path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jopemachine

changes/12869.feature.md

@@ -0,0 +1 @@
+Add the v2 DTOs and service actions for kernel scheduling-history search, forming the schema shared by REST v2 and GraphQL.

src/ai/backend/common/dto/manager/v2/scheduling_history/__init__.py

@@ -4,12 +4,16 @@
 
 from ai.backend.common.dto.manager.v2.scheduling_history.request import (
     AdminSearchDeploymentHistoriesInput,
+    AdminSearchKernelHistoriesInput,
     AdminSearchRouteHistoriesInput,
     AdminSearchSessionHistoriesInput,
     DeploymentHistoryFilter,
     DeploymentHistoryOrder,
+    KernelHistoryFilter,
+    KernelHistoryOrder,
     RouteHistoryFilter,
     RouteHistoryOrder,
+    ScopedSearchKernelHistoriesInput,
     SearchDeploymentHistoryInput,
     SearchRouteHistoryInput,
     SearchSessionHistoryInput,
@@ -18,9 +22,11 @@
 )
 from ai.backend.common.dto.manager.v2.scheduling_history.response import (
     AdminSearchDeploymentHistoriesPayload,
+    AdminSearchKernelHistoriesPayload,
     AdminSearchRouteHistoriesPayload,
     AdminSearchSessionHistoriesPayload,
     DeploymentHistoryNode,
+    KernelHistoryNode,
     ListDeploymentHistoryPayload,
     ListRouteHistoryPayload,
     ListSessionHistoryPayload,
@@ -30,6 +36,8 @@
 from ai.backend.common.dto.manager.v2.scheduling_history.types import (
     DeploymentHistoryOrderField,
     DeploymentHistoryScopeDTO,
+    KernelHistoryOrderField,
+    KernelHistoryScopeDTO,
     OrderDirection,
     RouteHistoryOrderField,
     RouteHistoryScopeDTO,
@@ -43,6 +51,8 @@
     # Types
     "DeploymentHistoryOrderField",
     "DeploymentHistoryScopeDTO",
+    "KernelHistoryOrderField",
+    "KernelHistoryScopeDTO",
     "OrderDirection",
     "RouteHistoryOrderField",
     "RouteHistoryScopeDTO",
@@ -52,22 +62,28 @@
     "SubStepResultInfo",
     # Input models (request)
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
+    "ScopedSearchKernelHistoriesInput",
     "SearchDeploymentHistoryInput",
     "SearchRouteHistoryInput",
     "SearchSessionHistoryInput",
     "SessionHistoryFilter",
     "SessionHistoryOrder",
     # Response models
     "AdminSearchDeploymentHistoriesPayload",
+    "AdminSearchKernelHistoriesPayload",
     "AdminSearchRouteHistoriesPayload",
     "AdminSearchSessionHistoriesPayload",
     "DeploymentHistoryNode",
+    "KernelHistoryNode",
     "ListDeploymentHistoryPayload",
     "ListRouteHistoryPayload",
     "ListSessionHistoryPayload",

src/ai/backend/common/dto/manager/v2/scheduling_history/request.py

@@ -11,6 +11,8 @@
 
 from .types import (
     DeploymentHistoryOrderField,
+    KernelHistoryOrderField,
+    KernelHistoryScopeDTO,
     OrderDirection,
     RouteHistoryOrderField,
     SchedulingResultType,
@@ -19,13 +21,17 @@
 
 __all__ = (
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
     "SchedulingResultFilter",
+    "ScopedSearchKernelHistoriesInput",
     "SearchDeploymentHistoryInput",
     "SearchRouteHistoryInput",
     "SearchSessionHistoryInput",
@@ -86,6 +92,37 @@ class SearchSessionHistoryInput(BaseRequestModel):
     offset: int = Field(default=0, ge=0, description="Number of items to skip")
 
 
+class KernelHistoryFilter(BaseRequestModel):
+    """Filter conditions for kernel scheduling history search."""
+
+    id: UUIDFilter | None = Field(default=None, description="Filter by history record ID")
+    kernel_id: UUIDFilter | None = Field(default=None, description="Filter by kernel ID")
+    session_id: UUIDFilter | None = Field(default=None, description="Filter by session ID")
+    phase: StringFilter | None = Field(default=None, description="Filter by scheduling phase")
+    from_status: list[str] | None = Field(default=None, description="Filter by from_status values")
+    to_status: list[str] | None = Field(default=None, description="Filter by to_status values")
+    result: SchedulingResultFilter | None = Field(
+        default=None, description="Filter by scheduling result"
+    )
+    error_code: StringFilter | None = Field(default=None, description="Filter by error code")
+    message: StringFilter | None = Field(default=None, description="Filter by message")
+    created_at: DateTimeFilter | None = Field(default=None, description="Filter by created_at")
+    updated_at: DateTimeFilter | None = Field(default=None, description="Filter by updated_at")
+    AND: list[KernelHistoryFilter] | None = Field(default=None, description="AND conjunction.")
+    OR: list[KernelHistoryFilter] | None = Field(default=None, description="OR conjunction.")
+    NOT: list[KernelHistoryFilter] | None = Field(default=None, description="NOT negation.")
+
+
+KernelHistoryFilter.model_rebuild()
+
+
+class KernelHistoryOrder(BaseRequestModel):
+    """Order specification for kernel scheduling history."""
+
+    field: KernelHistoryOrderField = Field(description="Field to order by")
+    direction: OrderDirection = Field(default=OrderDirection.DESC, description="Order direction")
+
+
 class DeploymentHistoryFilter(BaseRequestModel):
     """Filter conditions for deployment scheduling history search."""
 
@@ -182,6 +219,37 @@ class AdminSearchSessionHistoriesInput(BaseRequestModel):
     offset: int | None = Field(default=None, description="Offset pagination: number to skip")
 
 
+class AdminSearchKernelHistoriesInput(BaseRequestModel):
+    """Input for admin search of kernel scheduling histories."""
+
+    filter: KernelHistoryFilter | None = Field(default=None, description="Filter conditions")
+    order: list[KernelHistoryOrder] | None = Field(default=None, description="Order specifications")
+    first: int | None = Field(default=None, description="Cursor pagination: number of items")
+    after: str | None = Field(default=None, description="Cursor pagination: after cursor")
+    last: int | None = Field(default=None, description="Cursor pagination: last N items")
+    before: str | None = Field(default=None, description="Cursor pagination: before cursor")
+    limit: int | None = Field(default=None, description="Offset pagination: maximum items")
+    offset: int | None = Field(default=None, description="Offset pagination: number to skip")
+
+
+class ScopedSearchKernelHistoriesInput(BaseRequestModel):
+    """Input for scoped search of kernel scheduling histories.
+
+    Unlike the session/deployment/route scoped searches, the scope is carried in the body
+    because a kernel query may be scoped by session_id, kernel_id, or both.
+    """
+
+    scope: KernelHistoryScopeDTO = Field(description="Required. Restricts the rows returned.")
+    filter: KernelHistoryFilter | None = Field(default=None, description="Filter conditions")
+    order: list[KernelHistoryOrder] | None = Field(default=None, description="Order specifications")
+    first: int | None = Field(default=None, description="Cursor pagination: number of items")
+    after: str | None = Field(default=None, description="Cursor pagination: after cursor")
+    last: int | None = Field(default=None, description="Cursor pagination: last N items")
+    before: str | None = Field(default=None, description="Cursor pagination: before cursor")
+    limit: int | None = Field(default=None, description="Offset pagination: maximum items")
+    offset: int | None = Field(default=None, description="Offset pagination: number to skip")
+
+
 class AdminSearchDeploymentHistoriesInput(BaseRequestModel):
     """Input for admin search of deployment histories."""
 

src/ai/backend/common/dto/manager/v2/scheduling_history/response.py

@@ -16,9 +16,11 @@
 
 __all__ = (
     "AdminSearchDeploymentHistoriesPayload",
+    "AdminSearchKernelHistoriesPayload",
     "AdminSearchRouteHistoriesPayload",
     "AdminSearchSessionHistoriesPayload",
     "DeploymentHistoryNode",
+    "KernelHistoryNode",
     "ListDeploymentHistoryPayload",
     "ListRouteHistoryPayload",
     "ListSessionHistoryPayload",
@@ -46,6 +48,26 @@ class SessionHistoryNode(BaseResponseModel):
     updated_at: datetime = Field(description="Timestamp when the history record was last updated")
 
 
+class KernelHistoryNode(BaseResponseModel):
+    """Node model representing a kernel scheduling history record.
+
+    Has no ``sub_steps``: the ``kernel_scheduling_history`` table carries no such column.
+    """
+
+    id: UUID = Field(description="History record ID")
+    kernel_id: UUID = Field(description="Kernel ID this history belongs to")
+    session_id: UUID = Field(description="Session owning the kernel")
+    phase: str = Field(description="Scheduling phase")
+    from_status: str | None = Field(default=None, description="Status before transition")
+    to_status: str | None = Field(default=None, description="Status after transition")
+    result: str = Field(description="Result of the scheduling attempt")
+    error_code: str | None = Field(default=None, description="Error code if scheduling failed")
+    message: str | None = Field(default=None, description="Human-readable message or error detail")
+    attempts: int = Field(description="Number of scheduling attempts made")
+    created_at: datetime = Field(description="Timestamp when the history record was created")
+    updated_at: datetime = Field(description="Timestamp when the history record was last updated")
+
+
 class DeploymentHistoryNode(BaseResponseModel):
     """Node model representing a deployment scheduling history record.
 
@@ -127,6 +149,15 @@ class AdminSearchSessionHistoriesPayload(BaseResponseModel):
     has_previous_page: bool = Field(description="Whether there is a previous page.")
 
 
+class AdminSearchKernelHistoriesPayload(BaseResponseModel):
+    """Payload for admin and scoped search of kernel scheduling histories."""
+
+    items: list[KernelHistoryNode] = Field(description="List of kernel history nodes.")
+    total_count: int = Field(description="Total number of records matching the filter.")
+    has_next_page: bool = Field(description="Whether there is a next page.")
+    has_previous_page: bool = Field(description="Whether there is a previous page.")
+
+
 class AdminSearchDeploymentHistoriesPayload(BaseResponseModel):
     """Payload for admin search of deployment histories."""
 

src/ai/backend/common/dto/manager/v2/scheduling_history/types.py

@@ -8,15 +8,17 @@
 from enum import StrEnum
 from uuid import UUID
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
 from ai.backend.common.api_handlers import BaseRequestModel, BaseResponseModel
 from ai.backend.common.dto.manager.v2.common import OrderDirection
+from ai.backend.common.types import KernelId, SessionId
 
 __all__ = (
     "DeploymentHistoryOrderField",
     "DeploymentHistoryScopeDTO",
     "KernelHistoryOrderField",
+    "KernelHistoryScopeDTO",
     "OrderDirection",
     "RouteHistoryOrderField",
     "RouteHistoryScopeDTO",
@@ -84,6 +86,16 @@ class SessionHistoryScopeDTO(BaseRequestModel):
     session_id: UUID = Field(description="Session ID to get history for.")
 
 
+class KernelHistoryScopeDTO(BaseRequestModel):
+    """Scope for kernel scheduling history queries.
+
+    The kernel is the access boundary; narrowing by session or any other column is a
+    filter concern and belongs to ``KernelHistoryFilter``.
+    """
+
+    kernel_id: KernelId = Field(description="Kernel ID to get history for.")
+
+
 class DeploymentHistoryScopeDTO(BaseRequestModel):
     """Scope for deployment scheduling history queries."""
 

src/ai/backend/manager/repositories/scheduling_history/db_source/db_source.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 import sqlalchemy as sa
@@ -22,13 +23,13 @@
     RouteHistoryRow,
     SessionSchedulingHistoryRow,
 )
+from ai.backend.manager.models.scopes import SearchScope
 from ai.backend.manager.repositories.base import (
     BatchQuerier,
     execute_batch_querier,
 )
 from ai.backend.manager.repositories.scheduling_history.types import (
     DeploymentHistorySearchScope,
-    KernelSchedulingHistorySearchScope,
     RouteHistorySearchScope,
     SessionSchedulingHistorySearchScope,
 )
@@ -125,13 +126,13 @@ async def search_kernel_history(
     async def search_kernel_scoped_history(
         self,
         querier: BatchQuerier,
-        scope: KernelSchedulingHistorySearchScope,
+        scopes: Sequence[SearchScope],
     ) -> KernelSchedulingHistoryListResult:
-        """Search kernel scheduling history within scope."""
+        """Search kernel history whose rows match any of ``scopes`` (OR), narrowed by ``querier``."""
         async with self._db.begin_readonly_session() as db_sess:
             query = sa.select(KernelSchedulingHistoryRow)
 
-            result = await execute_batch_querier(db_sess, query, querier, scopes=[scope])
+            result = await execute_batch_querier(db_sess, query, querier, scopes=scopes)
 
             items = [row.KernelSchedulingHistoryRow.to_data() for row in result.rows]
 

src/ai/backend/manager/repositories/scheduling_history/repository.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 from ai.backend.common.metrics.metric import DomainType, LayerType
@@ -21,12 +22,12 @@
 from ai.backend.manager.data.session.types import (
     SessionSchedulingHistoryListResult,
 )
+from ai.backend.manager.models.scopes import SearchScope
 from ai.backend.manager.repositories.base import BatchQuerier
 
 from .db_source import SchedulingHistoryDBSource
 from .types import (
     DeploymentHistorySearchScope,
-    KernelSchedulingHistorySearchScope,
     RouteHistorySearchScope,
     SessionSchedulingHistorySearchScope,
 )
@@ -98,10 +99,10 @@ async def search_kernel_history(
     async def search_kernel_scoped_history(
         self,
         querier: BatchQuerier,
-        scope: KernelSchedulingHistorySearchScope,
+        scopes: Sequence[SearchScope],
     ) -> KernelSchedulingHistoryListResult:
-        """Search kernel scheduling history within scope."""
-        return await self._db_source.search_kernel_scoped_history(querier, scope)
+        """Search kernel history whose rows match any of ``scopes`` (OR)."""
+        return await self._db_source.search_kernel_scoped_history(querier, scopes)
 
     # ========== Deployment History (Admin) ==========