feat(BA-6628): cascade fragment deletion from the allow list

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jopemachine

proposals/BEP-1052-scoped-app-config-redesign.md

@@ -72,12 +72,13 @@ Three scopes cover the use cases (`public` for the pre-login shell):
   joined to `app_config_allow_list` only for each fragment's `rank` — an
   indexed `(config_name, scope_type)` join. No permission or policy is
   evaluated at read time.
-- **Allow-list = the write gate for every fragment.** `app_config_allow_list`
+- **Allow-list = the write gate and the merge order.** `app_config_allow_list`
   holds **one record per `(config_name, scope_type)`**; a fragment at
-  that scope may be created/updated/purged **only if** the record exists
-  — through the admin mutations and the regular ones alike. What sets
-  admins apart is that they alone manage the allow-list (and the
-  `app_config_definitions`) itself. It governs **writes only** — never reads.
+  that scope may be created **only if** the record exists — through the
+  admin mutations and the regular ones alike. Fragments reference their
+  entry by FK (`ON DELETE CASCADE`), so removing an entry removes its
+  fragments. What sets admins apart is that they alone manage the
+  allow-list (and the `app_config_definitions`) itself.
 - **`rank` lives on the allow-list entry.** Merge priority is an
   admin-owned policy: it sits on the (admin-managed) allow-list entry,
   not on the fragment — a fragment owner editing their own fragment can
@@ -110,12 +111,13 @@ Keyed by the natural composite `(scope_type, scope_id, config_name)`
 - `scope_type` — `public | domain | user`.
 - `scope_id` — the scope's identifier (see convention below).
 - `config_name` — FK → `app_config_definitions.config_name`.
+- `(config_name, scope_type)` — composite FK →
+  `app_config_allow_list` with `ON DELETE CASCADE`: a fragment exists
+  only while its allow-list entry does, and carries no rank of its own —
+  its merge priority is the entry's `rank` (see §2).
 - `config` — schema-less JSON payload.
 - `created_at` / `updated_at`.
 
-The fragment carries no rank of its own — its merge priority is its
-allow-list entry's `rank` (see §2).
-
 ### `app_config_allow_list` — the per-`(config_name, scope_type)` write gate
 
 One row per `(config_name, scope_type)` (unique) — a normalized,
@@ -135,7 +137,8 @@ advance.
 
 A row's **presence** is the write grant, and its `rank` is the merge
 order of its fragments. It gates **both** write paths; admins, unlike
-users, may also create/update/purge the allow-list rows themselves.
+users, may also create/purge the allow-list rows themselves — and
+purging one cascades to its fragments.
 
 ### Scope-ID convention
 
@@ -147,20 +150,22 @@ users, may also create/update/purge the allow-list rows themselves.
 
 ### Integrity
 
-- **Every** fragment write (admin or regular) requires (a) a registered
+- **Every** fragment create (admin or regular) requires (a) a registered
   `config_name` (FK to `app_config_definitions`) and (b) an
   `app_config_allow_list` row for the write's `(config_name,
-  scope_type)`. The service layer rejects per-row when either is missing.
+  scope_type)` — enforced both by the write gate (domain error) and by
+  the composite FK. Updates and purges of an existing fragment need no
+  gate: the FK guarantees the entry exists while the fragment does.
 - A regular (non-admin) mutation is further restricted to the caller's
   own `user` row; admin mutations may target any scope (still gated by
   the allow-list) and are the only writes that may touch the allow-list
   and `app_config_definitions`.
 - `app_config_definitions` purge is rejected while any fragment or allow-list
   entry still references the `config_name` (`ON DELETE NO ACTION`).
-- `app_config_allow_list` purge **revokes future writes** at that
-  `(config_name, scope_type)`. Because reads never consult the
-  allow-list, **existing fragments are untouched and keep merging** — to
-  actually drop a value, an admin purges the fragments themselves.
+- `app_config_allow_list` purge **revokes the grant and drops its data**:
+  the fragments at that `(config_name, scope_type)` are removed by the
+  `ON DELETE CASCADE` FK, so a revoked value disappears from the merge
+  in the same statement — no orphaned fragments to clean up separately.
 
 <a id="write-model"></a>
 ### Write model
@@ -196,9 +201,8 @@ boundary.
 
 To promote a fixed value to user-customizable, the admin adds a single
 `(config_name, user)` grant — no data migration. To lock it back down,
-the admin removes the grant **and** purges any existing `user` fragments
-(removing the grant alone only blocks new writes; reads still merge what
-is already stored).
+the admin removes the grant: the cascade drops the existing `user`
+fragments with it, so the admin value applies again immediately.
 
 ---
 
