refactor(BA-5827): drop premature error type, switch admin_repo to Updater/Purger, rename extra_config

- Drop `AppConfigFragmentPolicyMissing` (and the FK-violation
  integrity_error_check that mapped to it). The required-policy
  invariant is enforced upstream by the service layer; the DB-level
  FK is the defense-in-depth backstop and now surfaces as a generic
  `ForeignKeyViolationError`. The typed exception was premature for
  the DB+repository foundation slice — re-introduce later if a
  service/API layer needs it.
- Refactor the admin_repository / db_source split: db_source now
  accepts pre-built `Updater` / `Purger` objects (mirroring
  `scaling_group`, `vfolder`, etc.), with the natural-key → PK
  resolution exposed as `resolve_pk_by_key`. `admin_repository`
  builds the `Updater` / `Purger` and translates the missing-row
  case into `AppConfigFragmentNotFound`.
- Rename the JSONB column / Row attribute / Data field /
  Creator+Updater spec / admin-repository parameter from
  `extra_config` to `config` end-to-end (DB column included). The
  legacy-drop migration's downgrade keeps `extra_config` because it
  recreates the historical schema.
- Update the regression test to expect the generic
  `ForeignKeyViolationError`.

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

Author: jopemachine

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

@@ -30,7 +30,7 @@ class AppConfigFragmentData:
     scope_type: AppConfigScopeType
     scope_id: str
     name: str
-    extra_config: Mapping[str, Any] | None
+    config: Mapping[str, Any] | None
     created_at: datetime
     updated_at: datetime | None
 

src/ai/backend/manager/errors/app_config.py

@@ -56,22 +56,3 @@ def error_code(self) -> ErrorCode:
             operation=ErrorOperation.READ,
             error_detail=ErrorDetail.NOT_FOUND,
         )
-
-
-class AppConfigFragmentPolicyMissing(BackendAIError, web.HTTPConflict):
-    """Raised when a fragment references a `name` without a matching policy row.
-
-    Defense-in-depth against the required-policy invariant — normally
-    the service layer rejects earlier, but the FK violation surfaces
-    here if the service check is bypassed.
-    """
-
-    error_type = "https://api.backend.ai/probs/app-config-fragment-policy-missing"
-    error_title = "Referenced app-config policy does not exist for this fragment."
-
-    def error_code(self) -> ErrorCode:
-        return ErrorCode(
-            domain=ErrorDomain.BACKENDAI,
-            operation=ErrorOperation.CREATE,
-            error_detail=ErrorDetail.CONFLICT,
-        )

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

@@ -53,7 +53,7 @@ def upgrade() -> None:
             nullable=False,
         ),
         sa.Column(
-            "extra_config",
+            "config",
             pgsql.JSONB(),
             nullable=True,
         ),

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

@@ -52,8 +52,8 @@ class AppConfigFragmentRow(Base):  # type: ignore[misc]
         ),
         nullable=False,
     )
-    extra_config: Mapped[Mapping[str, Any] | None] = mapped_column(
-        "extra_config",
+    config: Mapped[Mapping[str, Any] | None] = mapped_column(
+        "config",
         pgsql.JSONB,
         nullable=True,
     )
@@ -76,7 +76,7 @@ def to_data(self) -> AppConfigFragmentData:
             scope_type=self.scope_type,
             scope_id=self.scope_id,
             name=self.name,
-            extra_config=dict(self.extra_config) if self.extra_config is not None else None,
+            config=dict(self.config) if self.config is not None else None,
             created_at=self.created_at,
             updated_at=self.updated_at,
         )

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

@@ -14,6 +14,7 @@
     AppConfigFragmentKey,
     AppConfigFragmentSearchResult,
 )
+from ai.backend.manager.errors.app_config import AppConfigFragmentNotFound
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
 from ai.backend.manager.models.utils import ExtendedAsyncSAEngine
 from ai.backend.manager.repositories.app_config_fragment.creators import (
@@ -26,7 +27,9 @@
     AppConfigFragmentUpdaterSpec,
 )
 from ai.backend.manager.repositories.base.creator import Creator
+from ai.backend.manager.repositories.base.purger import Purger
 from ai.backend.manager.repositories.base.querier import BatchQuerier
