feat: expose deployment lifecycle sub_step on v2 GQL/REST surfaces

The v1 ``DeploymentDTO.sub_step`` had no v2 counterpart, so the GQL
``ModelDeployment`` node and the v2 REST ``DeploymentNode`` were missing
the rolling-update progress signal. Promote ``DeploymentLifecycleSubStep``
to ``common.data.model_deployment.types`` so the v2 DTO layer can reach it
(``common/`` cannot import from ``manager/``), repoint every existing
importer at the common location, then surface the enum on:

- ``DeploymentNode.sub_step`` (v2 REST DTO)
- ``ModelDeployment.subStep`` (GQL, backed by a new
  ``DeploymentLifecycleSubStep`` GQL enum)

The v2 adapter pipes ``ModelDeploymentData.sub_step`` through to the
new DTO field, and the v2 schema dump picks up the enum + field.

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

Author: jopemachine

docs/manager/graphql-reference/supergraph.graphql

@@ -5220,6 +5220,17 @@ enum DeploymentHistoryOrderField
   UPDATED_AT @join__enumValue(graph: STRAWBERRY)
 }
 
+"""
+Added in UNRELEASED. Sub-step within a deployment's current lifecycle phase. ``None`` when the deployment is not in a sub-step-bearing phase.
+"""
+enum DeploymentLifecycleSubStep
+  @join__type(graph: STRAWBERRY)
+{
+  DEPLOYING_PROVISIONING @join__enumValue(graph: STRAWBERRY)
+  DEPLOYING_ROLLING_BACK @join__enumValue(graph: STRAWBERRY)
+  DEPLOYING_COMPLETED @join__enumValue(graph: STRAWBERRY)
+}
+
 """Added in UNRELEASED. Deployment options payload response."""
 type DeploymentOptionsInfoGQL
   @join__type(graph: STRAWBERRY)
@@ -9306,6 +9317,11 @@ type ModelDeployment implements Node
   """
   scalingState: ScalingState!
 
+  """
+  Added in UNRELEASED. Sub-step within the current lifecycle phase. ``None`` when the deployment is not in a sub-step-bearing phase.
+  """
+  subStep: DeploymentLifecycleSubStep
+
   """
   Added in 26.4.3. The current active revision of this deployment, resolved via DataLoader.
   """

docs/manager/graphql-reference/v2-schema.graphql

@@ -3486,6 +3486,15 @@ enum DeploymentHistoryOrderField {
   UPDATED_AT
 }
 
+"""
+Added in UNRELEASED. Sub-step within a deployment's current lifecycle phase. ``None`` when the deployment is not in a sub-step-bearing phase.
+"""
+enum DeploymentLifecycleSubStep {
+  DEPLOYING_PROVISIONING
+  DEPLOYING_ROLLING_BACK
+  DEPLOYING_COMPLETED
+}
+
 """Added in UNRELEASED. Deployment options payload response."""
 type DeploymentOptionsInfoGQL {
   """Handler-keyed scheduler policy (timeout + retry)."""
@@ -6109,6 +6118,11 @@ type ModelDeployment implements Node {
   """
   scalingState: ScalingState!
 
+  """
+  Added in UNRELEASED. Sub-step within the current lifecycle phase. ``None`` when the deployment is not in a sub-step-bearing phase.
+  """
+  subStep: DeploymentLifecycleSubStep
+
   """
   Added in 26.4.3. The current active revision of this deployment, resolved via DataLoader.
   """

src/ai/backend/common/data/model_deployment/types.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+import enum
 from typing import Any, Self
 
 from ai.backend.common.data.endpoint.types import EndpointLifecycle
@@ -50,7 +53,7 @@ def _missing_(cls, value: Any) -> Self | None:
         return super()._missing_(value)
 
     @classmethod
-    def from_lifecycle(cls, lifecycle: EndpointLifecycle) -> "ModelDeploymentStatus":
+    def from_lifecycle(cls, lifecycle: EndpointLifecycle) -> ModelDeploymentStatus:
         match lifecycle:
             case EndpointLifecycle.PENDING | EndpointLifecycle.CREATED:
                 return cls.PENDING
