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

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

@@ -1,8 +1,13 @@
 import type { UUID } from 'crypto';
 import type { WorkoutExerciseCTO } from '../../../../ctos/workout/WorkoutExerciseCTO.js';
+import type {
+  WorkoutMuscleGroupVolumeCTO,
+  WorkoutVolumeLandmarkEstimate
+} from '../../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
 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';
 
 /**
  * A service for handling volume planning operations across microcycles.
@@ -24,6 +29,39 @@ export default class WorkoutVolumePlanningService {
   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;
+
+  /** Minimum average performance score (or recovery presence) to count a mesocycle toward MRV estimation. */
+  private static readonly MRV_PERFORMANCE_THRESHOLD = 2.5;
+
+  /** 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;
+
+  /** Maximum sets that can be added to a single exercise in one progression step. */
+  private static readonly MAX_SET_ADDITION_PER_EXERCISE = 2;
+
+  /** Maximum total sets to distribute across a muscle group in one progression step. */
+  private static readonly MAX_TOTAL_SET_ADDITIONS = 3;
+
   /**
    * Calculates the set plan for an entire microcycle.
    */
@@ -56,9 +94,185 @@ 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 };
   }
 
+  /**
+   * Estimates MEV, MRV, and MAV for a muscle group based on historical data
+   * across completed mesocycles.
+   *
+   * @param volumeCTO The WorkoutMuscleGroupVolumeCTO containing mesocycle
+   *   history for this muscle group.
+   */
+  static estimateVolumeLandmarks(
+    volumeCTO: WorkoutMuscleGroupVolumeCTO
+  ): WorkoutVolumeLandmarkEstimate {
+    const { mesocycleHistory } = volumeCTO;
+
+    // Estimated MEV
+    let estimatedMev: number;
+    const effectiveMesocycles = mesocycleHistory.filter(
+      (m) => m.avgRsm !== null && m.avgRsm >= this.MEV_RSM_THRESHOLD
+    );
+    if (effectiveMesocycles.length > 0) {
+      estimatedMev =
+        effectiveMesocycles.reduce((sum, m) => sum + m.startingSetCount, 0) /
+        effectiveMesocycles.length;
+      estimatedMev = Math.round(estimatedMev);
+    } else if (mesocycleHistory.length > 0) {
+      estimatedMev = Math.min(...mesocycleHistory.map((m) => m.startingSetCount));
+    } else {
+      estimatedMev = this.DEFAULT_MEV;
+    }
+
+    // Estimated MRV
+    let estimatedMrv: number;
+    const stressedMesocycles = mesocycleHistory.filter(
+      (m) =>
+        (m.avgPerformanceScore !== null &&
+          m.avgPerformanceScore >= this.MRV_PERFORMANCE_THRESHOLD) ||
+        m.recoverySessionCount > 0
+    );
+    if (stressedMesocycles.length > 0) {
+      estimatedMrv =
+        stressedMesocycles.reduce((sum, m) => sum + m.peakSetCount, 0) / stressedMesocycles.length;
+      estimatedMrv = Math.round(estimatedMrv);
+    } else if (mesocycleHistory.length > 0) {
+      estimatedMrv = Math.max(...mesocycleHistory.map((m) => m.peakSetCount)) + this.MRV_HEADROOM;
+    } else {
+      estimatedMrv = this.DEFAULT_MRV;
+    }
+
+    // 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;
+    }
+
+    const estimatedMav = Math.ceil((estimatedMev + estimatedMrv) / 2);
+
+    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.
    *
