fix(BA-5827): apply review feedback on Fragment DTOs and actions

- Drop the FK detail from `AppConfigFragmentKeyInput.name` description
  — the FK is documented at the SQL / model layer; the DTO description
  should not leak that detail.
- Add `scope_type` filter to `AppConfigFragmentFilter` (was missing
  even though scope_type is part of the natural key) plus the matching
  `AppConfigFragmentConditions.by_scope_type_equals` factory.
- Add `UPDATED_AT` to `AppConfigFragmentOrderField` and the
  `AppConfigFragmentOrders.updated_at` factory; wire it into the
  adapter's order mapping.
- `AppConfigFragmentAction.entity_id()` now returns the row id (or
  None when the row id is not yet known at action time), not the
  natural key. Applies to get / create / update / purge action +
  result pairs.

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

Author: jopemachine

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

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 from typing import Any
+from uuid import UUID
 
 from pydantic import Field
 
@@ -39,7 +40,7 @@ class AppConfigFragmentKeyInput(BaseRequestModel):
     name: str = Field(
         min_length=1,
         max_length=128,
-        description="Policy name (FK to `app_config_policies.config_name`).",
+        description="Policy name.",
     )
 
 
@@ -73,7 +74,12 @@ class PurgeAppConfigFragmentInput(BaseRequestModel):
 class AppConfigFragmentFilter(BaseRequestModel):
     """Filter for app-config fragment search."""
 
+    id_in: list[UUID] | None = Field(
+        default=None,
+        description="Match rows whose `id` is in this list (used by Relay node loaders).",
+    )
     name: StringFilter | None = Field(default=None, description="Filter by policy name.")
+    scope_type: AppConfigScopeType | None = Field(default=None, description="Filter by scope_type.")
     scope_id: StringFilter | None = Field(default=None, description="Filter by scope_id.")
 
 

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

@@ -31,3 +31,4 @@ class AppConfigFragmentOrderField(StrEnum):
     SCOPE_ID = "scope_id"
     NAME = "name"
     CREATED_AT = "created_at"
+    UPDATED_AT = "updated_at"

src/ai/backend/manager/api/adapters/app_config_fragment.py

@@ -186,6 +186,8 @@ def _build_querier_from_input(self, input: SearchAppConfigFragmentsInput) -> Bat
 
     def _convert_filter(self, filter: AppConfigFragmentFilter) -> list[QueryCondition]:
         conditions: list[QueryCondition] = []