@@ -69,6 +72,27 @@ class DeploymentStrategy(CIStrEnum):
     BLUE_GREEN = "BLUE_GREEN"
 
 
+class DeploymentLifecycleSubStep(enum.StrEnum):
+    """Sub-steps within deployment lifecycle phases.
+
+    Member names are prefixed with the lifecycle phase they belong to
+    (e.g. ``DEPLOYING_``). String values are stored in the database as-is.
+    """
+
+    # -- DEPLOYING phase --
+    DEPLOYING_PROVISIONING = "deploying_provisioning"
+    """New revision routes are being provisioned and old routes are being drained."""
+    DEPLOYING_ROLLING_BACK = "deploying_rolling_back"
+    """Clearing deploying_revision and transitioning to READY."""
+    DEPLOYING_COMPLETED = "deploying_completed"
+    """All strategy conditions satisfied; triggers revision swap."""
+
+    @classmethod
+    def deploying_handler_sub_steps(cls) -> tuple[DeploymentLifecycleSubStep, ...]:
+        """Sub-steps that have their own deploying handler (excludes COMPLETED, which is an evaluator outcome)."""
+        return (cls.DEPLOYING_PROVISIONING, cls.DEPLOYING_ROLLING_BACK)
+
+
 class RouteStatus(CIStrEnum):
     """Lifecycle status of a route in the deployment."""
 

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

@@ -15,6 +15,7 @@
 from ai.backend.common.data.endpoint.types import ScalingState
 from ai.backend.common.data.model_deployment.types import (
     ActivenessStatus,
+    DeploymentLifecycleSubStep,
     LivenessStatus,
     ReadinessStatus,
     RouteHealthStatus,
@@ -175,6 +176,13 @@ class DeploymentNode(BaseResponseModel):
         default=None,
         description="ID of the revision currently being deployed (in progress, not yet active)",
     )
+    sub_step: DeploymentLifecycleSubStep | None = Field(
+        default=None,
+        description=(
+            "Sub-step within the current lifecycle phase. ``None`` when the"
+            " deployment is not in a sub-step-bearing phase."
+        ),
+    )
 
 
 class RouteNode(BaseResponseModel):

src/ai/backend/manager/api/adapters/deployment/adapter.py

@@ -2255,6 +2255,7 @@ def _deployment_data_to_dto(data: ModelDeploymentData) -> DeploymentNode:
             scaling_state=data.scaling_state,
             current_revision_id=data.current_revision_id,
             deploying_revision_id=data.deploying_revision_id,
+            sub_step=data.sub_step,
         )
 
     @staticmethod

src/ai/backend/manager/api/gql/deployment/types/deployment.py

@@ -13,6 +13,7 @@
 
 from ai.backend.common.data.endpoint.types import ScalingState
 from ai.backend.common.data.model_deployment.types import (
+    DeploymentLifecycleSubStep,
     ModelDeploymentStatus,
 )
 from ai.backend.common.dto.manager.v2.deployment.request import (
@@ -195,6 +196,19 @@
 )
 
 
+DeploymentLifecycleSubStepGQL: type[DeploymentLifecycleSubStep] = gql_enum(
+    BackendAIGQLMeta(
+        added_version=NEXT_RELEASE_VERSION,
+        description=(
+            "Sub-step within a deployment's current lifecycle phase."
+            " ``None`` when the deployment is not in a sub-step-bearing phase."
+        ),
+    ),
+    DeploymentLifecycleSubStep,
+    name="DeploymentLifecycleSubStep",
+)
+
+
 @gql_pydantic_type(
     BackendAIGQLMeta(
         added_version="25.19.0",
@@ -351,6 +365,16 @@ class ModelDeployment(PydanticNodeMixin[DeploymentNodeDTO]):
             ),
         )
     )
