@aneuhold/core-ts-db-lib 4.1.13 → 4.1.14

package/lib/services/workout/util/VolumePlanning/WorkoutVolumePlanningService.ts

@@ -7,13 +7,18 @@ import type {
 import type { WorkoutSessionExercise } from '../../../../documents/workout/WorkoutSessionExercise.js';
 import type WorkoutMesocyclePlanContext from '../../Mesocycle/WorkoutMesocyclePlanContext.js';
 import WorkoutSessionExerciseService from '../../SessionExercise/WorkoutSessionExerciseService.js';
-import WorkoutSFRService from '../SFR/WorkoutSFRService.js';
+
+/** An exercise eligible to receive additional sets during SFR-based distribution. */
+type SetAdditionCandidate = {
+  exerciseId: UUID;
+  sfr: number;
+  muscleGroupIndex: number;
+  previousSetCount: number;
+};
 
 /**
  * A service for handling volume planning operations across microcycles.
  *
- * SCOPE: Microcycle-level volume distribution (calculating set counts per exercise)
- *
  * RESPONSIBILITIES:
  * - Calculate set counts for exercises across a microcycle
  * - Apply progressive overload rules (baseline + historical adjustments)
@@ -26,14 +31,32 @@ import WorkoutSFRService from '../SFR/WorkoutSFRService.js';
  * - {@link WorkoutSessionExerciseService} - Used to calculate SFR and recovery recommendations
  */
 export default class WorkoutVolumePlanningService {
+  /**
+   * Controls the volume *progression rate* across accumulation microcycles.
+   *
+   * Both modes start at estimated MEV when historical volume data exists
+   * (falling back to 2 sets per exercise when no history is available).
+   *
+   * When `false` (default): legacy progression — adds 1 set per muscle group
+   * every `progressionInterval` microcycles from the MEV starting point.
+   *
+   * When `true`: MEV-to-MRV interpolation — linearly distributes sets from
+   * estimated MEV to estimated MRV across all accumulation microcycles.
+   *
+   * This flag exists to allow toggling between the two progression algorithms
+   * while the MEV-to-MRV approach is validated in practice. Once confidence is
+   * established, the flag and legacy path should be removed.
+   */
+  static USE_VOLUME_LANDMARK_PROGRESSION = false;
+
   private static readonly MAX_SETS_PER_EXERCISE = 8;
   private static readonly MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION = 10;
 
   /** Minimum average RSM required for a mesocycle to count toward MEV estimation. */
   private static readonly MEV_RSM_THRESHOLD = 4;
 
-  /** Default estimated MEV when no qualifying mesocycle history exists. */
-  private static readonly DEFAULT_MEV = 2;
+  /** Default estimated MEV when no qualifying mesocycle history exists. Per-exercise value. */
+  private static readonly DEFAULT_MEV_PER_EXERCISE = 2;
 
   /** Minimum average performance score (or recovery presence) to count a mesocycle toward MRV estimation. */
   private static readonly MRV_PERFORMANCE_THRESHOLD = 2.5;
@@ -41,20 +64,8 @@ export default class WorkoutVolumePlanningService {
   /** Extra sets added above the historical peak when no stressed mesocycles exist, to estimate MRV. */
   private static readonly MRV_HEADROOM = 2;
 
-  /** Default estimated MRV when no mesocycle history exists at all. */
-  private static readonly DEFAULT_MRV = 8;
-
-  /** RSM bracket upper bound for "below MEV" proximity (0 to this value inclusive). */
-  private static readonly MEV_PROXIMITY_BELOW_THRESHOLD = 3;
-
-  /** RSM bracket upper bound for "at MEV" proximity (above BELOW threshold up to this value inclusive). */
-  private static readonly MEV_PROXIMITY_AT_THRESHOLD = 6;
-
-  /** Recommended set adjustment when volume is below MEV. */
-  private static readonly MEV_BELOW_SET_ADJUSTMENT = 3;
-
-  /** Recommended set adjustment when volume is above MEV. */
-  private static readonly MEV_ABOVE_SET_ADJUSTMENT = -2;
+  /** Default estimated MRV when no mesocycle history exists at all. Per-exercise value. */
+  private static readonly DEFAULT_MRV_PER_EXERCISE = 8;
 
   /** Maximum sets that can be added to a single exercise in one progression step. */
   private static readonly MAX_SET_ADDITION_PER_EXERCISE = 2;
@@ -94,17 +105,6 @@ export default class WorkoutVolumePlanningService {
       }
     });
 
-    // Apply MEV proximity adjustment when generating the second microcycle (index 1)
-    // after the first microcycle is complete with RSM data. Only applies when volume
-    // data (volumeCTOs) was provided to the context.
-    if (
-      microcycleIndex === 1 &&
-      !isDeloadMicrocycle &&
-      context.muscleGroupToVolumeLandmarkMap.size > 0
-    ) {
-      this.applyMevProximityAdjustments(context, exerciseIdToSetCount);
-    }
-
     return { exerciseIdToSetCount, recoveryExerciseIds };
   }
 
@@ -133,7 +133,7 @@ export default class WorkoutVolumePlanningService {
     } else if (mesocycleHistory.length > 0) {
       estimatedMev = Math.min(...mesocycleHistory.map((m) => m.startingSetCount));
     } else {
-      estimatedMev = this.DEFAULT_MEV;
+      estimatedMev = this.DEFAULT_MEV_PER_EXERCISE;
     }
 
     // Estimated MRV
@@ -151,12 +151,9 @@ export default class WorkoutVolumePlanningService {
     } else if (mesocycleHistory.length > 0) {
       estimatedMrv = Math.max(...mesocycleHistory.map((m) => m.peakSetCount)) + this.MRV_HEADROOM;
     } else {
-      estimatedMrv = this.DEFAULT_MRV;
+      estimatedMrv = this.DEFAULT_MRV_PER_EXERCISE;
     }
 