@@ -300,12 +304,11 @@ likewise `null` — clients fall back to their built-in defaults.
   user)` grant; users then create/update/purge their own copy. No data
   migration.
 - **Admin locks a value back down** — remove the `(config_name, user)`
-  grant **and** purge existing `user` fragments (the grant gates writes,
-  not reads).
+  grant; the cascade drops the existing `user` fragments with it.
 - **Admin reorders contributions** — set the allow-list entries'
   `rank`s (per `(config_name, scope_type)`, not per fragment).
-- **Admin retires a config name** — purge the fragments, then the
-  allow-list entries, then the `app_config_definitions` row (purge is rejected
+- **Admin retires a config name** — purge the allow-list entries (their
+  fragments cascade), then the `app_config_definitions` row (purge is rejected
   while references remain).
 - **Admin audit** — cross-scope fragment search and cross-user merged
   search for support.

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

@@ -0,0 +1,58 @@
+"""cascade fragment deletion from app_config_allow_list
+
+Add a composite FK from ``app_config_fragments (config_name, scope_type)`` to
+``app_config_allow_list`` with ``ON DELETE CASCADE`` (BEP-1052): removing an
+allow-list entry removes every fragment written under it, so a revoked value
+disappears from the merge in the same statement. Fragments whose allow-list
+entry was already removed (previously kept and still merged) are deleted before
+the FK is added — the same outcome the cascade would have produced.
+
+Revision ID: a560420476b6
+Revises: 66d0f891ed20
+Create Date: 2026-07-03
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "a560420476b6"
+down_revision = "66d0f891ed20"
+# Part of: NEXT_RELEASE_VERSION
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Fragments without an allow-list entry are unrepresentable once the FK exists;
+    # remove them as the cascade would have when the entry was purged.
+    op.execute(
+        sa.text(
+            """
+            DELETE FROM app_config_fragments f
+            WHERE NOT EXISTS (
+                SELECT 1
+                FROM app_config_allow_list al
+                WHERE al.config_name = f.config_name
+                  AND al.scope_type = f.scope_type
+            )
+            """
+        )
+    )
+    op.create_foreign_key(
+        "fk_app_config_fragments_config_name_scope_type",
+        "app_config_fragments",
+        "app_config_allow_list",
+        ["config_name", "scope_type"],
+        ["config_name", "scope_type"],
+        ondelete="CASCADE",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        "fk_app_config_fragments_config_name_scope_type",
+        "app_config_fragments",
+        type_="foreignkey",
+    )

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

@@ -18,10 +18,12 @@
 class AppConfigAllowListRow(Base):  # type: ignore[misc]
     """Permission to write config fragments for one config name at one scope type.
 
-    A config fragment may be created, updated, or purged only when a matching row
-    exists here; without one, the write is rejected. ``rank`` is the merge priority
-    the entry's fragments carry (low → high; higher wins) — admin-owned here so
-    fragment owners cannot re-order the merge. There is at most one row per
+    A config fragment may be created only when a matching row exists here; without
+    one, the write is rejected. Fragments reference this table by
+    ``(config_name, scope_type)`` with ``ON DELETE CASCADE``, so removing an entry
+    also removes every fragment written under it. ``rank`` is the merge priority the
+    entry's fragments carry (low → high; higher wins) — admin-owned here so fragment
+    owners cannot re-order the merge. There is at most one row per
     ``(config_name, scope_type)``, and only admins create or remove these rows.
     """
 

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

@@ -20,8 +20,10 @@
 class AppConfigFragmentRow(Base):  # type: ignore[misc]
     """One scoped app config fragment — a single JSON document at ``(config_name, scope_type, scope_id)``.
 
-    The fragment carries no merge priority of its own — its rank is the ``rank`` of
-    the allow-list entry for its ``(config_name, scope_type)``.
+    A fragment hangs off its ``app_config_allow_list`` entry (FK on
+    ``(config_name, scope_type)``, ``ON DELETE CASCADE``): it exists only while the
+    entry does, and its merge priority is the entry's ``rank`` — the fragment row
+    carries no rank of its own.
     """
 
     __tablename__ = "app_config_fragments"
@@ -32,6 +34,12 @@ class AppConfigFragmentRow(Base):  # type: ignore[misc]
             "scope_id",
             name="uq_app_config_fragments_config_name_scope_type_scope_id",
         ),
+        sa.ForeignKeyConstraint(
+            ["config_name", "scope_type"],
+            ["app_config_allow_list.config_name", "app_config_allow_list.scope_type"],
+            name="fk_app_config_fragments_config_name_scope_type",
+            ondelete="CASCADE",
+        ),
     )
 
     id: Mapped[AppConfigFragmentID] = mapped_column(

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

@@ -73,7 +73,8 @@ async def create(
         only_if: ExistsQuerier[AppConfigAllowListRow],
     ) -> AppConfigFragmentData:
         # ``only_if`` (built by the caller) and the write run in one transaction, so the gate
-        # check and the write commit atomically — no check-then-write race.
+        # check and the write commit atomically — no check-then-write race. The FK to the
+        # allow-list would also reject the insert, but the gate surfaces the domain error.
         async with self._ops.write_ops() as w:
             if not await w.exists(only_if):
                 raise AppConfigFragmentWriteNotAllowed(
@@ -92,36 +93,20 @@ async def get_by_id(self, fragment_id: AppConfigFragmentID) -> AppConfigFragment
             return result.row.to_data()
 
     @app_config_fragment_db_source_resilience.apply()
-    async def update(
-        self,
-        updater: Updater[AppConfigFragmentRow],
-        only_if: ExistsQuerier[AppConfigAllowListRow],
-    ) -> AppConfigFragmentData:
-        # Gate first, then write — both in one transaction so the check and the write commit
-        # atomically. A missing fragment surfaces as the update returning None below.
+    async def update(self, updater: Updater[AppConfigFragmentRow]) -> AppConfigFragmentData:
+        # No write-gate here: the FK to the allow-list guarantees a fragment row exists
+        # only while its ``(config_name, scope_type)`` entry does, so an existing
+        # fragment is always writable at its own scope.
         async with self._ops.write_ops() as w:
-            if not await w.exists(only_if):
-                raise AppConfigFragmentWriteNotAllowed(
-                    f"Writing app config fragment {updater.pk_value} is not allowed."
-                )
             result = await w.update(updater)
             if result is None:
                 raise AppConfigFragmentNotFound(f"App config fragment {updater.pk_value} not found")
             return result.row.to_data()
 
     @app_config_fragment_db_source_resilience.apply()
-    async def purge(
-        self,
-        purger: Purger[AppConfigFragmentRow],
-        only_if: ExistsQuerier[AppConfigAllowListRow],
-    ) -> AppConfigFragmentData:
-        # Gate first, then write — both in one transaction so the check and the write commit
-        # atomically. A missing fragment surfaces as the purge returning None below.
+    async def purge(self, purger: Purger[AppConfigFragmentRow]) -> AppConfigFragmentData:
+        # No write-gate here — see ``update``.
         async with self._ops.write_ops() as w:
-            if not await w.exists(only_if):
-                raise AppConfigFragmentWriteNotAllowed(
-                    f"Writing app config fragment {purger.pk_value} is not allowed."
-                )
             result = await w.purge(purger)
             if result is None:
                 raise AppConfigFragmentNotFound(f"App config fragment {purger.pk_value} not found")

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

@@ -67,20 +67,12 @@ async def get_by_id(self, fragment_id: AppConfigFragmentID) -> AppConfigFragment
         return await self._db_source.get_by_id(fragment_id)
 
     @app_config_fragment_repository_resilience.apply()
-    async def update(
-        self,
-        updater: Updater[AppConfigFragmentRow],
-        only_if: ExistsQuerier[AppConfigAllowListRow],
-    ) -> AppConfigFragmentData:
-        return await self._db_source.update(updater, only_if)
+    async def update(self, updater: Updater[AppConfigFragmentRow]) -> AppConfigFragmentData:
+        return await self._db_source.update(updater)
 
     @app_config_fragment_repository_resilience.apply()
-    async def purge(
-        self,
-        purger: Purger[AppConfigFragmentRow],
-        only_if: ExistsQuerier[AppConfigAllowListRow],
-    ) -> AppConfigFragmentData:
-        return await self._db_source.purge(purger, only_if)
+    async def purge(self, purger: Purger[AppConfigFragmentRow]) -> AppConfigFragmentData:
+        return await self._db_source.purge(purger)
 
     @app_config_fragment_repository_resilience.apply()
     async def admin_search(self, querier: BatchQuerier) -> AppConfigFragmentSearchResult:

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

@@ -7,9 +7,8 @@
 from ai.backend.manager.actions.types import ActionOperationType
 from ai.backend.manager.data.app_config_fragment.types import AppConfigFragmentData
 from ai.backend.manager.data.permission.types import RBACElementRef
-from ai.backend.manager.models.app_config_allow_list.row import AppConfigAllowListRow
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
-from ai.backend.manager.repositories.base import ExistsQuerier, Purger
+from ai.backend.manager.repositories.base import Purger
 from ai.backend.manager.services.app_config_fragment.actions.base import (
     AppConfigFragmentSingleEntityAction,
     AppConfigFragmentSingleEntityActionResult,
@@ -20,13 +19,13 @@
 class PurgeAppConfigFragmentAction(AppConfigFragmentSingleEntityAction):
     """Purge a fragment — not admin-only.
 
-    Gated by the allow-list write-gate (``only_if``) against the fragment's
-    ``(config_name, scope_type)``, so an allow-listed user may purge their own
-    ``user``-scope fragment.
+    No allow-list gate is needed — a fragment row exists only while its
+    ``(config_name, scope_type)`` allow-list entry does (FK with cascade), so an
+    existing fragment is always removable at its own scope. Purging the allow-list
+    entry itself cascades to its fragments without going through this action.
     """
 
     purger: Purger[AppConfigFragmentRow]
-    only_if: ExistsQuerier[AppConfigAllowListRow]
 
     @override
     @classmethod

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

@@ -7,9 +7,8 @@
 from ai.backend.manager.actions.types import ActionOperationType
 from ai.backend.manager.data.app_config_fragment.types import AppConfigFragmentData
 from ai.backend.manager.data.permission.types import RBACElementRef
-from ai.backend.manager.models.app_config_allow_list.row import AppConfigAllowListRow
 from ai.backend.manager.models.app_config_fragment.row import AppConfigFragmentRow
-from ai.backend.manager.repositories.base import ExistsQuerier, Updater
+from ai.backend.manager.repositories.base import Updater
 from ai.backend.manager.services.app_config_fragment.actions.base import (
     AppConfigFragmentSingleEntityAction,
     AppConfigFragmentSingleEntityActionResult,
@@ -20,13 +19,13 @@
 class UpdateAppConfigFragmentAction(AppConfigFragmentSingleEntityAction):
     """Update a fragment's ``config`` (replaced wholesale).
 
-    Not admin-only: an allow-listed user may update their own ``user``-scope fragment. The
-    allow-list write-gate (``only_if``) authorizes the write against the fragment's
-    ``(config_name, scope_type)``.
+    Not admin-only: a user may update their own ``user``-scope fragment. No allow-list
+    gate is needed — a fragment row exists only while its ``(config_name, scope_type)``
+    allow-list entry does (FK with cascade), so an existing fragment is always writable
+    at its own scope.
     """
 
     updater: Updater[AppConfigFragmentRow]
-    only_if: ExistsQuerier[AppConfigAllowListRow]
 
     @override
     @classmethod

src/ai/backend/manager/services/app_config_fragment/service.py

@@ -34,12 +34,14 @@
 class AppConfigFragmentService:
     """Write/read paths for app config fragments (not admin-only).
 
-    ``create`` / ``update`` / ``purge`` are gated by the allow-list write-gate in the
-    repository: the gate check and the write run in a single transaction, so a fragment is
-    only written or removed when an ``app_config_allow_list`` row exists for its
-    ``(config_name, scope_type)``. Because an allow-list row requires a registered
-    ``config_name`` (FK), this also enforces registration. An allow-listed user may
-    therefore manage their own ``user``-scope fragment without admin privileges.
+    ``create`` is gated by the allow-list write-gate in the repository: the gate check
+    and the write run in a single transaction, so a fragment is only written when an
+    ``app_config_allow_list`` row exists for its ``(config_name, scope_type)``. Because
+    an allow-list row requires a registered ``config_name`` (FK), this also enforces
+    registration. ``update`` / ``purge`` need no gate — the fragments' FK to the
+    allow-list (``ON DELETE CASCADE``) guarantees an existing fragment's entry exists.
+    An allow-listed user may therefore manage their own ``user``-scope fragment without
+    admin privileges.
     """
 
     _repository: AppConfigFragmentRepository
@@ -85,11 +87,11 @@ async def scoped_search(
     async def update(
         self, action: UpdateAppConfigFragmentAction
     ) -> UpdateAppConfigFragmentActionResult:
-        data = await self._repository.update(action.updater, action.only_if)
+        data = await self._repository.update(action.updater)
         return UpdateAppConfigFragmentActionResult(fragment=data)
 
     async def purge(
         self, action: PurgeAppConfigFragmentAction
     ) -> PurgeAppConfigFragmentActionResult:
-        data = await self._repository.purge(action.purger, action.only_if)
+        data = await self._repository.purge(action.purger)
         return PurgeAppConfigFragmentActionResult(fragment=data)