Add batch deletion to Experiments, Feature Flags, and Segments

packages/backend/CLAUDE.md

@@ -83,10 +83,10 @@ Segment inclusion/exclusion for **feature flags** is precomputed and stored flat
 
 - **`FeatureFlagPrecomputedSegment` entity** (`src/api/models/FeatureFlagPrecomputedSegment.ts`) — one row per feature flag, columns: `featureFlagId` (PK), `inclusionIds: text[]`, `exclusionIds: text[]`. FK to `feature_flag` with `onDelete: CASCADE`.
 - **`FeatureFlagPrecomputedSegmentService`** (`src/api/services/FeatureFlagPrecomputedSegmentService.ts`) — owns all computation and cache logic:
-  - `recomputeForFlag(flagId)` — flattens all enabled inclusion/exclusion segments (recursive sub-segments) into flat ID arrays and upserts the row. This is the only method that `await`s — callers on write paths never call it directly.
+  - `recomputeForFlag(flagId)` — flattens all enabled inclusion/exclusion segments (recursive sub-segments) into flat ID arrays and upserts the row. Imports and batch segment deletion await this method directly.
   - `scheduleRecomputeForFlags(flagIds[])` — fire-and-forget recompute for a known set of flags (swallows/logs errors). The flag-side counterpart to `scheduleRecomputeForSegment`.
   - `scheduleRecomputeForSegment(segmentId)` — fire-and-forget; finds all flags referencing a segment (and its parents) and recomputes each.
-  - `withRecompute(logger, resolveAffectedFlagIds, work)` — **the wrapper all top-level write methods use.** Resolves affected flag IDs *before* `work`, runs `work` (which must own/commit its own transaction), then fires a fire-and-forget recompute *after* commit. Keeps mutation + recompute in one call so a refactor can't drop the recompute. `work` is never blocked on the recompute.
+  - `withRecompute(logger, resolveAffectedFlagIds, work)` — **the wrapper for background recomputation on write paths.** Resolves affected flag IDs *before* `work`, runs `work` (which must own/commit its own transaction), then fires a fire-and-forget recompute *after* commit. Keeps mutation + recompute in one call so a refactor can't drop the recompute. `work` is never blocked on the recompute.
   - `getAffectedFlagIds(segmentId)` — public helper that returns flag IDs affected by a given segment (used as the `resolveAffectedFlagIds` for segment deletes).
   - `getPrecomputedSets(flagIds[])` — cache-wrapped batch fetch, returns a `Map<flagId, FeatureFlagPrecomputedSegment>`.
   - `backfillMissingFlags(logger)` — called at startup; computes rows only for flags that have none yet (no-op once all flags are populated).
@@ -105,14 +105,14 @@ Segment inclusion/exclusion for **feature flags** is precomputed and stored flat
 | Private list added to a shared segment | `SegmentService.addList` → `scheduleRecomputeForSegment` |
 | Private list removed from a shared segment | `SegmentService.deleteList` → `scheduleRecomputeForSegment` |
 | Segment members/structure updated | `SegmentService.addSegmentDataWithPipeline` → `scheduleRecomputeForSegment` |
-| Segment deleted entirely | `SegmentService.deleteSegment` → `withRecompute` (collects affected flag IDs **before** the delete, recomputes **after** commit) |
+| Segment deleted entirely | `SegmentService.deleteSegment` → `withRecompute` for single deletion; batch deletion collects affected flag IDs after the target lock and **before** deletion, then awaits recomputation **after** commit |
 | Server startup | `app.ts` → `backfillMissingFlags` — backfills any flag with no row |
 
-All recomputes triggered from write paths are **fire-and-forget** — no request handler (flag-side or segment-side) ever blocks on a recompute. The `import*` paths are the one exception: they `await recomputeForFlag` so "import complete" means the rows are ready.
+Ordinary write paths use **fire-and-forget** recomputation. The `import*` paths await `recomputeForFlag` so "import complete" means the rows are ready. Batch segment deletion also awaits post-commit recomputation for both flags and experiments before processing the next segment. `SegmentService.deleteSegment` selects this awaited branch when supplied with the batch transaction executor; ordinary callers retain background recomputation.
 
 ### Key invariant
 