+        if filter.id_in is not None:
+            conditions.append(AppConfigFragmentConditions.by_ids(filter.id_in))
         if filter.name is not None:
             condition = self.convert_string_filter(
                 filter.name,
@@ -197,6 +199,10 @@ def _convert_filter(self, filter: AppConfigFragmentFilter) -> list[QueryConditio
             )
             if condition is not None:
                 conditions.append(condition)
+        if filter.scope_type is not None:
+            conditions.append(
+                AppConfigFragmentConditions.by_scope_type_equals(filter.scope_type.value)
+            )
         if filter.scope_id is not None:
             condition = self.convert_string_filter(
                 filter.scope_id,
@@ -224,6 +230,8 @@ def _convert_orders(orders: list[AppConfigFragmentOrder]) -> list[QueryOrder]:
                     result.append(AppConfigFragmentOrders.name(ascending))
                 case "created_at":
                     result.append(AppConfigFragmentOrders.created_at(ascending))
+                case "updated_at":
+                    result.append(AppConfigFragmentOrders.updated_at(ascending))
         return result
 
     @staticmethod

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

@@ -131,6 +131,13 @@ def inner() -> sa.ColumnElement[bool]:
 
     by_scope_id_in = staticmethod(make_string_in_factory(AppConfigFragmentRow.scope_id))
 
+    @staticmethod
+    def by_scope_type_equals(scope_type: str) -> QueryCondition:
+        def inner() -> sa.ColumnElement[bool]:
+            return AppConfigFragmentRow.scope_type == scope_type
+
+        return inner
+
     @staticmethod
     def by_cursor_forward(cursor_id: str) -> QueryCondition:
         cursor_uuid = uuid.UUID(cursor_id)

src/ai/backend/manager/models/app_config_fragment/orders.py

@@ -32,3 +32,9 @@ def created_at(ascending: bool = True) -> QueryOrder:
         if ascending:
             return AppConfigFragmentRow.created_at.asc()
         return AppConfigFragmentRow.created_at.desc()
+
+    @staticmethod
+    def updated_at(ascending: bool = True) -> QueryOrder:
+        if ascending:
+            return AppConfigFragmentRow.updated_at.asc()
+        return AppConfigFragmentRow.updated_at.desc()

src/ai/backend/manager/services/app_config_fragment/actions/create.py

@@ -18,7 +18,8 @@ class CreateAppConfigFragmentAction(AppConfigFragmentAction):
 
     @override
     def entity_id(self) -> str | None:
-        return f"{self.key.scope_type}:{self.key.scope_id}:{self.key.name}"
+        # Row id is not known at action time (insert hasn't happened yet).
+        return None
 
     @override
     @classmethod
@@ -32,6 +33,4 @@ class CreateAppConfigFragmentActionResult(BaseActionResult):
 
     @override
     def entity_id(self) -> str | None:
-        return (
-            f"{self.fragment.key.scope_type}:{self.fragment.key.scope_id}:{self.fragment.key.name}"
-        )
+        return str(self.fragment.id)

src/ai/backend/manager/services/app_config_fragment/actions/get.py

@@ -16,7 +16,8 @@ class GetAppConfigFragmentAction(AppConfigFragmentAction):
 
     @override
     def entity_id(self) -> str | None:
-        return f"{self.key.scope_type}:{self.key.scope_id}:{self.key.name}"
+        # Row id is not known at action time (lookup is by natural key).
+        return None
 
     @override
     @classmethod
@@ -32,6 +33,4 @@ class GetAppConfigFragmentActionResult(BaseActionResult):
     def entity_id(self) -> str | None:
         if self.fragment is None:
             return None
-        return (
-            f"{self.fragment.key.scope_type}:{self.fragment.key.scope_id}:{self.fragment.key.name}"
-        )
+        return str(self.fragment.id)

src/ai/backend/manager/services/app_config_fragment/actions/purge.py

@@ -13,7 +13,8 @@ class PurgeAppConfigFragmentAction(AppConfigFragmentAction):
 
     @override
     def entity_id(self) -> str | None:
-        return f"{self.key.scope_type}:{self.key.scope_id}:{self.key.name}"
+        # Row id is not known at action time (lookup is by natural key).
+        return None
 
     @override
     @classmethod
@@ -28,4 +29,5 @@ class PurgeAppConfigFragmentActionResult(BaseActionResult):
 
     @override
     def entity_id(self) -> str | None:
-        return f"{self.key.scope_type}:{self.key.scope_id}:{self.key.name}"
+        # Row is gone post-purge; no surviving id to surface.
+        return None

src/ai/backend/manager/services/app_config_fragment/actions/update.py

@@ -18,7 +18,8 @@ class UpdateAppConfigFragmentAction(AppConfigFragmentAction):
 
     @override
     def entity_id(self) -> str | None:
-        return f"{self.key.scope_type}:{self.key.scope_id}:{self.key.name}"
+        # Row id is not known at action time (lookup is by natural key).
+        return None
 
     @override
     @classmethod
@@ -34,6 +35,4 @@ class UpdateAppConfigFragmentActionResult(BaseActionResult):
     def entity_id(self) -> str | None:
         if self.fragment is None:
             return None
-        return (
-            f"{self.fragment.key.scope_type}:{self.fragment.key.scope_id}:{self.fragment.key.name}"
-        )
+        return str(self.fragment.id)