@@ -75,13 +289,16 @@ export default class WorkoutVolumePlanningService {
     const recoveryExerciseIds = new Set<UUID>();
     const sessionIndexToExerciseIds = new Map<number, UUID[]>();
 
+    const { progressionInterval } = context;
+
     // 1. Calculate baselines for all exercises in muscle group
     muscleGroupExerciseCTOs.forEach((cto, index) => {
       const baseline = this.calculateBaselineSetCount(
         microcycleIndex,
         muscleGroupExerciseCTOs.length,
         index,
-        isDeloadMicrocycle
+        isDeloadMicrocycle,
+        progressionInterval
       );
       exerciseIdToSetCount.set(cto._id, Math.min(baseline, this.MAX_SETS_PER_EXERCISE));
 
@@ -150,13 +367,26 @@ export default class WorkoutVolumePlanningService {
     // 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;
+
     muscleGroupExerciseCTOs.forEach((cto) => {
       const previousSessionExercise = exerciseIdToPrevSessionExercise.get(cto._id);
       if (previousSessionExercise) {
-        let setCount = Math.min(
-          previousSessionExercise.setOrder.length,
-          this.MAX_SETS_PER_EXERCISE
-        );
+        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 (isDeloadMicrocycle) {
           setCount = Math.max(1, Math.floor(setCount / 2));
         }
@@ -164,8 +394,8 @@ export default class WorkoutVolumePlanningService {
       }
     });
 
-    // Deload microcycles use reduced volume — skip SFR-based set additions
-    if (isDeloadMicrocycle) {
+    // Deload microcycles and zero-progression cycles (Resensitization) skip SFR-based set additions
+    if (isDeloadMicrocycle || progressionInterval === 0) {
       return { exerciseIdToSetCount, recoveryExerciseIds };
     }
 
@@ -225,7 +455,7 @@ export default class WorkoutVolumePlanningService {
         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) {
+      } else if (recommendation !== null && recommendation >= 0) {
         totalSetsToAdd += recommendation;
 
         // Consider as candidate if session is not already capped
@@ -289,8 +519,12 @@ export default class WorkoutVolumePlanningService {
         WorkoutVolumePlanningService.MAX_SETS_PER_EXERCISE - currentSets;
       const maxDueToSessionLimit =
         WorkoutVolumePlanningService.MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION - sessionTotal;
-      // Hard limit of 2 to add to a particular exercise at once
-      const maxAddable = Math.min(setsToAdd, maxDueToExerciseLimit, maxDueToSessionLimit, 2);
+      const maxAddable = Math.min(
+        setsToAdd,
+        maxDueToExerciseLimit,
+        maxDueToSessionLimit,
+        WorkoutVolumePlanningService.MAX_SET_ADDITION_PER_EXERCISE
+      );
 
       if (maxAddable > 0) {
         exerciseIdToSetCount.set(exerciseId, currentSets + maxAddable);
@@ -298,8 +532,10 @@ export default class WorkoutVolumePlanningService {
       return maxAddable;
     }
 
-    // Cap the actual sets to add to 3 total
-    let setsRemaining = totalSetsToAdd >= 3 ? 3 : totalSetsToAdd;
+    let setsRemaining =
+      totalSetsToAdd >= WorkoutVolumePlanningService.MAX_TOTAL_SET_ADDITIONS
+        ? WorkoutVolumePlanningService.MAX_TOTAL_SET_ADDITIONS
+        : totalSetsToAdd;
     for (const candidate of candidates) {
       const added = addSetsToExercise(candidate.exerciseId, setsRemaining);
       setsRemaining -= added;
@@ -316,14 +552,26 @@ export default class WorkoutVolumePlanningService {
    * for the entire microcycle, regardless of which session those exercises are in.
    *
    * Baseline: 2 sets per exercise in the muscle group.
-   * Progression: add 1 total set per microcycle per muscle group (distributed to earlier exercises
-   * in the muscle-group-wide ordering).
+   * 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.
    */
   private static calculateBaselineSetCount(
     microcycleIndex: number,
     totalExercisesInMuscleGroupForMicrocycle: number,
     exerciseIndexInMuscleGroupForMicrocycle: number,
-    isDeloadMicrocycle: boolean
+    isDeloadMicrocycle: boolean,
+    progressionInterval: number = 1
   ): number {
     // Deload microcycle: half the sets from the previous microcycle, minimum 1 set.
     if (isDeloadMicrocycle) {
@@ -331,14 +579,16 @@ export default class WorkoutVolumePlanningService {
         microcycleIndex - 1,
         totalExercisesInMuscleGroupForMicrocycle,
         exerciseIndexInMuscleGroupForMicrocycle,
-        false
+        false,
+        progressionInterval
       );
       return Math.max(1, Math.floor(baselineSets / 2));
     }
 
     // Total sets to distribute for this muscle group in this microcycle.
-    // For now, add exactly +1 total set per microcycle per muscle group.
-    const totalSets = 2 * totalExercisesInMuscleGroupForMicrocycle + microcycleIndex;
+    const progressionSets =
+      progressionInterval === 0 ? 0 : Math.ceil(microcycleIndex / progressionInterval);
+    const totalSets = 2 * totalExercisesInMuscleGroupForMicrocycle + progressionSets;
 
     // Distribute sets evenly, with earlier exercises getting extra sets from the remainder.
     const baseSetsPerExercise = Math.floor(totalSets / totalExercisesInMuscleGroupForMicrocycle);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@aneuhold/core-ts-db-lib",
   "author": "Anton G. Neuhold Jr.",
   "license": "MIT",
-  "version": "4.1.12",
+  "version": "4.1.13",
   "description": "A core database library used for personal projects",
   "packageManager": "pnpm@10.25.0",
   "type": "module",