feat(BA-6921): accept and return scope_id as a UUID on the v2 API

Follows the column becoming UUID NULL in BA-6948: the request and response DTOs
take UUID | None, so a non-UUID scope_id is rejected at the boundary instead of
reaching a row no scope query can find. The adapter no longer maps public to an
empty-string sentinel in either direction — None is what the column stores.

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

Author: jopemachine

docs/manager/rest-reference/openapi.json

@@ -574,6 +574,7 @@
           "scope_id": {
             "anyOf": [
               {
+                "format": "uuid",
                 "type": "string"
               },
               {

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

@@ -30,7 +30,7 @@ class CreateAppConfigFragmentInput(BaseRequestModel):
     scope_type: AppConfigScopeType = Field(
         description="Scope the fragment is written at (public | domain | user)."
     )
-    scope_id: str | None = Field(
+    scope_id: UUID | None = Field(
         default=None,
         description="Scope identifier: the domain id (domain scope) or the user id (user scope). "
         "Null for public scope, which has no owner.",
@@ -42,7 +42,7 @@ def _check_scope_id(self) -> Self:
         if self.scope_type is AppConfigScopeType.PUBLIC:
             if self.scope_id is not None:
                 raise ValueError("scope_id must be null for public scope.")
-        elif not self.scope_id:
+        elif self.scope_id is None:
             raise ValueError("scope_id is required for domain and user scopes.")
         return self
 

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

@@ -28,7 +28,7 @@ class AppConfigFragmentNode(BaseResponseModel):
     id: UUID = Field(description="App config fragment UUID.")
     config_name: str = Field(description="Config name the fragment belongs to.")
     scope_type: AppConfigScopeType = Field(description="Scope the fragment is written at.")
-    scope_id: str | None = Field(
+    scope_id: UUID | None = Field(
         description="Scope identifier: the domain id or user id; null for public scope."
     )
     config: dict[str, Any] = Field(description="The fragment's JSON config document.")

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

@@ -56,23 +56,19 @@
 )
 from ai.backend.manager.types import OptionalState
 
-# Public fragments have no scope owner; the non-null scope_id column stores this empty
-# sentinel. Public is identified by scope_type, never by this value.
-_PUBLIC_SCOPE_ID = ""
-
 
 class AppConfigFragmentAdapter(BaseAdapter):
     """Adapter for raw app config fragment write operations."""
 
     # --- fragment CRUD (RBAC-gated at the processor) ---
 
     async def create(self, input: CreateAppConfigFragmentInput) -> CreateAppConfigFragmentPayload:
-        # scope_id is None only for public (enforced by the DTO validator); persist the empty
-        # sentinel since the column is non-null. Domain/user carry the id.
+        # scope_id is None exactly for public (enforced by the DTO validator), which is what
+        # the column stores for an ownerless fragment.
         spec = AppConfigFragmentCreatorSpec(
             config_name=input.config_name,
             scope_type=AppConfigScopeType(input.scope_type.value),
-            scope_id=input.scope_id or _PUBLIC_SCOPE_ID,
+            scope_id=input.scope_id,
             config=input.config,
         )
         action_result = await self._processors.app_config_fragment.create.wait_for_complete(
@@ -159,8 +155,7 @@ def _fragment_to_node(data: AppConfigFragmentData) -> AppConfigFragmentNode:
             id=data.id,
             config_name=data.config_name,
             scope_type=AppConfigScopeTypeDTO(data.scope_type.value),
-            # public has no owner — expose null rather than the stored empty sentinel.
-            scope_id=None if data.scope_type is AppConfigScopeType.PUBLIC else data.scope_id,
+            scope_id=data.scope_id,
             config=data.config,
             created_at=data.created_at,
             updated_at=data.updated_at,

tests/unit/common/dto/manager/v2/app_config_fragment/test_request.py

@@ -19,13 +19,13 @@
 )
 from ai.backend.common.exception import BackendAISchemaValidationFailed
 
-_SCOPE_ID = "11111111-1111-1111-1111-111111111111"
+_SCOPE_ID = uuid.UUID("11111111-1111-1111-1111-111111111111")
 
 
 @dataclass(frozen=True)
 class _ScopeCase:
     scope_type: AppConfigScopeType
-    scope_id: str | None
+    scope_id: uuid.UUID | None
 
 
 @pytest.fixture
@@ -63,13 +63,11 @@ def test_scope_id_matching_its_scope_type_is_accepted(
         [
             # public has no owner, so naming one is a contradiction.
             _ScopeCase(scope_type=AppConfigScopeType.PUBLIC, scope_id=_SCOPE_ID),
-            # domain and user both require an owner; absent and blank are equally unusable.
+            # domain and user both require an owner.
             _ScopeCase(scope_type=AppConfigScopeType.DOMAIN, scope_id=None),
-            _ScopeCase(scope_type=AppConfigScopeType.DOMAIN, scope_id=""),
             _ScopeCase(scope_type=AppConfigScopeType.USER, scope_id=None),
-            _ScopeCase(scope_type=AppConfigScopeType.USER, scope_id=""),
         ],
-        ids=lambda case: f"{case.scope_type.value}-{case.scope_id!r}",
+        ids=lambda case: f"{case.scope_type.value}-{case.scope_id}",
     )
     def test_scope_id_disagreeing_with_its_scope_type_is_rejected(
         self, case: _ScopeCase, config_document: dict[str, Any]
@@ -82,6 +80,25 @@ def test_scope_id_disagreeing_with_its_scope_type_is_rejected(
                 config=config_document,
             )
 
+    @pytest.mark.parametrize(
+        "scope_type",
+        [AppConfigScopeType.DOMAIN, AppConfigScopeType.USER],
+        ids=lambda scope_type: scope_type.value,
+    )
+    @pytest.mark.parametrize("scope_id", ["", "not-a-uuid"], ids=["empty", "malformed"])
+    def test_scope_id_that_is_not_a_uuid_is_rejected(
+        self, scope_type: AppConfigScopeType, scope_id: str, config_document: dict[str, Any]
+    ) -> None:
+        # Validated from a mapping because the field is typed UUID: a string only ever
+        # reaches it from a request payload, never from a type-checked call.
+        with pytest.raises((BackendAISchemaValidationFailed, ValidationError)):
+            CreateAppConfigFragmentInput.model_validate({
+                "config_name": "theme",
+                "scope_type": scope_type,
+                "scope_id": scope_id,
+                "config": config_document,
+            })
+
     def test_scope_id_defaults_to_none(self, config_document: dict[str, Any]) -> None:
         req = CreateAppConfigFragmentInput(
             config_name="theme",