feat(BA-6948): store app_config_fragments.scope_id as a nullable UUID

scope_id was never really a string: a domain fragment stores a domain id and a
user fragment a user id, both UUIDs, while a public fragment has no owner and
stored '' only because the column was NOT NULL. Search scopes therefore had to
compare against str(domain_id), and a malformed scope_id could be persisted into
a row no scope query would ever reach.

Store UUID NULL instead, with NULL meaning public.

Uniqueness needs restating: Postgres counts NULLs as distinct, so the existing
constraint on (config_name, scope_type, scope_id) stops rejecting a second
public fragment once public rows hold NULL. A partial unique index over the NULL
rows restores what the '' sentinel used to guarantee. UNIQUE NULLS NOT DISTINCT
would say this in one constraint but needs Postgres 15+, and the test fixture
runs 13.

The RBAC boundary still identifies scopes by string, so to_rbac_scope_id now
takes UUID | None and renders it, empty for public.

The migration forces public rows to NULL whatever they stored, and fails loudly
on a domain/user scope_id that is not a UUID rather than nulling it, since that
binding decides who can see the fragment. Upgrade and downgrade were both run
against a local DB with a row per scope type.

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

Author: jopemachine

changes/12984.feature.md

@@ -0,0 +1 @@
+Store `app_config_fragments.scope_id` as a nullable UUID, with `NULL` for the ownerless public scope, and accept and return it as a UUID on the REST v2 API.

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import enum
+import uuid
 
 from ai.backend.common.data.permission.types import RBACElementType, ScopeType
 
@@ -49,13 +50,14 @@ def to_rbac_element_type(self) -> RBACElementType | None:
             case AppConfigScopeType.USER:
                 return RBACElementType.USER
 
-    def to_rbac_scope_id(self, scope_id: str) -> str:
+    def to_rbac_scope_id(self, scope_id: uuid.UUID | None) -> str:
         """The RBAC scope id for a write at this fragment scope.
 
         ``public`` is system-wide (no per-entity scope id); ``domain`` / ``user`` carry
-        their own ``scope_id``.
+        their own ``scope_id``. RBAC identifies scopes by string, so the owner id is
+        rendered as text here even though it is stored as a UUID.
         """
