refactor(BA-5777): rename Batch to Bulk to match updated issue terminology

fregataa · claude · fregataa · commit 4d262a7c0133 · 2026-04-21T13:03:58.000+09:00
BA-5777 description was revised to use "Bulk" throughout. Rename the identifiers introduced in this branch to match: - Files: action/batch.py → action/bulk.py and the mirrors under processor/, validator/, validators/rbac/, plus the test file - Classes & type vars: BaseBatchAction → BaseBulkAction, BaseBatchActionResult → BaseBulkActionResult, BatchActionValidator → BulkActionValidator, BatchActionRBACValidator → BulkActionRBACValidator, BatchActionProcessor → BulkActionProcessor, BatchValidationResult → BulkValidationResult, BatchValidatorDecision → BulkValidatorDecision, BatchProcessResult → BulkProcessResult, TBatchAction/TBatchActionResult → TBulkAction/TBulkActionResult - __init__ exports and changelog fragment updated accordingly Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/changes/11191.feature.md b/changes/11191.feature.md
@@ -1 +1 @@
-Add batch RBAC filtering infrastructure so `BatchActionProcessor` can narrow actions per-entity and report per-validator decisions.
+Add bulk RBAC filtering infrastructure so `BulkActionProcessor` can narrow actions per-entity and report per-validator decisions.
diff --git a/src/ai/backend/manager/actions/action/__init__.py b/src/ai/backend/manager/actions/action/__init__.py
@@ -8,9 +8,9 @@
     TAction,
     TActionResult,
 )