+from ai.backend.manager.repositories.base.updater import Updater
 
 app_config_fragment_admin_repository_resilience = Resilience(
     policies=[
@@ -48,19 +51,29 @@
 )
 
 
+def _missing(key: AppConfigFragmentKey) -> AppConfigFragmentNotFound:
+    return AppConfigFragmentNotFound(
+        extra_msg=(
+            f"scope_type={key.scope_type.value!r}, scope_id={key.scope_id!r}, name={key.name!r}"
+        ),
+    )
+
+
 class AppConfigFragmentAdminRepository:
     """Admin-only operations on AppConfigFragment.
 
     All mutations (`create` / `update` / `purge`) and cross-scope
     reads (`admin_search` raw, `admin_search_app_configs` merged)
     live here — read-side scope-bound operations are on
     `AppConfigFragmentRepository`. Authorization is enforced at the
-    service layer before reaching either repository.
-
-    The required-policy invariant is enforced by the service layer;
-    the FK on `app_config_fragments.name` is the defense-in-depth
-    backstop, translated by the creator spec into
-    :class:`AppConfigFragmentPolicyMissing`.
+    service layer before reaching either repository. The required-
+    policy invariant is enforced upstream by the service layer; the
+    DB-level FK on ``app_config_fragments.name`` is the defense-in-
+    depth backstop and surfaces as a generic integrity error.
+
+    Mutations are routed through the shared Creator / Updater / Purger
+    helpers so the same execution / resilience plumbing applies as in
+    sister repositories.
     """
 
     _db_source: AppConfigFragmentDBSource
@@ -74,14 +87,14 @@ def __init__(self, db: ExtendedAsyncSAEngine) -> None:
     async def create(
         self,
         key: AppConfigFragmentKey,
-        extra_config: Mapping[str, Any],
+        config: Mapping[str, Any],
     ) -> AppConfigFragmentData:
         creator: Creator[AppConfigFragmentRow] = Creator(
             spec=AppConfigFragmentCreatorSpec(
                 scope_type=key.scope_type,
                 scope_id=key.scope_id,
                 name=key.name,
-                extra_config=extra_config,
+                config=config,
             ),
         )
         return await self._db_source.create(creator)
@@ -90,16 +103,37 @@ async def create(
     async def update(
         self,
         key: AppConfigFragmentKey,
-        extra_config: Mapping[str, Any],
+        config: Mapping[str, Any],
     ) -> AppConfigFragmentData:
-        """Update a fragment by natural key. Raises
-        ``AppConfigFragmentNotFound`` when missing."""
-        spec = AppConfigFragmentUpdaterSpec(extra_config=extra_config)
-        return await self._db_source.update(key, spec)
+        """Update a fragment by natural key. Resolves the natural key
+        to the row's UUID, builds an ``Updater``, and delegates to the
+        DB source. Raises :class:`AppConfigFragmentNotFound` when the
+        row is missing (or vanishes between resolve and write)."""
+        pk_value = await self._db_source.resolve_pk_by_key(key)
+        if pk_value is None:
+            raise _missing(key)
+        updater: Updater[AppConfigFragmentRow] = Updater(
+            spec=AppConfigFragmentUpdaterSpec(config=config),
+            pk_value=pk_value,
+        )
+        result = await self._db_source.update(updater)
+        if result is None:
+            raise _missing(key)
+        return result
 
     @app_config_fragment_admin_repository_resilience.apply()
     async def purge(self, key: AppConfigFragmentKey) -> bool:
-        return await self._db_source.purge(key)
+        """Delete a fragment by natural key. Resolves the natural key,
+        builds a ``Purger``, and delegates to the DB source. Returns
+        ``True`` only when a row was actually removed."""
+        pk_value = await self._db_source.resolve_pk_by_key(key)
+        if pk_value is None:
+            return False
+        purger: Purger[AppConfigFragmentRow] = Purger(
+            row_class=AppConfigFragmentRow,
+            pk_value=pk_value,
+        )
+        return await self._db_source.purge(purger)
 
     # ── Cross-scope reads ────────────────────────────────────────
 

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

@@ -6,14 +6,8 @@
 from dataclasses import dataclass
 from typing import Any, override
 
-from ai.backend.manager.errors.app_config import (
-    AppConfigFragmentConflict,
-    AppConfigFragmentPolicyMissing,
-)
-from ai.backend.manager.errors.repository import (
-    ForeignKeyViolationError,
-    UniqueConstraintViolationError,
-)
+from ai.backend.manager.errors.app_config import AppConfigFragmentConflict
+from ai.backend.manager.errors.repository import UniqueConstraintViolationError
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
 from ai.backend.manager.repositories.base.creator import CreatorSpec
 from ai.backend.manager.repositories.base.types import IntegrityErrorCheck
@@ -23,17 +17,17 @@
 class AppConfigFragmentCreatorSpec(CreatorSpec[AppConfigFragmentRow]):
     """CreatorSpec for `app_config_fragments`.
 
-    Maps DB constraint violations onto typed domain errors:
-    - ``(scope_type, scope_id, name)`` UNIQUE → :class:`AppConfigFragmentConflict`
-    - ``name`` FK to `app_config_policies.config_name` →
-      :class:`AppConfigFragmentPolicyMissing` (required-policy invariant
-      enforced as defense-in-depth).
+    Maps the natural-key UNIQUE violation to a typed domain error
+    (:class:`AppConfigFragmentConflict`). The required-policy
+    invariant (FK on ``name``) is enforced upstream by the service
+    layer; the DB-level FK violation surfaces as a generic
+    integrity error here.
     """
 
     scope_type: str
     scope_id: str
     name: str
-    extra_config: Mapping[str, Any]
+    config: Mapping[str, Any]
 
     @property
     @override
@@ -47,12 +41,6 @@ def integrity_error_checks(self) -> Sequence[IntegrityErrorCheck]:
                     ),
                 ),
             ),
