feat(BA-6191): add ScopeCreatorSpec, ScopePurgerSpec, and ScopeWriteOps

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

Author: fregataa

changes/11843.feature.md

@@ -0,0 +1 @@
+Add `ScopeCreatorSpec` / `ScopePurgerSpec` composite specs and a dedicated `ScopeWriteOps` class that provisions a new RBAC scope (scope row, preset-derived roles + permissions, role-to-scope and parent-scope associations) or tears one down in a single transaction.

src/ai/backend/manager/repositories/base/__init__.py

@@ -63,6 +63,17 @@
     execute_batch_querier,
     execute_querier,
 )
+from .scope_creator import (
+    ScopeContext,
+    ScopeCreator,
+    ScopeCreatorResult,
+    ScopeCreatorSpec,
+)
+from .scope_purger import (
+    ScopePurger,
+    ScopePurgerResult,
+    ScopePurgerSpec,
+)
 from .types import (
     CursorConditionFactory,
     ExistenceCheck,
@@ -190,6 +201,15 @@
     "BatchPurger",
     "BatchPurgerResult",
     "execute_batch_purger",
+    # ScopeCreator
+    "ScopeCreatorSpec",
+    "ScopeCreator",
+    "ScopeCreatorResult",
+    "ScopeContext",
+    # ScopePurger
+    "ScopePurgerSpec",
+    "ScopePurger",
+    "ScopePurgerResult",
     # Utils
     "combine_conditions_and",
     "combine_conditions_or",

src/ai/backend/manager/repositories/base/scope_creator.py

@@ -0,0 +1,92 @@
+"""Composite spec for race-free scope provisioning.
+
+A scope-creator spec coordinates the inserts that together provision a new RBAC
+scope: the scope row itself (domain, project, ...), any parent-scope mapping
+rows, and roles + role-scope associations + permissions instantiated from each
+active role preset matching the scope type.
+
+The spec itself owns no table; each returned sub-spec owns exactly one table,
+preserving the per-spec single-table rule. Orchestration lives in
+:meth:`ScopeWriteOps.create_scope`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ai.backend.common.data.permission.types import RBACElementType
+from ai.backend.manager.models.base import Base
+from ai.backend.manager.models.rbac_models.association_scopes_entities import (
+    AssociationScopesEntitiesRow,
+)
+from ai.backend.manager.models.rbac_models.role import RoleRow
+
+from .creator import CreatorSpec
+
+
+@dataclass(frozen=True)
+class ScopeContext:
+    """Locator for a scope row.
+
+    Carries the ``(scope_type, scope_id)`` pair used by downstream RBAC tables
+    (``permissions``, ``association_scopes_entities``) to reference the scope.
+    """
+
+    scope_type: RBACElementType
+    scope_id: str
+
+
+class ScopeCreatorSpec[TScopeRow: Base](ABC):
+    """Coordinator for ``scope row + parent-scope association rows``.
+
+    Subclass per scope type (e.g. ``DomainScopeCreatorSpec``,
+    ``ProjectScopeCreatorSpec``). Each returned sub-spec owns exactly one table.
+    """
+
+    @abstractmethod
+    def scope_spec(self) -> CreatorSpec[TScopeRow]:
+        """Single-table spec for the scope row."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def extract_scope_context(self, scope_row: TScopeRow) -> ScopeContext:
+        """Derive ``(scope_type, scope_id)`` from the just-inserted scope row.
+
+        The orchestrator uses this to look up matching role presets and to populate
+        ``scope_id`` on derived permission and association rows.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def parent_association_specs(
+        self,
+        scope_row: TScopeRow,
+    ) -> Sequence[CreatorSpec[AssociationScopesEntitiesRow]]:
+        """Parent-scope mapping rows (e.g. project under domain).
+
+        Return ``[]`` if the scope type has no parent.
+        """
+        raise NotImplementedError
+
+
+@dataclass
+class ScopeCreator[TScopeRow: Base]:
+    """Bundles a scope-creator spec for ``ScopeWriteOps.create_scope``."""
+
+    spec: ScopeCreatorSpec[TScopeRow]
+
+
+@dataclass
+class ScopeCreatorResult[TScopeRow: Base]:
+    """Outcome of a successful scope provisioning.
+
+    Only surfaces the freshly-inserted scope row and the roles that were
+    instantiated from active role presets. Auxiliary rows (permissions,
+    role-to-scope associations, parent-scope associations) are still
+    inserted by the orchestrator but are not returned.
+    """
+
+    scope_row: TScopeRow
+    role_rows: list[RoleRow]

src/ai/backend/manager/repositories/base/scope_purger.py

@@ -0,0 +1,74 @@
+"""Composite spec for race-free scope teardown.
+
+Mirror of :mod:`scope_creator`. A scope-purger spec coordinates the inverse
+sequence: drop scope-bound permission rows, drop the scope's association rows,
+and finally drop the scope row itself.
+
+Roles are intentionally left alone — role lifecycle is independent of scope
+lifecycle, and a role may be reused or reassigned after a scope is gone.
+
+The spec itself owns no table; each returned sub-spec targets exactly one table.
+Orchestration lives in :meth:`ScopeWriteOps.purge_scope`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from uuid import UUID
+
+from ai.backend.manager.models.base import Base
+from ai.backend.manager.models.rbac_models.association_scopes_entities import (
+    AssociationScopesEntitiesRow,
+)
+from ai.backend.manager.models.rbac_models.permission.permission import PermissionRow
+
+from .purger import BatchPurgerSpec
+
+
+class ScopePurgerSpec[TScopeRow: Base](ABC):
+    """Coordinator for purging a scope and the scope-bound RBAC rows it leaves behind.
+
+    Subclass per scope type. Each returned sub-spec targets exactly one table.
+    """
+
+    @abstractmethod
+    def scope_row_class(self) -> type[TScopeRow]:
+        """ORM class of the scope row being purged."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def scope_pk_value(self) -> UUID | str:
+        """Primary-key value of the scope row to delete."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def permissions_purge_spec(self) -> BatchPurgerSpec[PermissionRow]:
+        """Subquery selecting permission rows pinned to this scope."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def associations_purge_spec(self) -> BatchPurgerSpec[AssociationScopesEntitiesRow]:
+        """Single subquery selecting every association row to drop for this scope.
+
+        Multiple conditions (scope referenced as scope, scope referenced as entity, ...)
+        should be OR-combined into one ``WHERE`` clause; ``execute_batch_purger`` will
+        chunk the resulting set into batches automatically.
+        """
+        raise NotImplementedError
+
+
+@dataclass
+class ScopePurger[TScopeRow: Base]:
+    """Bundles a scope-purger spec for ``ScopeWriteOps.purge_scope``."""
+
+    spec: ScopePurgerSpec[TScopeRow]
+
+
+@dataclass
+class ScopePurgerResult[TScopeRow: Base]:
+    """Outcome of a scope teardown."""
+
+    scope_row: TScopeRow | None
+    deleted_permission_count: int
+    deleted_association_count: int