-The `feature_flag_precomputed_segment` row must always be recomputed **after** the structural change commits, so the flat arrays reflect the new state. For deletions specifically, affected flag IDs must be collected **before** the delete because the join table records are gone afterward. Both halves of this invariant are enforced by `withRecompute` (resolve-before → work → recompute-after), so top-level write methods get the ordering for free rather than hand-rolling it.
+The `feature_flag_precomputed_segment` row must always be recomputed **after** the structural change commits, so the flat arrays reflect the new state. For deletions specifically, affected flag IDs must be collected **before** the delete because the join table records are gone afterward. `withRecompute` enforces this ordering for background recomputation. The batch branch collects owners inside the supplied transaction, after the target lock is held, and waits for all post-commit updates to settle before propagating any failure.
 
 ## Precomputed Segment Lists (Experiments)
 
@@ -144,10 +144,10 @@ Experiment join tables (`ExperimentSegmentInclusion` / `ExperimentSegmentExclusi
 | Experiment lists imported | `ExperimentService.importExperimentLists` → `await recomputeForExperiment` after the import transaction commits |
 | Experiment context changed (deletes all its lists) | `ExperimentService.updateExperimentInDB` → `scheduleRecomputeForExperiments` after commit (recomputes to empty; `deleteAllListsFromExperiment` deletes the private segments directly, so the precomputed row would otherwise keep stale IDs). When a caller owns the transaction (`MoocletExperimentService.syncUpdate` / `syncUpdateWithMoocletAlgorithmTransition`), those methods recompute after their own commit — mirrors the flag side's `updateFeatureFlagInDB` → `withRecompute` |
 | Shared segment members/structure changed | `SegmentService.addList` / `deleteList` / `addSegmentDataWithPipeline` → `scheduleRecomputeForSegment` for **both** the flag and experiment services |
-| Segment deleted entirely | `SegmentService.deleteSegment` → collects affected experiment IDs **before** the delete, recomputes **after** commit (flags use `withRecompute` in the same method) |
+| Segment deleted entirely | `SegmentService.deleteSegment` → collects affected experiment IDs **before** deletion and recomputes **after** commit; single deletion schedules background work, while batch deletion collects owners after the target lock and awaits recomputation |
 | Server startup | `app.ts` → `backfillExperimentPrecomputedSegments` (guarded by `.catch` — a missing table never crashes startup) |
 
-Same invariant as feature flags: recompute **after** the change commits; for deletes, collect affected experiment IDs **before**. All write-path recomputes are fire-and-forget except the `create` / import / Mooclet paths, which `await` so "done" means the row is ready.
+Same invariant as feature flags: recompute **after** the change commits; for deletes, collect affected experiment IDs **before**. Write-path recomputes are fire-and-forget except the `create` / import / Mooclet paths and batch segment deletion, which await recomputation. A batch finishes each segment's post-commit updates before deleting the next segment.
 
 ### INCLUDE_ALL semantics (resolved)
 

packages/backend/src/api/controllers/ExperimentController.ts

@@ -1,3 +1,7 @@
+import { BatchDeleteResult } from 'upgrade_types';
+import { Inject } from 'typedi';
+import { BatchDeleteService } from '../services/BatchDeleteService';
+import { BatchEntityIdsValidator } from './validators/BatchEntityIdsValidator';
 import {
   Body,
   Get,
@@ -664,9 +668,43 @@ export class ExperimentController {
     public moocletExperimentService: MoocletExperimentService,
     public moocletRewardService: MoocletRewardsService,
     public importExportService: ImportExportService,
-    public cacheService: CacheService
+    public cacheService: CacheService,
+    @Inject(() => BatchDeleteService) private batchDeleteService: BatchDeleteService
   ) {}
 
+  /**
+   * @swagger
+   * /experiments/batch-delete:
+   *   post:
+   *     summary: Delete the selected experiments
+   *     description: Deletes selected experiments sequentially regardless of state, skipping missing items. Execution failures stop the remaining items. Returns one result per ID.
+   *     tags:
+   *       - Experiments
+   *     parameters:
+   *       - in: body
+   *         name: selection
+   *         required: true
+   *         schema:
+   *           $ref: '#/definitions/BatchEntityIdsRequest'
+   *     responses:
+   *       '200':
+   *         description: Per-ID deletion outcomes, including failures and items not attempted.
+   *         schema:
+   *           $ref: '#/definitions/BatchDeleteResult'
+   *       '400':
+   *         description: Expected a nonempty array of unique UUIDs.
+   *       '401':
+   *         description: AuthorizationRequiredError
+   */
+  @Post('/batch-delete')
+  public batchDelete(
+    @Body({ validate: true }) { ids }: BatchEntityIdsValidator,
+    @CurrentUser() currentUser: UserDTO,
+    @Req() request: AppRequest
+  ): Promise<BatchDeleteResult> {
+    return this.batchDeleteService.delete('experiments', ids, currentUser, request.logger);
+  }
+
   /**
    * @swagger
    * /experiments/names:

packages/backend/src/api/controllers/FeatureFlagController.ts

@@ -1,3 +1,7 @@
+import { BatchDeleteResult } from 'upgrade_types';
+import { Inject } from 'typedi';
+import { BatchDeleteService } from '../services/BatchDeleteService';
+import { BatchEntityIdsValidator } from './validators/BatchEntityIdsValidator';
 import {
   JsonController,
   Authorized,
@@ -154,7 +158,44 @@ interface FeatureFlagsPaginationInfo extends PaginationResponse {
 @Authorized()
 @JsonController('/flags')
 export class FeatureFlagsController {
-  constructor(public featureFlagService: FeatureFlagService, public experimentUserService: ExperimentUserService) {}
+  constructor(
+    public featureFlagService: FeatureFlagService,
+    public experimentUserService: ExperimentUserService,
+    @Inject(() => BatchDeleteService) private batchDeleteService: BatchDeleteService
+  ) {}
+
+  /**
+   * @swagger
+   * /flags/batch-delete:
+   *   post:
+   *     summary: Delete the selected flags
+   *     description: Deletes selected feature flags sequentially regardless of status, skipping missing items. Execution failures stop the remaining items. Returns one result per ID.
+   *     tags:
+   *       - Feature Flags
+   *     parameters:
+   *       - in: body
+   *         name: selection
+   *         required: true
+   *         schema:
+   *           $ref: '#/definitions/BatchEntityIdsRequest'
+   *     responses:
+   *       '200':
+   *         description: Per-ID deletion outcomes, including failures and items not attempted.
+   *         schema:
+   *           $ref: '#/definitions/BatchDeleteResult'
+   *       '400':
+   *         description: Expected a nonempty array of unique UUIDs.
+   *       '401':
+   *         description: AuthorizationRequiredError
+   */
+  @Post('/batch-delete')
+  public batchDelete(
+    @Body({ validate: true }) { ids }: BatchEntityIdsValidator,
+    @CurrentUser() currentUser: UserDTO,
+    @Req() request: AppRequest
+  ): Promise<BatchDeleteResult> {
+    return this.batchDeleteService.delete('flags', ids, currentUser, request.logger);
+  }
 
   /**
    * @swagger

packages/backend/src/api/controllers/SegmentController.ts

@@ -1,5 +1,11 @@
+import { UserDTO } from '../DTO/UserDTO';
+import { BatchDeleteResult } from 'upgrade_types';
+import { Inject } from 'typedi';
+import { BatchDeleteService } from '../services/BatchDeleteService';
+import { BatchEntityIdsValidator } from './validators/BatchEntityIdsValidator';
 import {
   JsonController,
+  CurrentUser,
   Get,
   Delete,
   Authorized,
@@ -49,6 +55,38 @@ interface SegmentPaginationInfo extends PaginationResponse {
 /**
  * @swagger
  * definitions:
+ *   BatchDeleteItemResult:
+ *     type: object
+ *     required: [id, outcome]
+ *     properties:
+ *       id:
+ *         type: string
+ *         format: uuid
+ *       outcome:
+ *         type: string
+ *         enum: [deleted, not_found, failed, unknown, not_attempted]
+ *       reasonCode:
+ *         type: string
+ *         enum: [not_found, delete_failed, lock_timeout, external_sync_failed, outcome_unknown, post_delete_failed]
+ *   BatchDeleteResult:
+ *     type: object
+ *     required: [results]
+ *     properties:
+ *       results:
+ *         type: array
+ *         items:
+ *           $ref: '#/definitions/BatchDeleteItemResult'
+ *   BatchEntityIdsRequest:
+ *     type: object
+ *     required: [ids]
+ *     properties:
+ *       ids:
+ *         type: array
+ *         minItems: 1
+ *         uniqueItems: true
+ *         items:
+ *           type: string
+ *           format: uuid
  *   Segment:
  *     required:
  *       - name
@@ -233,7 +271,43 @@ interface SegmentPaginationInfo extends PaginationResponse {
 @Authorized()
 @JsonController('/segments')
 export class SegmentController {
-  constructor(public segmentService: SegmentService) {}
+  constructor(
+    public segmentService: SegmentService,
+    @Inject(() => BatchDeleteService) private batchDeleteService: BatchDeleteService
+  ) {}
+
+  /**
+   * @swagger
+   * /segments/batch-delete:
+   *   post:
+   *     summary: Delete the selected segments
+   *     description: Deletes selected segments sequentially using the existing deletion workflow, skipping missing items. Execution failures stop the remaining items. Returns one result per ID.
+   *     tags:
+   *       - Segment
+   *     parameters:
+   *       - in: body
+   *         name: selection
+   *         required: true
+   *         schema:
+   *           $ref: '#/definitions/BatchEntityIdsRequest'
+   *     responses:
+   *       '200':
+   *         description: Per-ID deletion outcomes, including failures and items not attempted.
+   *         schema:
+   *           $ref: '#/definitions/BatchDeleteResult'
+   *       '400':
+   *         description: Expected a nonempty array of unique UUIDs.
+   *       '401':
+   *         description: AuthorizationRequiredError
+   */
+  @Post('/batch-delete')
+  public batchDelete(
+    @Body({ validate: true }) { ids }: BatchEntityIdsValidator,
+    @CurrentUser() currentUser: UserDTO,
+    @Req() request: AppRequest
+  ): Promise<BatchDeleteResult> {
+    return this.batchDeleteService.delete('segments', ids, currentUser, request.logger);
+  }
 
   /**
    * @swagger

packages/backend/src/api/controllers/validators/BatchEntityIdsValidator.ts

@@ -0,0 +1,26 @@
+import { ArrayNotEmpty, IsArray, IsUUID, registerDecorator } from 'class-validator';
+import { BatchEntityIdsRequest } from 'upgrade_types';
+
+const HasUniqueIds = () => (object: object, propertyName: string) => {
+  registerDecorator({
+    name: 'arrayUnique',
+    target: object.constructor,
+    propertyName,
+    options: { message: "All $property's elements must be unique" },
+    validator: {
+      validate(value: unknown) {
+        if (!Array.isArray(value)) return false;
+        const normalizedIds = value.map((id: unknown) => (typeof id === 'string' ? id.toLowerCase() : id));
+        return new Set(normalizedIds).size === value.length;
+      },
+    },
+  });
+};
+
+export class BatchEntityIdsValidator implements BatchEntityIdsRequest {
+  @IsArray()
+  @ArrayNotEmpty()
+  @HasUniqueIds()
+  @IsUUID('all', { each: true })
+  public ids: string[];
+}

packages/backend/src/api/repositories/DeletionRepository.ts

@@ -0,0 +1,25 @@
+import { EntityManager, Repository } from 'typeorm';
+import { BatchDeleteEntity } from 'upgrade_types';
+import { EntityRepository } from '../../typeorm-typedi-extensions';
+import { Experiment } from '../models/Experiment';
+import { FeatureFlag } from '../models/FeatureFlag';
+import { Segment } from '../models/Segment';
+import repositoryError from './utils/repositoryError';
+
+/** All reads and locks use the caller's deletion transaction, never the repository's default manager. */
+@EntityRepository()
+export class DeletionRepository extends Repository<DeletionRepository> {
+  public async findForDeletion(
+    entity: BatchDeleteEntity,
+    id: string,
+    manager: EntityManager
+  ): Promise<{ id: string } | null> {
+    const target = { experiments: Experiment, flags: FeatureFlag, segments: Segment }[entity];
+    return manager
+      .getRepository<{ id: string }>(target)
+      .findOne({ where: { id }, select: { id: true }, lock: { mode: 'pessimistic_write' } })
+      .catch((errorMsg: any) => {
+        throw repositoryError('DeletionRepository', 'findForDeletion', { entity, id }, errorMsg);
+      });
+  }
+}