-            IntegrityErrorCheck(
-                violation_type=ForeignKeyViolationError,
-                error=AppConfigFragmentPolicyMissing(
-                    extra_msg=f"No app_config_policies row for name={self.name}",
-                ),
-            ),
         )
 
     @override
@@ -61,5 +49,5 @@ def build_row(self) -> AppConfigFragmentRow:
             scope_type=self.scope_type,
             scope_id=self.scope_id,
             name=self.name,
-            extra_config=dict(self.extra_config),
+            config=dict(self.config),
         )

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

@@ -20,7 +20,6 @@
     AppConfigFragmentSearchResult,
     AppConfigScopeType,
 )
-from ai.backend.manager.errors.app_config import AppConfigFragmentNotFound
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
 from ai.backend.manager.models.app_config_policy.row import AppConfigPolicyRow
 from ai.backend.manager.models.user import UserRow
@@ -29,9 +28,6 @@
     AppConfigFragmentSearchScope,
     UserAppConfigSearchScope,
 )
-from ai.backend.manager.repositories.app_config_fragment.updaters import (
-    AppConfigFragmentUpdaterSpec,
-)
 from ai.backend.manager.repositories.base.creator import Creator, execute_creator
 from ai.backend.manager.repositories.base.purger import Purger, execute_purger
 from ai.backend.manager.repositories.base.querier import BatchQuerier, execute_batch_querier
@@ -111,76 +107,48 @@ async def get_by_id(self, id: uuid.UUID) -> AppConfigFragmentData | None:
     async def create(self, creator: Creator[AppConfigFragmentRow]) -> AppConfigFragmentData:
         """Insert a new fragment via the shared Creator helper.
 
-        Constraint violations translate to typed domain errors via the
-        spec's ``integrity_error_checks`` (duplicate key →
-        :class:`AppConfigFragmentConflict`, missing-policy FK →
-        :class:`AppConfigFragmentPolicyMissing`).
+        The natural-key UNIQUE violation translates to
+        :class:`AppConfigFragmentConflict` via the spec's
+        ``integrity_error_checks``. The required-policy invariant
+        (FK on ``name``) is enforced upstream by the service layer;
+        a bypass here surfaces as a generic integrity error.
         """
         async with self._db.begin_session() as db_sess:
             result = await execute_creator(db_sess, creator)
             return result.row.to_data()
 
     @app_config_fragment_db_source_resilience.apply()