+    sub_step: DeploymentLifecycleSubStepGQL | None = gql_added_field(
+        BackendAIGQLMeta(
+            added_version=NEXT_RELEASE_VERSION,
+            description=(
+                "Sub-step within the current lifecycle phase."
+                " ``None`` when the deployment is not in a sub-step-bearing phase."
+            ),
+        ),
+        default=None,
+    )
 
     @gql_added_field(
         BackendAIGQLMeta(

src/ai/backend/manager/data/deployment/types.py

@@ -16,6 +16,7 @@
 from ai.backend.common.data.endpoint.types import EndpointLifecycle, ScalingState
 from ai.backend.common.data.model_deployment.types import (
     ActivenessStatus,
+    DeploymentLifecycleSubStep,
     DeploymentStrategy,
     LivenessStatus,
     ModelDeploymentStatus,
@@ -164,30 +165,6 @@ class RouteSubStatus(enum.StrEnum):
     WARMING_UP = "warming_up"
 
 
-# ========== Status Transition Types (BEP-1030) ==========
-
-
-class DeploymentLifecycleSubStep(enum.StrEnum):
-    """Sub-steps within deployment lifecycle phases.
-
-    Member names are prefixed with the lifecycle phase they belong to
-    (e.g. ``DEPLOYING_``).  String values are stored in the database as-is.
-    """
-
-    # -- DEPLOYING phase --
-    DEPLOYING_PROVISIONING = "deploying_provisioning"
-    """New revision routes are being provisioned and old routes are being drained."""
-    DEPLOYING_ROLLING_BACK = "deploying_rolling_back"
-    """Clearing deploying_revision and transitioning to READY."""
-    DEPLOYING_COMPLETED = "deploying_completed"
-    """All strategy conditions satisfied; triggers revision swap."""
-
-    @classmethod
-    def deploying_handler_sub_steps(cls) -> tuple[DeploymentLifecycleSubStep, ...]:
-        """Sub-steps that have their own deploying handler (excludes COMPLETED, which is an evaluator outcome)."""
-        return (cls.DEPLOYING_PROVISIONING, cls.DEPLOYING_ROLLING_BACK)
-
-
 @dataclass(frozen=True)
 class DeploymentLifecycleStatus:
     """Target state for a deployment status transition.

src/ai/backend/manager/event_dispatcher/handlers/schedule.py

@@ -1,5 +1,6 @@
 import logging
 
+from ai.backend.common.data.model_deployment.types import DeploymentLifecycleSubStep
 from ai.backend.common.events.event_types.agent.anycast import AgentStartedEvent
 from ai.backend.common.events.event_types.schedule.anycast import (
     DoDeploymentLifecycleEvent,
@@ -17,7 +18,6 @@
 from ai.backend.common.events.hub.hub import EventHub
 from ai.backend.common.types import AgentId
 from ai.backend.logging.utils import BraceStyleAdapter
-from ai.backend.manager.data.deployment.types import DeploymentLifecycleSubStep
 from ai.backend.manager.sokovan.deployment.coordinator import DeploymentCoordinator
 from ai.backend.manager.sokovan.deployment.route.coordinator import RouteCoordinator
 from ai.backend.manager.sokovan.deployment.route.types import RouteLifecycleType

src/ai/backend/manager/models/endpoint/conditions.py

@@ -14,8 +14,8 @@
     UUIDEqualMatchSpec,
     UUIDInMatchSpec,
 )
+from ai.backend.common.data.model_deployment.types import DeploymentLifecycleSubStep
 from ai.backend.common.identifier.deployment import DeploymentID
-from ai.backend.manager.data.deployment.types import DeploymentLifecycleSubStep
 from ai.backend.manager.models.condition_utils import make_string_in_factory
 from ai.backend.manager.models.endpoint import (
     EndpointAutoScalingRuleRow,

src/ai/backend/manager/models/endpoint/row.py

@@ -35,6 +35,7 @@
 
 from ai.backend.common.config import model_definition_iv
 from ai.backend.common.data.model_deployment.types import (
+    DeploymentLifecycleSubStep,
     DeploymentStrategy,
     ModelDeploymentStatus,
 )
@@ -69,7 +70,6 @@
 )
 from ai.backend.manager.data.deployment.types import (
     DeploymentInfo,
-    DeploymentLifecycleSubStep,
     DeploymentMetadata,
     DeploymentNetworkData,
     DeploymentOptions,