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/data/permission/types.py

@@ -352,6 +352,7 @@ class ScopeType(enum.StrEnum):
 
     # === Entity-level scopes ===
     SESSION = "session"
+    KERNEL = "kernel"
     DEPLOYMENT = "deployment"
     MODEL_DEPLOYMENT = "model_deployment"
     VFOLDER = "vfolder"
@@ -424,6 +425,7 @@ class RBACElementType(enum.StrEnum):
     PROJECT_RESOURCE_POLICY = "project_resource_policy"
     ROLE = "role"
     AUDIT_LOG = "audit_log"
+    KERNEL_HISTORY = "kernel:history"
     EVENT_LOG = "event_log"
 
     # === Admin page access control ===

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

@@ -109,6 +109,7 @@ class RBACElementTypeDTO(StrEnum):
     PROJECT_RESOURCE_POLICY = "project_resource_policy"
     ROLE = "role"
     AUDIT_LOG = "audit_log"
+    KERNEL_HISTORY = "kernel:history"
     EVENT_LOG = "event_log"
 
     # Admin page access control

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

@@ -4,10 +4,13 @@
 
 from ai.backend.common.dto.manager.v2.scheduling_history.request import (
     AdminSearchDeploymentHistoriesInput,
+    AdminSearchKernelHistoriesInput,
     AdminSearchRouteHistoriesInput,
     AdminSearchSessionHistoriesInput,
     DeploymentHistoryFilter,
     DeploymentHistoryOrder,
+    KernelHistoryFilter,
+    KernelHistoryOrder,
     RouteHistoryFilter,
     RouteHistoryOrder,
     SearchDeploymentHistoryInput,
@@ -18,9 +21,11 @@
 )
 from ai.backend.common.dto.manager.v2.scheduling_history.response import (
     AdminSearchDeploymentHistoriesPayload,
+    AdminSearchKernelHistoriesPayload,
     AdminSearchRouteHistoriesPayload,
     AdminSearchSessionHistoriesPayload,
     DeploymentHistoryNode,
+    KernelHistoryNode,
     ListDeploymentHistoryPayload,
     ListRouteHistoryPayload,
     ListSessionHistoryPayload,
@@ -30,6 +35,7 @@
 from ai.backend.common.dto.manager.v2.scheduling_history.types import (
     DeploymentHistoryOrderField,
     DeploymentHistoryScopeDTO,
+    KernelHistoryOrderField,
     OrderDirection,
     RouteHistoryOrderField,
     RouteHistoryScopeDTO,
@@ -43,6 +49,7 @@
     # Types
     "DeploymentHistoryOrderField",
     "DeploymentHistoryScopeDTO",
+    "KernelHistoryOrderField",
     "OrderDirection",
     "RouteHistoryOrderField",
     "RouteHistoryScopeDTO",
@@ -52,10 +59,13 @@
     "SubStepResultInfo",
     # Input models (request)
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
     "SearchDeploymentHistoryInput",
@@ -65,9 +75,11 @@
     "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,7 @@
 
 from .types import (
     DeploymentHistoryOrderField,
+    KernelHistoryOrderField,
     OrderDirection,
     RouteHistoryOrderField,
     SchedulingResultType,
@@ -19,10 +20,13 @@
 
 __all__ = (
     "AdminSearchDeploymentHistoriesInput",
+    "AdminSearchKernelHistoriesInput",
     "AdminSearchRouteHistoriesInput",
     "AdminSearchSessionHistoriesInput",
     "DeploymentHistoryFilter",
     "DeploymentHistoryOrder",
+    "KernelHistoryFilter",
+    "KernelHistoryOrder",
     "RouteHistoryFilter",
     "RouteHistoryOrder",
     "SchedulingResultFilter",
@@ -86,6 +90,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 +217,19 @@ 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 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/manager/api/gql/rbac/types/permission.py

@@ -239,6 +239,7 @@ async def scope(
                 | RBACElementType.KEYPAIR_RESOURCE_POLICY
                 | RBACElementType.PROJECT_RESOURCE_POLICY
                 | RBACElementType.AUDIT_LOG
+                | RBACElementType.KERNEL_HISTORY
                 | RBACElementType.EVENT_LOG
                 | RBACElementType.NOTIFICATION_RULE
                 | RBACElementType.AGENT

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

@@ -127,7 +127,7 @@ async def search_kernel_scoped_history(
         querier: BatchQuerier,
         scope: KernelSchedulingHistorySearchScope,
     ) -> 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)
 

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

@@ -100,7 +100,7 @@ async def search_kernel_scoped_history(
         querier: BatchQuerier,
         scope: KernelSchedulingHistorySearchScope,
     ) -> KernelSchedulingHistoryListResult:
-        """Search kernel scheduling history within scope."""
+        """Search kernel history whose rows match any of ``scopes`` (OR)."""
         return await self._db_source.search_kernel_scoped_history(querier, scope)
 
     # ========== Deployment History (Admin) ==========

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

@@ -6,11 +6,9 @@
 from typing import Any, override
 from uuid import UUID
 
-import sqlalchemy as sa
-
 from ai.backend.common.data.filter_specs import UUIDEqualMatchSpec
 from ai.backend.common.identifier.replica import ReplicaID
-from ai.backend.common.types import KernelId, SessionId
+from ai.backend.common.types import KernelId
 from ai.backend.manager.errors.deployment import EndpointNotFound
 from ai.backend.manager.errors.kernel import (
     KernelNotFound,
@@ -78,60 +76,30 @@ def existence_checks(self) -> list[ExistenceCheck[Any]]:
 class KernelSchedulingHistorySearchScope(SearchScope):
     """Scope for kernel scheduling history search.
 
-    Either axis may be given; when both are, they intersect. The request DTO
-    rejects an empty scope before one is built.
+    Used for entity-scoped queries where kernel_id is the scope parameter.
     """
 
-    session_id: SessionId | None = None
-    """Restrict to the kernels of this session."""
-
-    kernel_id: KernelId | None = None
-    """Restrict to this kernel."""
+    kernel_id: KernelId
+    """Required. The kernel to search history for."""
 
     @override
     def to_condition(self) -> QueryCondition:
         """Convert scope to a query condition for KernelSchedulingHistoryRow."""
-        conditions: list[QueryCondition] = []
-        if self.session_id is not None:
-            conditions.append(
-                KernelSchedulingHistoryConditions.by_session_id_filter(
-                    UUIDEqualMatchSpec(value=self.session_id, negated=False)
-                )
-            )
-        if self.kernel_id is not None:
-            conditions.append(
-                KernelSchedulingHistoryConditions.by_kernel_id_filter(
-                    UUIDEqualMatchSpec(value=self.kernel_id, negated=False)
-                )
-            )
-
-        def inner() -> sa.sql.expression.ColumnElement[bool]:
-            return sa.and_(*(cond() for cond in conditions))
-
-        return inner
+        return KernelSchedulingHistoryConditions.by_kernel_id_filter(
+            UUIDEqualMatchSpec(value=self.kernel_id, negated=False)
+        )
 
     @property
     @override
     def existence_checks(self) -> list[ExistenceCheck[Any]]:
-        """Check that each scoped entity exists."""
-        checks: list[ExistenceCheck[Any]] = []
-        if self.session_id is not None:
-            checks.append(
-                ExistenceCheck(
-                    column=SessionRow.id,
-                    value=self.session_id,
-                    error=SessionNotFound(str(self.session_id)),
-                )
-            )
-        if self.kernel_id is not None:
-            checks.append(
-                ExistenceCheck(
-                    column=KernelRow.id,
-                    value=self.kernel_id,
-                    error=KernelNotFound(str(self.kernel_id)),
-                )
-            )
-        return checks
+        """Check that the kernel exists."""
+        return [
+            ExistenceCheck(
+                column=KernelRow.id,
+                value=self.kernel_id,
+                error=KernelNotFound(str(self.kernel_id)),
+            ),
+        ]
 
 
 # Deployment History Scope