-    async def update(
+    async def resolve_pk_by_key(
         self,
         key: AppConfigFragmentKey,
-        spec: AppConfigFragmentUpdaterSpec,
-    ) -> AppConfigFragmentData:
-        """Update the fragment identified by its natural key.
-
-        The natural key ``(scope_type, scope_id, name)`` is not the PK,
-        so we first resolve it to the row's UUID `id` and then delegate
-        to the shared Updater helper (single-column PK required). Raises
-        :class:`AppConfigFragmentNotFound` when no row exists for the
-        key (or vanishes between resolve and write); reads use the
-        nullable `get(...)` instead.
-        """
-
-        def _missing() -> AppConfigFragmentNotFound:
-            return AppConfigFragmentNotFound(
-                extra_msg=(
-                    f"scope_type={key.scope_type.value!r}, "
-                    f"scope_id={key.scope_id!r}, name={key.name!r}"
-                ),
-            )
-
-        async with self._db.begin_session() as db_sess:
-            pk_value = await db_sess.scalar(
+    ) -> uuid.UUID | None:
+        """Resolve the natural key ``(scope_type, scope_id, name)`` to
+        the row's UUID ``id``. Returns ``None`` when no row matches —
+        callers translate to a domain-appropriate response."""
+        async with self._db.begin_readonly_session() as db_sess:
+            pk: uuid.UUID | None = await db_sess.scalar(
                 sa.select(AppConfigFragmentRow.id).where(
                     AppConfigFragmentRow.scope_type == key.scope_type,
                     AppConfigFragmentRow.scope_id == key.scope_id,
                     AppConfigFragmentRow.name == key.name,
                 )
             )
-            if pk_value is None:
-                raise _missing()
-            updater: Updater[AppConfigFragmentRow] = Updater(spec=spec, pk_value=pk_value)
-            result = await execute_updater(db_sess, updater)
-            if result is None:
-                raise _missing()
-            return result.row.to_data()
+            return pk
 
     @app_config_fragment_db_source_resilience.apply()
-    async def purge(self, key: AppConfigFragmentKey) -> bool:
-        """Delete the fragment identified by the natural key.
+    async def update(self, updater: Updater[AppConfigFragmentRow]) -> AppConfigFragmentData | None:
+        """Apply a pre-built Updater. Returns ``None`` when the row
+        vanished between PK resolution and write; the caller maps this
+        to :class:`AppConfigFragmentNotFound`."""
+        async with self._db.begin_session() as db_sess:
+            result = await execute_updater(db_sess, updater)
+            return result.row.to_data() if result is not None else None
 
-        Resolves the natural key to the row's UUID `id` and delegates
-        to the shared Purger helper. Returns `True` when a row was
-        actually removed.
-        """
+    @app_config_fragment_db_source_resilience.apply()
+    async def purge(self, purger: Purger[AppConfigFragmentRow]) -> bool:
+        """Apply a pre-built Purger. Returns ``True`` when a row was
+        actually removed (``False`` if the row vanished concurrently)."""
         async with self._db.begin_session() as db_sess:
-            pk_value = await db_sess.scalar(
-                sa.select(AppConfigFragmentRow.id).where(
-                    AppConfigFragmentRow.scope_type == key.scope_type,
-                    AppConfigFragmentRow.scope_id == key.scope_id,
-                    AppConfigFragmentRow.name == key.name,
-                )
-            )
-            if pk_value is None:
-                return False
-            purger: Purger[AppConfigFragmentRow] = Purger(
-                row_class=AppConfigFragmentRow, pk_value=pk_value
-            )
             result = await execute_purger(db_sess, purger)
             return result is not None
 
@@ -228,7 +196,7 @@ def _merge_chain(
         chain: Sequence[str],
     ) -> _MergedChain:
         """Order `rows` by `chain` (low → high) and deep-merge their
-        `extra_config` in that order. Empty result projects to `None`.
+        `config` in that order. Empty result projects to `None`.
 
         Shared by the single-doc and search merge methods so both paths
         produce the same shape.
@@ -239,9 +207,9 @@ def _merge_chain(
         ]
         merged: Mapping[str, Any] = {}
         for row in ordered:
-            if row.extra_config is None:
+            if row.config is None:
                 continue
-            merged = deep_merge(merged, row.extra_config)
+            merged = deep_merge(merged, row.config)
         return _MergedChain(
             fragments=[row.to_data() for row in ordered],
             config=(merged or None),

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

@@ -14,12 +14,12 @@
 class AppConfigFragmentUpdaterSpec(UpdaterSpec[AppConfigFragmentRow]):
     """UpdaterSpec for `app_config_fragments`.
 
-    Only `extra_config` is mutable — the ``(scope_type, scope_id, name)``
+    Only `config` is mutable — the ``(scope_type, scope_id, name)``
     natural key is fixed; changing any of those is a new row, not an
     update.
     """
 
-    extra_config: Mapping[str, Any]
+    config: Mapping[str, Any]
 
     @property
     @override
@@ -28,4 +28,4 @@ def row_class(self) -> type[AppConfigFragmentRow]:
 
     @override
     def build_values(self) -> dict[str, Any]:
-        return {"extra_config": dict(self.extra_config)}
+        return {"config": dict(self.config)}