-    // Hard cap MRV at 10 (MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION)
-    estimatedMrv = Math.min(estimatedMrv, this.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION);
-
     // Ensure MRV > MEV
     if (estimatedMrv <= estimatedMev) {
       estimatedMrv = estimatedMev + 1;
@@ -167,117 +164,18 @@ export default class WorkoutVolumePlanningService {
     return { estimatedMev, estimatedMrv, estimatedMav, mesocycleCount: mesocycleHistory.length };
   }
 
-  /**
-   * Evaluates MEV (Minimum Effective Volume) proximity for a muscle group based on
-   * RSM scores from the first microcycle. Called when generating the second microcycle to adjust
-   * the volume baseline.
-   *
-   * Returns `null` when the first microcycle is incomplete or has no RSM data for the muscle group.
-   *
-   * @param context The mesocycle planning context containing microcycle/session/exercise data.
-   * @param muscleGroupId The muscle group to evaluate.
-   */
-  static evaluateMevProximity(
-    context: WorkoutMesocyclePlanContext,
-    muscleGroupId: UUID
-  ): {
-    /** 'below' = RSM 0-3, 'at' = RSM 4-6, 'above' = RSM 7-9 */
-    proximity: 'below' | 'at' | 'above';
-
-    /**
-     * Recommended total set adjustment for this muscle group.
-     * Positive = add sets, negative = remove sets, 0 = no change.
-     * Range: -2 to +3
-     */
-    recommendedSetAdjustment: number;
-
-    /** The average RSM across session exercises targeting this muscle group. */
-    averageRsm: number;
-  } | null {
-    const firstMicrocycle = context.microcyclesInOrder[0];
-    if (!firstMicrocycle) return null;
-
-    // Check the first microcycle is complete
-    const lastSessionId = firstMicrocycle.sessionOrder[firstMicrocycle.sessionOrder.length - 1];
-    if (!context.sessionMap.get(lastSessionId)?.complete) return null;
-
-    // Collect RSM totals from session exercises that target this muscle group
-    const rsmTotals: number[] = [];
-    for (const sessionId of firstMicrocycle.sessionOrder) {
-      const session = context.sessionMap.get(sessionId);
-      if (!session) continue;
-      for (const seId of session.sessionExerciseOrder) {
-        const se = context.sessionExerciseMap.get(seId);
-        if (!se) continue;
-        const exercise = context.exerciseMap.get(se.workoutExerciseId);
-        if (!exercise?.primaryMuscleGroups.includes(muscleGroupId)) continue;
-
-        const rsmTotal = WorkoutSFRService.getRsmTotal(se.rsm);
-        if (rsmTotal !== null) {
-          rsmTotals.push(rsmTotal);
-        }
-      }
-    }
-
-    if (rsmTotals.length === 0) return null;
-
-    const averageRsm = rsmTotals.reduce((sum, val) => sum + val, 0) / rsmTotals.length;
-    const bracket = Math.floor(averageRsm);
-
-    if (bracket <= this.MEV_PROXIMITY_BELOW_THRESHOLD) {
-      return {
-        proximity: 'below',
-        recommendedSetAdjustment: this.MEV_BELOW_SET_ADJUSTMENT,
-        averageRsm
-      };
-    } else if (bracket <= this.MEV_PROXIMITY_AT_THRESHOLD) {
-      return { proximity: 'at', recommendedSetAdjustment: 0, averageRsm };
-    }
-    return {
-      proximity: 'above',
-      recommendedSetAdjustment: this.MEV_ABOVE_SET_ADJUSTMENT,
-      averageRsm
-    };
-  }
-
-  /**
-   * Applies MEV proximity adjustments based on RSM data from the first microcycle.
-   * Adjusts set counts per muscle group when the first microcycle indicates volume
-   * was below or above MEV.
-   */
-  private static applyMevProximityAdjustments(
-    context: WorkoutMesocyclePlanContext,
-    exerciseIdToSetCount: Map<UUID, number>
-  ): void {
-    if (!context.muscleGroupToExerciseCTOsMap) return;
-
-    for (const [muscleGroupId, muscleGroupExerciseCTOs] of context.muscleGroupToExerciseCTOsMap) {
-      const mevResult = this.evaluateMevProximity(context, muscleGroupId);
-      if (!mevResult || mevResult.recommendedSetAdjustment === 0) continue;
-
-      // Distribute the adjustment evenly across exercises in this muscle group
-      const exerciseCount = muscleGroupExerciseCTOs.length;
-      const adjustmentPerExercise = Math.floor(mevResult.recommendedSetAdjustment / exerciseCount);
-      const adjustmentRemainder = mevResult.recommendedSetAdjustment % exerciseCount;
-
-      muscleGroupExerciseCTOs.forEach((cto, index) => {
-        const currentSets = exerciseIdToSetCount.get(cto._id) ?? 2;
-        const extra =
-          index < Math.abs(adjustmentRemainder) ? Math.sign(mevResult.recommendedSetAdjustment) : 0;
-        const newSets = Math.max(
-          1,
-          Math.min(currentSets + adjustmentPerExercise + extra, this.MAX_SETS_PER_EXERCISE)
-        );
-        exerciseIdToSetCount.set(cto._id, newSets);
-      });
-    }
-  }
-
   /**
    * Calculates the set count for each exercise in a particular muscle group for this microcycle.
    *
-   * If there is no previous microcycle data for the muscle group, this falls back to
-   * the baseline progression rules.
+   * Pipeline:
+   * 1. **Volume targets** — Determine start/end volume from landmarks or defaults
+   * 2. **Baseline** — Calculate default set counts from progression rules
+   * 3. **Resolve history** — Find the most recent session exercise data for each exercise
+   * 4. **Apply history** — Override baselines with historical set counts (or MAV for recovery returns)
+   * 5. **Evaluate SFR** — Determine recovery exercises and candidates for set additions
+   * 6. **Distribute sets** — Allocate added sets to candidates by SFR quality
+   *
+   * Falls back to baseline when no previous microcycle data exists.
    */
   private static calculateSetCountForEachExerciseInMuscleGroup(
     context: WorkoutMesocyclePlanContext,
@@ -288,22 +186,38 @@ export default class WorkoutVolumePlanningService {
     const exerciseIdToSetCount = new Map<UUID, number>();
     const recoveryExerciseIds = new Set<UUID>();
     const sessionIndexToExerciseIds = new Map<number, UUID[]>();
-
     const { progressionInterval } = context;
 
-    // 1. Calculate baselines for all exercises in muscle group
+    // 1. Look up volume landmarks and compute volume targets
+    const primaryMuscleGroupId = muscleGroupExerciseCTOs[0]?.primaryMuscleGroups[0];
+    const volumeLandmark = primaryMuscleGroupId
+      ? context.muscleGroupToVolumeLandmarkMap.get(primaryMuscleGroupId)
+      : undefined;
+
+    const { startVolume, endVolume } = this.getVolumeTargetsForMuscleGroup(
+      volumeLandmark,
+      muscleGroupExerciseCTOs.length,
+      progressionInterval
+    );
+
+    // 2. Calculate baseline set counts for all exercises in the muscle group
+    const baselineCounts = this.calculateBaselineSetCounts(
+      microcycleIndex,
+      context.accumulationMicrocycleCount,
+      muscleGroupExerciseCTOs.length,
+      startVolume,
+      endVolume,
+      isDeloadMicrocycle,
+      progressionInterval
+    );
+
+    // 3. Assign baselines and build session-to-exercise index
     muscleGroupExerciseCTOs.forEach((cto, index) => {
-      const baseline = this.calculateBaselineSetCount(
-        microcycleIndex,
-        muscleGroupExerciseCTOs.length,
-        index,
-        isDeloadMicrocycle,
-        progressionInterval
+      exerciseIdToSetCount.set(
+        cto._id,
+        Math.min(baselineCounts[index], this.MAX_SETS_PER_EXERCISE)
       );
-      exerciseIdToSetCount.set(cto._id, Math.min(baseline, this.MAX_SETS_PER_EXERCISE));
 
-      // Build out the map for session indices to the array of exercise IDs as it pertains to this
-      // muscle group.
       if (!context.exerciseIdToSessionIndex) return;
       const exerciseSessionIndex = context.exerciseIdToSessionIndex.get(cto._id);
       if (exerciseSessionIndex === undefined) return;
@@ -313,17 +227,204 @@ export default class WorkoutVolumePlanningService {
       sessionIndexToExerciseIds.set(exerciseSessionIndex, existingExerciseIdsForSession);
     });
 
-    // 2. Resolve historical performance data
-    // Return if no previous microcycle
+    // 4. Resolve historical data — returns null if no usable history exists
+    const exerciseIds = new Set(muscleGroupExerciseCTOs.map((cto) => cto._id));
+    const historicalData = this.resolveHistoricalExerciseData(
+      context,
+      microcycleIndex,
+      exerciseIds
+    );
+    if (!historicalData) return { exerciseIdToSetCount, recoveryExerciseIds };
+
+    // 5. Apply historical set counts (overrides baselines)
+    this.applyHistoricalSetCounts(
+      muscleGroupExerciseCTOs,
+      historicalData.exerciseIdToPrevSessionExercise,
+      historicalData.exercisesThatWerePreviouslyInRecovery,
+      exerciseIdToSetCount,
+      isDeloadMicrocycle,
+      volumeLandmark
+    );
+
+    // Deload microcycles and zero-progression cycles (Resensitization) skip SFR-based set additions
+    if (isDeloadMicrocycle || progressionInterval === 0) {
+      return { exerciseIdToSetCount, recoveryExerciseIds };
+    }
+
+    // 6. Evaluate SFR recommendations (per-exercise SFR + recovery detection)
+    const { totalSetsToAdd, candidates } = this.evaluateSfrRecommendations(
+      context,
+      muscleGroupExerciseCTOs,
+      historicalData.exerciseIdToPrevSessionExercise,
+      historicalData.exercisesThatWerePreviouslyInRecovery,
+      exerciseIdToSetCount,
+      recoveryExerciseIds,
+      sessionIndexToExerciseIds
+    );
+
+    if (totalSetsToAdd === 0 || candidates.length === 0) {
+      return { exerciseIdToSetCount, recoveryExerciseIds };
+    }
+
+    // 7. Distribute added sets to candidates by SFR quality
+    this.distributeSetsToExercises(
+      candidates,
+      totalSetsToAdd,
+      exerciseIdToSetCount,
+      context.exerciseIdToSessionIndex,
+      sessionIndexToExerciseIds
+    );
+
+    return { exerciseIdToSetCount, recoveryExerciseIds };
+  }
+
+  /**
+   * Determines the start and end volume targets for a muscle group based on
+   * historical volume landmarks and cycle type.
+   *
+   * @param volumeLandmark Volume landmark estimate from historical data, if available.
+   * @param exerciseCount Number of exercises in the muscle group.
+   * @param progressionInterval Cycle-type progression interval (1=MuscleGain, 2=Cut, 0=Resensitization).
+   */
+  private static getVolumeTargetsForMuscleGroup(
+    volumeLandmark: WorkoutVolumeLandmarkEstimate | undefined,
+    exerciseCount: number,
+    progressionInterval: number
+  ): { startVolume: number; endVolume: number } {
+    // Resensitization (interval=0): flat at estimated MEV (or default when no history)
+    if (progressionInterval === 0) {
+      const flatVolume =
+        volumeLandmark && volumeLandmark.mesocycleCount > 0
+          ? volumeLandmark.estimatedMev
+          : this.DEFAULT_MEV_PER_EXERCISE * exerciseCount;
+      return { startVolume: flatVolume, endVolume: flatVolume };
+    }
+
+    // With historical volume landmarks
+    if (volumeLandmark && volumeLandmark.mesocycleCount > 0) {
+      const startVolume = volumeLandmark.estimatedMev;
+      // Cut: progress to MAV (midpoint), not MRV
+      let endVolume =
+        progressionInterval === 2 ? volumeLandmark.estimatedMav : volumeLandmark.estimatedMrv;
+
+      if (endVolume <= startVolume) {
+        endVolume = startVolume + 1;
+      }
+
+      return { startVolume, endVolume };
+    }
+
+    // No history: use per-exercise defaults
+    const startVolume = this.DEFAULT_MEV_PER_EXERCISE * exerciseCount;
+    const mrvTotal = this.DEFAULT_MRV_PER_EXERCISE * exerciseCount;
+
+    // Cut: target MAV (midpoint), not MRV
+    const endVolume =
+      progressionInterval === 2 ? Math.ceil((startVolume + mrvTotal) / 2) : mrvTotal;
+
+    return { startVolume, endVolume };
+  }
+
+  /**
+   * Calculates the baseline set counts for all exercises in a muscle group for a given microcycle.
+   *
+   * When {@link USE_VOLUME_LANDMARK_PROGRESSION} is `false` (default), uses the legacy progression
+   * rate: +1 set per muscle group every `progressionInterval` microcycles from the starting volume.
+   *
+   * When `true`, linearly interpolates from `startVolume` to `endVolume` across accumulation
+   * microcycles.
+   *
+   * @param microcycleIndex The index of the current microcycle.
+   * @param accumulationMicrocycleCount Number of accumulation (non-deload) microcycles.
+   * @param exerciseCount Number of exercises in the muscle group.
+   * @param startVolume Total muscle-group volume at microcycle 0.
+   * @param endVolume Total muscle-group volume target at the last accumulation microcycle.
+   * @param isDeloadMicrocycle Whether this is a deload microcycle.
+   * @param progressionInterval Microcycles between each set addition (0 = no progression).
+   */
+  private static calculateBaselineSetCounts(
+    microcycleIndex: number,
+    accumulationMicrocycleCount: number,
+    exerciseCount: number,
+    startVolume: number,
+    endVolume: number,
+    isDeloadMicrocycle: boolean,
+    progressionInterval: number
+  ): number[] {
+    if (isDeloadMicrocycle) {
+      const lastAccumulationCounts = this.calculateBaselineSetCounts(
+        microcycleIndex - 1,
+        accumulationMicrocycleCount,
+        exerciseCount,
+        startVolume,
+        endVolume,
+        false,
+        progressionInterval
+      );
+      return lastAccumulationCounts.map((count) => Math.max(1, Math.floor(count / 2)));
+    }
+
+    let totalSets: number;
+
+    if (this.USE_VOLUME_LANDMARK_PROGRESSION) {
+      // Linear interpolation from startVolume to endVolume
+      if (accumulationMicrocycleCount <= 1) {
+        totalSets = startVolume;
+      } else {
+        totalSets = Math.round(
+          startVolume +
+            ((endVolume - startVolume) * microcycleIndex) / (accumulationMicrocycleCount - 1)
+        );
+      }
+    } else {
+      // Legacy progression: +1 set per muscle group per progressionInterval microcycles
+      const progressionSets =
+        progressionInterval === 0 ? 0 : Math.ceil(microcycleIndex / progressionInterval);
+      totalSets = startVolume + progressionSets;
+    }
+
+    return this.distributeEvenly(totalSets, exerciseCount);
+  }
+
+  /**
+   * Distributes a total evenly across N slots, with remainder going to earlier slots.
+   *
+   * @param total The total to distribute.
+   * @param slots The number of slots to distribute across.
+   */
+  private static distributeEvenly(total: number, slots: number): number[] {
+    const base = Math.floor(total / slots);
+    const remainder = total % slots;
+    return Array.from({ length: slots }, (_, i) => (i < remainder ? base + 1 : base));
+  }
+
+  /**
+   * Walks backward through completed microcycles to find the most recent non-recovery
+   * session exercise for each exercise in the muscle group.
+   *
+   * Returns `null` when no usable historical data exists (no previous microcycle, or
+   * previous microcycles are incomplete/have no matching exercises).
+   *
+   * @param context The mesocycle planning context.
+   * @param microcycleIndex The current microcycle index.
+   * @param exerciseIds The exercise IDs to search for.
+   */
+  private static resolveHistoricalExerciseData(
+    context: WorkoutMesocyclePlanContext,
+    microcycleIndex: number,
+    exerciseIds: Set<UUID>
+  ): {
+    exerciseIdToPrevSessionExercise: Map<UUID, WorkoutSessionExercise>;
+    exercisesThatWerePreviouslyInRecovery: Set<UUID>;
+  } | null {
     let previousMicrocycleIndex = microcycleIndex - 1;
     let previousMicrocycle = context.microcyclesInOrder[previousMicrocycleIndex];
-    if (!previousMicrocycle) return { exerciseIdToSetCount, recoveryExerciseIds };
+    if (!previousMicrocycle) return null;
 
-    // Map previous session exercises
-    const exerciseIds = new Set(muscleGroupExerciseCTOs.map((cto) => cto._id));
     const exerciseIdToPrevSessionExercise = new Map<UUID, WorkoutSessionExercise>();
     const foundExerciseIds = new Set<UUID>();
     const exercisesThatWerePreviouslyInRecovery = new Set<UUID>();
+
     // Loop through each previous microcycle until we find all exercises or run out of microcycles
     while (exerciseIdToPrevSessionExercise.size < exerciseIds.size && previousMicrocycle) {
       // Check if the previous microcycle is complete; if not, we cannot use its data
@@ -334,14 +435,12 @@ export default class WorkoutVolumePlanningService {
         break;
       }
 
-      // Start with session order
+      // Scan all session exercises in this microcycle for matching non-recovery exercises
       for (const sessionId of previousMicrocycle.sessionOrder) {
         const session = context.sessionMap.get(sessionId);
         if (!session) continue;
-        // Get the session exercises for this session
         for (const sessionExerciseId of session.sessionExerciseOrder) {
           const sessionExercise = context.sessionExerciseMap.get(sessionExerciseId);
-          // Map if in our muscle group && it isn't a recovery exercise
           if (
             sessionExercise &&
             exerciseIds.has(sessionExercise.workoutExerciseId) &&
@@ -350,91 +449,104 @@ export default class WorkoutVolumePlanningService {
           ) {
             exerciseIdToPrevSessionExercise.set(sessionExercise.workoutExerciseId, sessionExercise);
             foundExerciseIds.add(sessionExercise.workoutExerciseId);
+            // If we had to go back more than one microcycle, the exercise was in recovery
             if (previousMicrocycleIndex < microcycleIndex - 1) {
               exercisesThatWerePreviouslyInRecovery.add(sessionExercise.workoutExerciseId);
             }
           }
         }
       }
-      // Move to earlier microcycle
       previousMicrocycleIndex = previousMicrocycleIndex - 1;
       previousMicrocycle = context.microcyclesInOrder[previousMicrocycleIndex];
     }
-    if (exerciseIdToPrevSessionExercise.size === 0)
-      return { exerciseIdToSetCount, recoveryExerciseIds };
 
-    // Update baseline with historical set counts when available.
-    // For deload microcycles, halve the historical count (minimum 1 set). We don't use baseline
-    // because the user may have adjusted over the mesocycle in a way that the baseline is actually
-    // a higher set count than what would be calculated by halving the previous microcycle's sets.
-    //
-    // For exercises returning from recovery, use the estimated MAV from volume landmarks
-    // when available, instead of the pre-recovery historical count.
-    const primaryMuscleGroupId = muscleGroupExerciseCTOs[0]?.primaryMuscleGroups[0];
-    const volumeLandmark = primaryMuscleGroupId
-      ? context.muscleGroupToVolumeLandmarkMap.get(primaryMuscleGroupId)
-      : undefined;
+    if (exerciseIdToPrevSessionExercise.size === 0) return null;
+    return { exerciseIdToPrevSessionExercise, exercisesThatWerePreviouslyInRecovery };
+  }
+
+  /**
+   * Overrides baseline set counts with historical data from the previous microcycle.
+   *
+   * For exercises returning from recovery, distributes the estimated MAV from volume
+   * landmarks proportionally across exercises. For deload microcycles, halves the
+   * historical count (minimum 1 set).
+   *
+   * @param muscleGroupExerciseCTOs Exercises in this muscle group.
+   * @param exerciseIdToPrevSessionExercise Map from exercise ID to its previous session exercise.
+   * @param exercisesThatWerePreviouslyInRecovery Exercises returning from recovery.
+   * @param exerciseIdToSetCount Current set count assignments (mutated).
+   * @param isDeloadMicrocycle Whether this is a deload microcycle.
+   * @param volumeLandmark Volume landmark estimate for the primary muscle group, if available.
+   */
+  private static applyHistoricalSetCounts(
+    muscleGroupExerciseCTOs: WorkoutExerciseCTO[],
+    exerciseIdToPrevSessionExercise: Map<UUID, WorkoutSessionExercise>,
+    exercisesThatWerePreviouslyInRecovery: Set<UUID>,
+    exerciseIdToSetCount: Map<UUID, number>,
+    isDeloadMicrocycle: boolean,
+    volumeLandmark: WorkoutVolumeLandmarkEstimate | undefined
+  ): void {
+    // Pre-compute per-exercise MAV distribution for exercises returning from recovery.
+    // Uses floor-based even distribution (conservative) per the source material's guidance
+    // to err on the lighter side when returning from recovery.
+    const hasExerciseReturningFromRecovery = muscleGroupExerciseCTOs.some((cto) =>
+      exercisesThatWerePreviouslyInRecovery.has(cto._id)
+    );
+    const mavDistribution =
+      hasExerciseReturningFromRecovery && volumeLandmark
+        ? this.distributeEvenly(volumeLandmark.estimatedMav, muscleGroupExerciseCTOs.length)
+        : undefined;
 
-    muscleGroupExerciseCTOs.forEach((cto) => {
+    muscleGroupExerciseCTOs.forEach((cto, index) => {
       const previousSessionExercise = exerciseIdToPrevSessionExercise.get(cto._id);
-      if (previousSessionExercise) {
-        let setCount: number;
-
-        if (exercisesThatWerePreviouslyInRecovery.has(cto._id) && volumeLandmark) {
-          // Exercise is returning from recovery — resume at the estimated MAV
-          setCount = Math.min(volumeLandmark.estimatedMav, this.MAX_SETS_PER_EXERCISE);
-        } else {
-          setCount = Math.min(previousSessionExercise.setOrder.length, this.MAX_SETS_PER_EXERCISE);
-        }
+      if (!previousSessionExercise) return;
 
-        if (isDeloadMicrocycle) {
-          setCount = Math.max(1, Math.floor(setCount / 2));
-        }
-        exerciseIdToSetCount.set(cto._id, setCount);
+      let setCount: number;
+      if (exercisesThatWerePreviouslyInRecovery.has(cto._id) && mavDistribution) {
+        // Returning from recovery — resume at conservatively distributed MAV
+        setCount = Math.min(mavDistribution[index], this.MAX_SETS_PER_EXERCISE);
+      } else {
+        // Carry forward last microcycle's set count
+        setCount = Math.min(previousSessionExercise.setOrder.length, this.MAX_SETS_PER_EXERCISE);
       }
-    });
 
-    // Deload microcycles and zero-progression cycles (Resensitization) skip SFR-based set additions
-    if (isDeloadMicrocycle || progressionInterval === 0) {
-      return { exerciseIdToSetCount, recoveryExerciseIds };
-    }
-
-    /**
-     * Determines if the session for the given exercise is already capped for this muscle group.
-     */
-    function sessionIsCapped(exerciseId: UUID): boolean {
-      if (!context.exerciseIdToSessionIndex) {
-        throw new Error(
-          'WorkoutMesocyclePlanContext.exerciseIdToSessionIndex is not initialized. This should be set during mesocycle planning.'
-        );
+      if (isDeloadMicrocycle) {
+        // Deload: halve volume, minimum 1 set
+        setCount = Math.max(1, Math.floor(setCount / 2));
       }
-      const sessionIndex = context.exerciseIdToSessionIndex.get(exerciseId);
-      if (sessionIndex === undefined) return false;
-
-      const exerciseIdsInSession = sessionIndexToExerciseIds.get(sessionIndex);
-      if (!exerciseIdsInSession) return false;
-      let totalSetsInSession = 0;
-      exerciseIdsInSession.forEach((id) => {
-        // Use the sets from the previous microcycle's session exercise
-        totalSetsInSession += exerciseIdToPrevSessionExercise.get(id)?.setOrder.length || 0;
-      });
-      return (
-        totalSetsInSession >= WorkoutVolumePlanningService.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION
-      );
-    }
+      exerciseIdToSetCount.set(cto._id, setCount);
+    });
+  }
 
-    // 3. Determine sets to add and valid candidates
+  /**
+   * Evaluates each exercise's performance feedback to determine recovery exercises,
+   * set addition recommendations, and candidates for volume increases.
+   *
+   * @param context The mesocycle planning context.
+   * @param muscleGroupExerciseCTOs Exercises in this muscle group.
+   * @param exerciseIdToPrevSessionExercise Map from exercise ID to its previous session exercise.
+   * @param exercisesThatWerePreviouslyInRecovery Exercises returning from recovery.
+   * @param exerciseIdToSetCount Current set count assignments (mutated for recovery exercises).
+   * @param recoveryExerciseIds Set of exercise IDs flagged for recovery (mutated).
+   * @param sessionIndexToExerciseIds Map from session index to exercise IDs in that session.
+   */
+  private static evaluateSfrRecommendations(
+    context: WorkoutMesocyclePlanContext,
+    muscleGroupExerciseCTOs: WorkoutExerciseCTO[],
+    exerciseIdToPrevSessionExercise: Map<UUID, WorkoutSessionExercise>,
+    exercisesThatWerePreviouslyInRecovery: Set<UUID>,
+    exerciseIdToSetCount: Map<UUID, number>,
+    recoveryExerciseIds: Set<UUID>,
+    sessionIndexToExerciseIds: Map<number, UUID[]>
+  ): { totalSetsToAdd: number; candidates: SetAdditionCandidate[] } {
     let totalSetsToAdd = 0;
-    const candidates: {
-      exerciseId: UUID;
-      sfr: number;
-      muscleGroupIndex: number;
-      previousSetCount: number;
-    }[] = [];
+
+    const candidates: SetAdditionCandidate[] = [];
     muscleGroupExerciseCTOs.forEach((cto, muscleGroupIndex) => {
       const previousSessionExercise = exerciseIdToPrevSessionExercise.get(cto._id);
       if (!previousSessionExercise) return;
 
+      // Get SFR-based recommendation: positive = add sets, 0 = maintain, -1 = recovery needed
       let recommendation: number | null;
       if (!exercisesThatWerePreviouslyInRecovery.has(cto._id)) {
         recommendation =
@@ -442,26 +554,29 @@ export default class WorkoutVolumePlanningService {
             previousSessionExercise
           );
       } else {
-        // If previously in recovery, do not recommend adding sets this microcycle. Also, this is
-        // the only thing we are overriding. We still want to use the historical data for
-        // SFR calculations, even though that one was the one that triggered a recovery session.
-        // This should make it so that it is less likely to have sets added to it.
+        // Returning from recovery — don't add sets yet, but still use SFR for candidate ranking
         recommendation = 0;
       }
 
       if (recommendation === -1) {
+        // Recovery needed: halve sets and flag as recovery exercise
         recoveryExerciseIds.add(cto._id);
-        // Cut sets in half (rounded down, minimum 1) for recovery
         const previousSetCount = previousSessionExercise.setOrder.length;
         const recoverySets = Math.max(1, Math.floor(previousSetCount / 2));
         exerciseIdToSetCount.set(cto._id, recoverySets);
       } else if (recommendation !== null && recommendation >= 0) {
+        // Accumulate SFR-recommended additions into shared total
         totalSetsToAdd += recommendation;
 
-        // Consider as candidate if session is not already capped
+        // Only exercises below per-exercise cap and in uncapped sessions are candidates
         if (
           previousSessionExercise.setOrder.length < this.MAX_SETS_PER_EXERCISE &&
-          !sessionIsCapped(cto._id)
+          !this.sessionIsCapped(
+            cto._id,
+            context.exerciseIdToSessionIndex,
+            sessionIndexToExerciseIds,
+            exerciseIdToPrevSessionExercise
+          )
         ) {
           candidates.push({
             exerciseId: cto._id,
@@ -476,126 +591,152 @@ export default class WorkoutVolumePlanningService {
       }
     });
 
-    // Return if nothing to add or no candidates
-    if (totalSetsToAdd === 0 || candidates.length === 0) {
-      return { exerciseIdToSetCount, recoveryExerciseIds };
-    }
+    return { totalSetsToAdd, candidates };
+  }
 
-    // 4. Distribute added sets based on SFR quality
-    // Sort by SFR descending, then by muscleGroupIndex ascending (as tie-breaker)
+  /**
+   * Distributes added sets across candidate exercises, prioritizing higher SFR scores.
+   * Respects per-exercise, per-session, and per-addition caps.
+   *
+   * @param candidates Exercises eligible for set additions, with SFR scores.
+   * @param totalSetsToAdd Total sets recommended for addition (before capping).
+   * @param exerciseIdToSetCount Current set count assignments (mutated).
+   * @param exerciseIdToSessionIndex Map from exercise ID to its session index.
+   * @param sessionIndexToExerciseIds Map from session index to exercise IDs in that session.
+   */
+  private static distributeSetsToExercises(
+    candidates: SetAdditionCandidate[],
+    totalSetsToAdd: number,
+    exerciseIdToSetCount: Map<UUID, number>,
+    exerciseIdToSessionIndex: Map<UUID, number> | undefined,
+    sessionIndexToExerciseIds: Map<number, UUID[]>
+  ): void {
+    // Prioritize exercises with highest SFR (best stimulus-to-fatigue ratio)
     candidates.sort((candidateA, candidateB) =>
       candidateA.sfr !== candidateB.sfr
         ? candidateB.sfr - candidateA.sfr
         : candidateA.muscleGroupIndex - candidateB.muscleGroupIndex
     );
 
-    /**
-     * Gets the total sets currently planned for a session.
-     */
-    function getSessionTotal(exerciseId: UUID): number {
-      if (!context.exerciseIdToSessionIndex) return 0;
-      const sessionIndex = context.exerciseIdToSessionIndex.get(exerciseId);
-      if (sessionIndex === undefined) return 0;
-
-      const exerciseIdsInSession = sessionIndexToExerciseIds.get(sessionIndex);
-      if (!exerciseIdsInSession) return 0;
-
-      let total = 0;
-      exerciseIdsInSession.forEach((id) => {
-        total += exerciseIdToSetCount.get(id) || 0;
-      });
-      return total;
-    }
-
-    /**
-     * Attempts to add sets to an exercise, respecting all constraints.
-     * Returns the number of sets actually added.
-     */
-    function addSetsToExercise(exerciseId: UUID, setsToAdd: number): number {
-      const currentSets = exerciseIdToSetCount.get(exerciseId) || 0;
-      const sessionTotal = getSessionTotal(exerciseId);
-
-      const maxDueToExerciseLimit =
-        WorkoutVolumePlanningService.MAX_SETS_PER_EXERCISE - currentSets;
-      const maxDueToSessionLimit =
-        WorkoutVolumePlanningService.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION - sessionTotal;
-      const maxAddable = Math.min(
-        setsToAdd,
-        maxDueToExerciseLimit,
-        maxDueToSessionLimit,
-        WorkoutVolumePlanningService.MAX_SET_ADDITION_PER_EXERCISE
-      );
-
-      if (maxAddable > 0) {
-        exerciseIdToSetCount.set(exerciseId, currentSets + maxAddable);
-      }
-      return maxAddable;
-    }
-
+    // Cap total additions at MAX_TOTAL_SET_ADDITIONS regardless of raw recommendation
     let setsRemaining =
-      totalSetsToAdd >= WorkoutVolumePlanningService.MAX_TOTAL_SET_ADDITIONS
-        ? WorkoutVolumePlanningService.MAX_TOTAL_SET_ADDITIONS
+      totalSetsToAdd >= this.MAX_TOTAL_SET_ADDITIONS
+        ? this.MAX_TOTAL_SET_ADDITIONS
         : totalSetsToAdd;
+
+    // Distribute sets one candidate at a time until budget is exhausted
     for (const candidate of candidates) {
-      const added = addSetsToExercise(candidate.exerciseId, setsRemaining);
+      const added = this.addSetsToExercise(
+        candidate.exerciseId,
+        setsRemaining,
+        exerciseIdToSetCount,
+        exerciseIdToSessionIndex,
+        sessionIndexToExerciseIds
+      );
       setsRemaining -= added;
       if (setsRemaining === 0) break;
     }
-
-    return { exerciseIdToSetCount, recoveryExerciseIds };
   }
 
   /**
-   * Calculates the default number of sets for an exercise based on microcycle progression.
-   *
-   * Key rule: set progression is distributed across exercises that share the same primary muscle group
-   * for the entire microcycle, regardless of which session those exercises are in.
+   * Determines if the session containing the given exercise is already at the
+   * per-muscle-group-per-session cap, based on previous microcycle set counts.
    *
-   * Baseline: 2 sets per exercise in the muscle group.
-   * Progression: add 1 set per muscle group every `progressionInterval` microcycles.
-   * - MuscleGain (interval 1): every microcycle
-   * - Cut (interval 2): every other microcycle
-   * - Resensitization (interval 0): no progression (flat 2 sets per exercise)
-   *
-   * @param microcycleIndex The index of the current microcycle.
-   * @param totalExercisesInMuscleGroupForMicrocycle Total exercises in the muscle group for
-   * this microcycle.
-   * @param exerciseIndexInMuscleGroupForMicrocycle Index of the current exercise within the
-   * muscle group.
-   * @param isDeloadMicrocycle Whether this is a deload microcycle.
-   * @param progressionInterval Number of microcycles between each set addition. 0 means no
-   * progression.
+   * @param exerciseId The exercise to check.
+   * @param exerciseIdToSessionIndex Map from exercise ID to its session index.
+   * @param sessionIndexToExerciseIds Map from session index to exercise IDs in that session.
+   * @param exerciseIdToPrevSessionExercise Map from exercise ID to its previous session exercise.
    */
-  private static calculateBaselineSetCount(
-    microcycleIndex: number,
-    totalExercisesInMuscleGroupForMicrocycle: number,
-    exerciseIndexInMuscleGroupForMicrocycle: number,
-    isDeloadMicrocycle: boolean,
-    progressionInterval: number = 1
-  ): number {
-    // Deload microcycle: half the sets from the previous microcycle, minimum 1 set.
-    if (isDeloadMicrocycle) {
-      const baselineSets = this.calculateBaselineSetCount(
-        microcycleIndex - 1,
-        totalExercisesInMuscleGroupForMicrocycle,
-        exerciseIndexInMuscleGroupForMicrocycle,
-        false,
-        progressionInterval
+  private static sessionIsCapped(
+    exerciseId: UUID,
+    exerciseIdToSessionIndex: Map<UUID, number> | undefined,
+    sessionIndexToExerciseIds: Map<number, UUID[]>,
+    exerciseIdToPrevSessionExercise: Map<UUID, WorkoutSessionExercise>
+  ): boolean {
+    if (!exerciseIdToSessionIndex) {
+      throw new Error(
+        'WorkoutMesocyclePlanContext.exerciseIdToSessionIndex is not initialized. This should be set during mesocycle planning.'
       );
-      return Math.max(1, Math.floor(baselineSets / 2));
     }
+    const sessionIndex = exerciseIdToSessionIndex.get(exerciseId);
+    if (sessionIndex === undefined) return false;
+
+    const exerciseIdsInSession = sessionIndexToExerciseIds.get(sessionIndex);
+    if (!exerciseIdsInSession) return false;
+    let totalSetsInSession = 0;
+    exerciseIdsInSession.forEach((id) => {
+      totalSetsInSession += exerciseIdToPrevSessionExercise.get(id)?.setOrder.length || 0;
+    });
+    return totalSetsInSession >= this.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION;
+  }
+
+  /**
+   * Gets the total sets currently planned for a session containing the given exercise.
+   *
+   * @param exerciseId The exercise whose session total to compute.
+   * @param exerciseIdToSetCount Current set count assignments.
+   * @param exerciseIdToSessionIndex Map from exercise ID to its session index.
+   * @param sessionIndexToExerciseIds Map from session index to exercise IDs in that session.
+   */
+  private static getSessionSetTotal(
+    exerciseId: UUID,
+    exerciseIdToSetCount: Map<UUID, number>,
+    exerciseIdToSessionIndex: Map<UUID, number> | undefined,
+    sessionIndexToExerciseIds: Map<number, UUID[]>
+  ): number {
+    if (!exerciseIdToSessionIndex) return 0;
+    const sessionIndex = exerciseIdToSessionIndex.get(exerciseId);
+    if (sessionIndex === undefined) return 0;
 
-    // Total sets to distribute for this muscle group in this microcycle.
-    const progressionSets =
-      progressionInterval === 0 ? 0 : Math.ceil(microcycleIndex / progressionInterval);
-    const totalSets = 2 * totalExercisesInMuscleGroupForMicrocycle + progressionSets;
+    const exerciseIdsInSession = sessionIndexToExerciseIds.get(sessionIndex);
+    if (!exerciseIdsInSession) return 0;
 
-    // Distribute sets evenly, with earlier exercises getting extra sets from the remainder.
-    const baseSetsPerExercise = Math.floor(totalSets / totalExercisesInMuscleGroupForMicrocycle);
-    const remainder = totalSets % totalExercisesInMuscleGroupForMicrocycle;
+    let total = 0;
+    exerciseIdsInSession.forEach((id) => {
+      total += exerciseIdToSetCount.get(id) || 0;
+    });
+    return total;
+  }
 
-    return exerciseIndexInMuscleGroupForMicrocycle < remainder
-      ? baseSetsPerExercise + 1
-      : baseSetsPerExercise;
+  /**
+   * Attempts to add sets to an exercise, respecting per-exercise, per-session, and
+   * per-addition caps. Mutates `exerciseIdToSetCount` in place.
+   *
+   * @param exerciseId The exercise to add sets to.
+   * @param setsToAdd The desired number of sets to add.
+   * @param exerciseIdToSetCount Current set count assignments (mutated).
+   * @param exerciseIdToSessionIndex Map from exercise ID to its session index.
+   * @param sessionIndexToExerciseIds Map from session index to exercise IDs in that session.
+   * @returns The number of sets actually added.
+   */
+  private static addSetsToExercise(
+    exerciseId: UUID,
+    setsToAdd: number,
+    exerciseIdToSetCount: Map<UUID, number>,
+    exerciseIdToSessionIndex: Map<UUID, number> | undefined,
+    sessionIndexToExerciseIds: Map<number, UUID[]>
+  ): number {
+    const currentSets = exerciseIdToSetCount.get(exerciseId) || 0;
+    const sessionTotal = this.getSessionSetTotal(
+      exerciseId,
+      exerciseIdToSetCount,
+      exerciseIdToSessionIndex,
+      sessionIndexToExerciseIds
+    );
+
+    // Respect all caps: per-exercise max, per-session max, and per-addition max
+    const maxDueToExerciseLimit = this.MAX_SETS_PER_EXERCISE - currentSets;
+    const maxDueToSessionLimit = this.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION - sessionTotal;
+    const maxAddable = Math.min(
+      setsToAdd,
+      maxDueToExerciseLimit,
+      maxDueToSessionLimit,
+      this.MAX_SET_ADDITION_PER_EXERCISE
+    );
+
+    if (maxAddable > 0) {
+      exerciseIdToSetCount.set(exerciseId, currentSets + maxAddable);
+    }
+    return maxAddable;
   }
 }