-from .batch import (
-    BaseBatchAction,
-    BaseBatchActionResult,
+from .bulk import (
+    BaseBulkAction,
+    BaseBulkActionResult,
 )
 from .rbac import (
     BaseRBACAction,
@@ -111,8 +111,8 @@
     "BaseActionResult",
     "BaseActionResultMeta",
     "BaseActionTriggerMeta",
-    "BaseBatchAction",
-    "BaseBatchActionResult",
+    "BaseBulkAction",
+    "BaseBulkActionResult",
     "BaseRBACAction",
     "RBACActionName",
     "RBACRequiredPermission",
diff --git a/src/ai/backend/manager/actions/action/bulk.py b/src/ai/backend/manager/actions/action/bulk.py
@@ -6,16 +6,16 @@
 
 
 @dataclass
-class BaseBatchAction[T](BaseAction):
-    """Base class for actions operating on a batch of entities.
+class BaseBulkAction[T](BaseAction):
+    """Base class for actions operating on a bulk of entities.
 
-    ``entity_ids`` is stored as ``list[str]`` so ``BatchActionValidator``
+    ``entity_ids`` is stored as ``list[str]`` so ``BulkActionValidator``
     implementations can match against validator verdicts directly. The
     original ``T``-typed view is exposed via ``typed_entity_ids()``.
 
-    Batch actions intentionally carry **only** ``entity_ids``. User context
+    Bulk actions intentionally carry **only** ``entity_ids``. User context
     (user id, role) flows through ``current_user()``, not the action, so
-    ``BatchActionProcessor`` can reconstruct a filtered action by calling
+    ``BulkActionProcessor`` can reconstruct a filtered action by calling
     ``type(action)(entity_ids=...)`` directly — no ``__init__`` override or
     factory hook is required. Subclasses that try to add required fields
     break that constructor call and will fail fast at runtime, which is
@@ -30,7 +30,7 @@ def typed_entity_ids(self) -> list[T]:
         raise NotImplementedError
 
 
-class BaseBatchActionResult(BaseActionResult):
+class BaseBulkActionResult(BaseActionResult):
     @override
     def entity_id(self) -> str | None:
         return None
@@ -40,5 +40,5 @@ def entity_ids(self) -> list[str]:
         raise NotImplementedError
 
 
-TBatchAction = TypeVar("TBatchAction", bound=BaseBatchAction[Any])
-TBatchActionResult = TypeVar("TBatchActionResult", bound=BaseBatchActionResult)
+TBulkAction = TypeVar("TBulkAction", bound=BaseBulkAction[Any])
+TBulkActionResult = TypeVar("TBulkActionResult", bound=BaseBulkActionResult)
diff --git a/src/ai/backend/manager/actions/processor/bulk.py b/src/ai/backend/manager/actions/processor/bulk.py
@@ -10,14 +10,14 @@
 from ai.backend.manager.actions.action import (
     BaseActionTriggerMeta,
 )
-from ai.backend.manager.actions.action.batch import (
-    BaseBatchAction,
-    BaseBatchActionResult,
+from ai.backend.manager.actions.action.bulk import (
+    BaseBulkAction,
+    BaseBulkActionResult,
 )
 from ai.backend.manager.actions.monitors.monitor import ActionMonitor
-from ai.backend.manager.actions.validator.batch import (
-    BatchActionValidator,
-    BatchValidationResult,
+from ai.backend.manager.actions.validator.bulk import (
+    BulkActionValidator,
+    BulkValidationResult,
 )
 
 from .base import ActionRunner
@@ -26,45 +26,45 @@
 
 
 @dataclass(frozen=True)
-class BatchValidatorDecision:
-    """One validator's per-entity verdict observed during batch processing.
+class BulkValidatorDecision:
+    """One validator's per-entity verdict observed during bulk processing.
 
     Mirrors the ``SubStepResult`` pattern used by the scheduler history so
     callers can trace where in the validator chain each ID was filtered and
     *why*. ``results`` carries the validator's classification unchanged.
     """
 
     validator_name: str
-    results: BatchValidationResult
+    results: BulkValidationResult
 
 
 @dataclass(frozen=True)
-class BatchProcessResult[TBatchActionResult: BaseBatchActionResult]:
-    """Outcome of a ``BatchActionProcessor`` run.
+class BulkProcessResult[TBulkActionResult: BaseBulkActionResult]:
+    """Outcome of a ``BulkActionProcessor`` run.
 
     ``result`` is what the service function returned for the permitted subset
     of entity IDs. ``validator_decisions`` keeps the per-validator trace in
     iteration order; callers assemble the partial-success response by
     walking it (each decision carries the denied IDs and their reasons).
     """
 
-    result: TBatchActionResult
-    validator_decisions: list[BatchValidatorDecision]
+    result: TBulkActionResult
+    validator_decisions: list[BulkValidatorDecision]
 
 
-class BatchActionProcessor[
-    TBatchAction: BaseBatchAction[Any],
-    TBatchActionResult: BaseBatchActionResult,
+class BulkActionProcessor[
+    TBulkAction: BaseBulkAction[Any],
+    TBulkActionResult: BaseBulkActionResult,
 ]:
-    _validators: Sequence[BatchActionValidator]
+    _validators: Sequence[BulkActionValidator]
 
-    _runner: ActionRunner[TBatchAction, TBatchActionResult]
+    _runner: ActionRunner[TBulkAction, TBulkActionResult]
 
     def __init__(
         self,
-        func: Callable[[TBatchAction], Awaitable[TBatchActionResult]],
+        func: Callable[[TBulkAction], Awaitable[TBulkActionResult]],
         monitors: Sequence[ActionMonitor] | None = None,
-        validators: Sequence[BatchActionValidator] | None = None,
+        validators: Sequence[BulkActionValidator] | None = None,
     ) -> None:
         self._runner = ActionRunner(func, monitors)
 
@@ -73,13 +73,13 @@ def __init__(
     @asynccontextmanager
     async def _validator_scope(
         self,
-        validator: BatchActionValidator,
-        action: TBatchAction,
+        validator: BulkActionValidator,
+        action: TBulkAction,
         meta: BaseActionTriggerMeta,
-    ) -> AsyncIterator[BatchValidationResult]:
+    ) -> AsyncIterator[BulkValidationResult]:
         """Run one validator inside a bookend scope.
 
-        Yields the validator's ``BatchValidationResult`` so the caller can
+        Yields the validator's ``BulkValidationResult`` so the caller can
         record the decision inside the block. Timing and per-validator
         logging live here rather than inside each validator implementation.
         """
@@ -90,7 +90,7 @@ async def _validator_scope(
         finally:
             duration = (datetime.now(UTC) - started_at).total_seconds()
             log.debug(
-                "batch validator {} saw {} ids, denied {} in {:.3f}s",
+                "bulk validator {} saw {} ids, denied {} in {:.3f}s",
                 validator.name(),
                 len(validation.allowed_entity_ids) + len(validation.denied_entities),
                 len(validation.denied_entities),
@@ -99,9 +99,9 @@ async def _validator_scope(
 
     def _process_action(
         self,
-        current_action: TBatchAction,
-        validation: BatchValidationResult,
-    ) -> TBatchAction:
+        current_action: TBulkAction,
+        validation: BulkValidationResult,
+    ) -> TBulkAction:
         """Return a new action narrowed to the IDs this validator permitted.
 
         Returns the incoming action unchanged when the validator denied
@@ -115,30 +115,28 @@ def _process_action(
         filtered_ids = [eid for eid in current_action.entity_ids if eid in allowed_set]
         return type(current_action)(entity_ids=filtered_ids)
 
-    async def _run(self, action: TBatchAction) -> BatchProcessResult[TBatchActionResult]:
+    async def _run(self, action: TBulkAction) -> BulkProcessResult[TBulkActionResult]:
         started_at = datetime.now(UTC)
         action_id = uuid.uuid4()
         action_trigger_meta = BaseActionTriggerMeta(action_id=action_id, started_at=started_at)
 
-        current_action: TBatchAction = action
-        decisions: list[BatchValidatorDecision] = []
+        current_action: TBulkAction = action
+        decisions: list[BulkValidatorDecision] = []
 
         for validator in self._validators:
             async with self._validator_scope(
                 validator, current_action, action_trigger_meta
             ) as validation:
                 decisions.append(
-                    BatchValidatorDecision(
+                    BulkValidatorDecision(
                         validator_name=validator.name(),
                         results=validation,
                     )
                 )
                 current_action = self._process_action(current_action, validation)
 
         action_result = await self._runner.run(current_action, action_trigger_meta)
-        return BatchProcessResult(result=action_result, validator_decisions=decisions)
+        return BulkProcessResult(result=action_result, validator_decisions=decisions)
 
-    async def wait_for_complete(
-        self, action: TBatchAction
-    ) -> BatchProcessResult[TBatchActionResult]:
+    async def wait_for_complete(self, action: TBulkAction) -> BulkProcessResult[TBulkActionResult]:
         return await self._run(action)
diff --git a/src/ai/backend/manager/actions/validator/bulk.py b/src/ai/backend/manager/actions/validator/bulk.py
@@ -3,36 +3,36 @@
 from typing import Any
 
 from ai.backend.manager.actions.action import BaseActionTriggerMeta
-from ai.backend.manager.actions.action.batch import BaseBatchAction
+from ai.backend.manager.actions.action.bulk import BaseBulkAction
 
 
 @dataclass(frozen=True)
 class DeniedEntity:
-    """A batch entity that a validator rejected, paired with its reason."""
+    """A bulk entity that a validator rejected, paired with its reason."""
 
     entity_id: str
     deny_reason: str
 
 
 @dataclass(frozen=True)
-class BatchValidationResult:
-    """Per-entity validation outcome for a batch action.
+class BulkValidationResult:
+    """Per-entity validation outcome for a bulk action.
 
-    ``BatchActionProcessor`` intersects ``allowed_entity_ids`` across
+    ``BulkActionProcessor`` intersects ``allowed_entity_ids`` across
     validators and records each ``DeniedEntity`` — with its reason — on the
-    corresponding ``BatchValidatorDecision`` so the final response can
+    corresponding ``BulkValidatorDecision`` so the final response can
     surface *why* each ID was filtered out.
     """
 
     allowed_entity_ids: list[str]
     denied_entities: list[DeniedEntity]
 
 
-class BatchActionValidator(ABC):
+class BulkActionValidator(ABC):
     @classmethod
     @abstractmethod
     def name(cls) -> str:
-        """Stable identifier used in ``BatchValidatorDecision.validator_name``.
+        """Stable identifier used in ``BulkValidatorDecision.validator_name``.
 
         Chosen by the implementation so logs and partial-success responses can
         attribute denials to a specific validator independently of the Python
@@ -42,9 +42,9 @@ class name.
 
     @abstractmethod
     async def validate(
-        self, action: BaseBatchAction[Any], meta: BaseActionTriggerMeta
-    ) -> BatchValidationResult:
-        """Validate the batch action and return per-entity permission results.
+        self, action: BaseBulkAction[Any], meta: BaseActionTriggerMeta
+    ) -> BulkValidationResult:
+        """Validate the bulk action and return per-entity permission results.
 
         Implementations must classify every ID in ``action.entity_ids`` as
         either allowed or denied. Validators that cannot make a decision for
diff --git a/src/ai/backend/manager/actions/validators/rbac/bulk.py b/src/ai/backend/manager/actions/validators/rbac/bulk.py
@@ -1,17 +1,17 @@
 from typing import Any, override
 
 from ai.backend.manager.actions.action import BaseActionTriggerMeta
-from ai.backend.manager.actions.action.batch import BaseBatchAction
-from ai.backend.manager.actions.validator.batch import (
-    BatchActionValidator,
-    BatchValidationResult,
+from ai.backend.manager.actions.action.bulk import BaseBulkAction
+from ai.backend.manager.actions.validator.bulk import (
+    BulkActionValidator,
+    BulkValidationResult,
 )
 from ai.backend.manager.repositories.permission_controller.repository import (
     PermissionControllerRepository,
 )
 
 
-class BatchActionRBACValidator(BatchActionValidator):
+class BulkActionRBACValidator(BulkActionValidator):
     def __init__(
         self,
         repository: PermissionControllerRepository,
@@ -25,11 +25,11 @@ def name(cls) -> str:
 
     @override
     async def validate(
-        self, action: BaseBatchAction[Any], meta: BaseActionTriggerMeta
-    ) -> BatchValidationResult:
-        # TODO: wire this to PermissionControllerRepository.check_batch_permission_with_scope_chain().
+        self, action: BaseBulkAction[Any], meta: BaseActionTriggerMeta
+    ) -> BulkValidationResult:
+        # TODO: wire this to PermissionControllerRepository.check_bulk_permission_with_scope_chain().
         # Until then, every entity is treated as allowed so legacy behavior is preserved.
-        return BatchValidationResult(
+        return BulkValidationResult(
             allowed_entity_ids=list(action.entity_ids),
             denied_entities=[],
         )
diff --git a/tests/unit/manager/actions/test_bulk_processor.py b/tests/unit/manager/actions/test_bulk_processor.py

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		-Add batch RBAC filtering infrastructure so `BatchActionProcessor` can narrow actions per-entity and report per-validator decisions.
	`1`	+Add bulk RBAC filtering infrastructure so `BulkActionProcessor` can narrow actions per-entity and report per-validator decisions.