-        return "" if self is AppConfigScopeType.PUBLIC else scope_id
+        return "" if self is AppConfigScopeType.PUBLIC else str(scope_id)
 
     def default_rank(self) -> int:
         """Default merge rank for an allow-list entry at this scope type (BEP-1052).

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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import uuid
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any
@@ -15,7 +16,7 @@ class AppConfigFragmentData:
     id: AppConfigFragmentID
     config_name: str
     scope_type: AppConfigScopeType
-    scope_id: str
+    scope_id: uuid.UUID | None
     config: dict[str, Any]
     created_at: datetime
     updated_at: datetime

src/ai/backend/manager/models/alembic/versions/e5b71c94d2a8_app_config_fragment_scope_id_to_uuid.py

@@ -0,0 +1,76 @@
+"""convert app_config_fragments.scope_id to a nullable UUID
+
+``scope_id`` held a ``VARCHAR(255)`` that was never really a string: a domain
+fragment stores a domain id and a user fragment a user id, both UUIDs, while a
+public fragment has no owner at all and stored ``''`` only because the column
+was ``NOT NULL``. Store the real type instead — ``UUID NULL``, with ``NULL``
+meaning "public, no owner".
+
+The uniqueness of ``(config_name, scope_type, scope_id)`` needs help: Postgres
+treats ``NULL``s as distinct in a unique constraint, so the existing constraint
+stops rejecting a second public fragment for the same config name once public
+rows hold ``NULL``. A partial unique index over the ``NULL`` rows restores the
+guarantee the ``''`` sentinel used to provide. (``UNIQUE NULLS NOT DISTINCT``
+would say the same thing in one constraint, but it needs Postgres 15+ and the
+test fixture runs 13.)
+
+Public rows are forced to ``NULL`` regardless of what they stored, since public
+has no owner by definition. Domain and user rows are cast, and a value that is
+not a UUID fails the migration on purpose — nulling it would silently drop the
+scope binding that decides who can see the fragment.
+
+Revision ID: e5b71c94d2a8
+Revises: 577c7a215934
+Create Date: 2026-07-21
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "e5b71c94d2a8"
+down_revision = "577c7a215934"
+# Part of: NEXT_RELEASE_VERSION
+branch_labels = None
+depends_on = None
+
+_PUBLIC_INDEX = "uq_app_config_fragments_public_config_name"
+_TABLE = "app_config_fragments"
+
+
+def upgrade() -> None:
+    op.execute(
+        sa.text("""
+            ALTER TABLE app_config_fragments
+            ALTER COLUMN scope_id DROP NOT NULL,
+            ALTER COLUMN scope_id TYPE UUID
+            USING (
+                CASE
+                    WHEN scope_type = 'public' THEN NULL
+                    ELSE NULLIF(scope_id, '')::uuid
+                END
+            )
+        """)
+    )
+    op.create_index(
+        _PUBLIC_INDEX,
+        _TABLE,
+        ["config_name", "scope_type"],
+        unique=True,
+        postgresql_where=sa.text("scope_id IS NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(_PUBLIC_INDEX, table_name=_TABLE)
+    # Public rows go back to the empty sentinel the NOT NULL column used to require, which
+    # the plain constraint can compare like any other value.
+    op.execute(
+        sa.text("""
+            ALTER TABLE app_config_fragments
+            ALTER COLUMN scope_id TYPE VARCHAR(255)
+            USING (COALESCE(scope_id::text, ''))
+        """)
+    )
+    op.alter_column(_TABLE, "scope_id", nullable=False)

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

@@ -10,6 +10,8 @@
 
 from ai.backend.common.data.app_config.types import AppConfigScopeType
 from ai.backend.common.data.filter_specs import StringMatchSpec
+from ai.backend.common.identifier.domain import DomainID
+from ai.backend.common.identifier.user import UserID
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
 from ai.backend.manager.models.clauses import QueryCondition
 from ai.backend.manager.models.condition_utils import make_string_in_factory
@@ -118,7 +120,7 @@ def inner() -> sa.sql.expression.ColumnElement[bool]:
     # --- scope_id filter ---
 
     @staticmethod
-    def by_scope_id_equals(scope_id: str) -> QueryCondition:
+    def by_scope_id_equals(scope_id: uuid.UUID) -> QueryCondition:
         def inner() -> sa.sql.expression.ColumnElement[bool]:
             return AppConfigFragmentRow.scope_id == scope_id
 
@@ -136,19 +138,19 @@ def inner() -> sa.sql.expression.ColumnElement[bool]:
         return inner
 
     @staticmethod
-    def by_domain_visibility(domain: str) -> QueryCondition:
-        """The ``domain`` scope for ``domain``."""
+    def by_domain_visibility(domain_id: DomainID) -> QueryCondition:
+        """The ``domain`` scope for ``domain_id``."""
 
         def inner() -> sa.sql.expression.ColumnElement[bool]:
             return sa.and_(
                 AppConfigFragmentRow.scope_type == AppConfigScopeType.DOMAIN,
-                AppConfigFragmentRow.scope_id == domain,
+                AppConfigFragmentRow.scope_id == domain_id,
             )
 
         return inner
 
     @staticmethod
-    def by_user_visibility(user_id: str) -> QueryCondition:
+    def by_user_visibility(user_id: UserID) -> QueryCondition:
         """The ``user`` scope for ``user_id``."""
 
         def inner() -> sa.sql.expression.ColumnElement[bool]:

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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import uuid
 from typing import Any
 
 import sqlalchemy as sa
@@ -32,6 +33,17 @@ class AppConfigFragmentRow(LifecycleTimestampsMixin, Base):  # type: ignore[misc
             "scope_id",
             name="uq_app_config_fragments_config_name_scope_type_scope_id",
         ),
+        # The constraint above only covers domain and user fragments: Postgres counts NULLs
+        # as distinct, so it would let a config take any number of public fragments. This
+        # partial index restores that guarantee for the NULL (public) rows. It replaces the
+        # NULLS NOT DISTINCT the constraint would otherwise want, which needs Postgres 15+.
+        sa.Index(
+            "uq_app_config_fragments_public_config_name",
+            "config_name",
+            "scope_type",
+            unique=True,
+            postgresql_where=sa.text("scope_id IS NULL"),
+        ),
         sa.ForeignKeyConstraint(
             ["config_name", "scope_type"],
             ["app_config_allow_list.config_name", "app_config_allow_list.scope_type"],
@@ -56,10 +68,12 @@ class AppConfigFragmentRow(LifecycleTimestampsMixin, Base):  # type: ignore[misc
         StrEnumType(AppConfigScopeType),
         nullable=False,
     )
-    scope_id: Mapped[str] = mapped_column(
+    # NULL is the public scope: it has no owner. Domain and user fragments carry the id of
+    # the domain or user that owns them.
+    scope_id: Mapped[uuid.UUID | None] = mapped_column(
         "scope_id",
-        sa.String(length=255),
-        nullable=False,
+        GUID,
+        nullable=True,
     )
     config: Mapped[dict[str, Any]] = mapped_column(
         "config",

src/ai/backend/manager/repositories/app_config_fragment/creators.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import uuid
 from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import Any, override
@@ -23,7 +24,7 @@ class AppConfigFragmentCreatorSpec(CreatorSpec[AppConfigFragmentRow]):
 
     config_name: str
     scope_type: AppConfigScopeType
-    scope_id: str
+    scope_id: uuid.UUID | None
     config: dict[str, Any]
 
     @property

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

@@ -85,7 +85,9 @@ async def create(self, spec: AppConfigFragmentCreatorSpec) -> AppConfigFragmentD
             spec=spec,
             element_type=RBACElementType.APP_CONFIG_FRAGMENT,
             scope_ref=(
-                RBACElementRef(element_type, spec.scope_id) if element_type is not None else None
+                RBACElementRef(element_type, str(spec.scope_id))
+                if element_type is not None
+                else None
             ),
         )
         async with self._rbac_ops_provider.write_ops() as w:
@@ -223,8 +225,8 @@ async def list_visible_fragments_bulk(
         scope_visibility = [AppConfigFragmentConditions.by_public_visibility()]
         if scope is not None:
             scope_visibility += [
-                AppConfigFragmentConditions.by_domain_visibility(str(scope.domain_id)),
-                AppConfigFragmentConditions.by_user_visibility(str(scope.user_id)),
+                AppConfigFragmentConditions.by_domain_visibility(scope.domain_id),
+                AppConfigFragmentConditions.by_user_visibility(scope.user_id),
             ]
         querier = BatchQuerier(
             pagination=NoPagination(),

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

@@ -63,7 +63,7 @@ def to_condition(self) -> QueryCondition:
         def inner() -> sa.sql.expression.ColumnElement[bool]:
             return sa.and_(
                 AppConfigFragmentRow.scope_type == AppConfigScopeType.DOMAIN,
-                AppConfigFragmentRow.scope_id == str(domain_id),
+                AppConfigFragmentRow.scope_id == domain_id,
             )
 
         return inner
@@ -87,7 +87,7 @@ def to_condition(self) -> QueryCondition:
         def inner() -> sa.sql.expression.ColumnElement[bool]:
             return sa.and_(
                 AppConfigFragmentRow.scope_type == AppConfigScopeType.USER,
-                AppConfigFragmentRow.scope_id == str(user_id),
+                AppConfigFragmentRow.scope_id == user_id,
             )
 
         return inner

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

@@ -47,7 +47,8 @@ def target_element(self) -> RBACElementRef:
         element = self.creator_spec.scope_type.to_rbac_element_type()
         if element is None:
             return RBACElementRef(RBACElementType.APP_CONFIG_FRAGMENT, "")
-        return RBACElementRef(element, self.creator_spec.scope_id)
+        # A non-null element type means domain or user scope, which always carries an owner.
+        return RBACElementRef(element, str(self.creator_spec.scope_id))
 
 
 @dataclass