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

package/lib/services/workout/Exercise/WorkoutExerciseService.ts

@@ -5,8 +5,10 @@ import {
   ExerciseRepRange
 } from '../../../documents/workout/WorkoutExercise.js';
 import type { WorkoutExerciseCalibration } from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import type { CompletedWorkoutSet, WorkoutSet } from '../../../documents/workout/WorkoutSet.js';
 import WorkoutEquipmentTypeService from '../EquipmentType/WorkoutEquipmentTypeService.js';
 import WorkoutExerciseCalibrationService from '../ExerciseCalibration/WorkoutExerciseCalibrationService.js';
+import WorkoutSessionExerciseService from '../SessionExercise/WorkoutSessionExerciseService.js';
 import WorkoutSFRService from '../util/SFR/WorkoutSFRService.js';
 
 /**
@@ -50,6 +52,10 @@ export default class WorkoutExerciseService {
    * This method applies either rep-based or load-based progression depending on the exercise's
    * preferred progression type, then rounds the weight to available equipment options.
    *
+   * When a `previousFirstSet` is provided, autoregulation adjusts progression based on the
+   * surplus between planned and actual performance. Without it, the calibration-based formula
+   * is used as a baseline.
+   *
    * Rep progression: The weight is calculated based on reps at microcycle 0, and reps increase
    * by 2 per microcycle to reach max reps at the final accumulation microcycle (ideally),
    * or drop back down and increase weight by 2%.
@@ -63,8 +69,16 @@ export default class WorkoutExerciseService {
     equipment: WorkoutEquipmentType;
     microcycleIndex: number;
     firstMicrocycleRir: number;
+    previousFirstSet?: WorkoutSet;
   }): { targetWeight: number; targetReps: number } {
-    const { exercise, calibration, equipment, microcycleIndex, firstMicrocycleRir } = params;
+    const {
+      exercise,
+      calibration,
+      equipment,
+      microcycleIndex,
+      firstMicrocycleRir,
+      previousFirstSet
+    } = params;
 
     // Validate equipment has weight options
     if (!equipment.weightOptions || equipment.weightOptions.length === 0) {
@@ -77,6 +91,195 @@ export default class WorkoutExerciseService {
     const repRange = this.getRepRangeValues(exercise.repRange);
     const repRangeMidpoint = Math.floor((repRange.min + repRange.max) / 2);
 
+    // If we have a previous set with complete data, use autoregulation
+    if (previousFirstSet && this.hasCompleteAutoRegulationData(previousFirstSet)) {
+      return this.calculateAutoRegulatedTargets({
+        exercise,
+        equipment,
+        previousFirstSet,
+        repRange
+      });
+    }
+
+    // Calibration-based formula (no previous set available)
+    return this.calculateCalibrationBasedTargets({
+      exercise,
+      calibration,
+      equipment,
+      microcycleIndex,
+      firstMicrocycleRir,
+      repRange,
+      repRangeMidpoint
+    });
+  }
+
+  /**
+   * Calculates targets using auto-regulation based on actual performance from a previous set.
+   */
+  private static calculateAutoRegulatedTargets(params: {
+    exercise: WorkoutExercise;
+    equipment: WorkoutEquipmentType;
+    previousFirstSet: CompletedWorkoutSet;
+    repRange: { min: number; max: number };
+  }): { targetWeight: number; targetReps: number } {
+    const { exercise, equipment, previousFirstSet, repRange } = params;
+
+    const surplus = WorkoutSessionExerciseService.calculateSetSurplus(
+      previousFirstSet.actualReps,
+      previousFirstSet.plannedReps,
+      previousFirstSet.rir,
+      previousFirstSet.plannedRir
+    );
+
+    if (exercise.preferredProgressionType === ExerciseProgressionType.Rep) {
+      return this.calculateAutoRegulatedRepTargets(previousFirstSet, surplus, repRange, equipment);
+    }
+
+    return this.calculateAutoRegulatedLoadTargets(previousFirstSet, surplus, repRange, equipment);
+  }
+
+  /**
+   * Auto-regulated rep progression. Weight stays the same, reps adjust based on surplus.
+   *
+   * | Surplus | Action |
+   * |---:|---|
+   * | >= 3 | Accelerate: actualReps + 2 (progress from actual, not planned) |
+   * | 0 to 2 | Normal: plannedReps + 2 |
+   * | -1 to -2 | Hold: plannedReps (don't add reps) |
+   * | <= -3 | Regress: actualReps (use actual as new baseline) |
+   */
+  private static calculateAutoRegulatedRepTargets(
+    previousSet: CompletedWorkoutSet,
+    surplus: number,
+    repRange: { min: number; max: number },
+    equipment: WorkoutEquipmentType
+  ): { targetWeight: number; targetReps: number } {
+    let targetReps: number;
+    let targetWeight = previousSet.plannedWeight;
+
+    if (surplus >= 3) {
+      targetReps = previousSet.actualReps + 2;
+    } else if (surplus >= 0) {
+      targetReps = previousSet.plannedReps + 2;
+    } else if (surplus >= -2) {
+      targetReps = previousSet.plannedReps;
+    } else {
+      targetReps = previousSet.actualReps;
+    }
+
+    // Clamp to rep range floor (never target below min, even if actual was 0)
+    targetReps = Math.max(targetReps, repRange.min);
+
+    // Handle rep range ceiling: if target exceeds max, reset and bump weight
+    if (targetReps > repRange.max) {
+      targetReps = repRange.max;
+      const nextWeight = this.findNextTwoPercentWeight(targetWeight, equipment);
+      if (nextWeight !== null) {
+        targetWeight = nextWeight;
+      }
+    }
+
+    // Round weight to equipment
+    const roundedWeight = WorkoutEquipmentTypeService.findNearestWeight(
+      equipment,
+      targetWeight,
+      'prefer-down'
+    );
+    if (roundedWeight !== null) {
+      targetWeight = roundedWeight;
+    }
+
+    return { targetWeight, targetReps };
+  }
+
+  /**
+   * Auto-regulated load progression. Reps stay at rep range max, weight adjusts based on surplus.
+   *
+   * | Surplus | Action |
+   * |---:|---|
+   * | >= 2 | Accelerate: increase weight by ~4% |
+   * | 0 to 1 | Normal: increase weight by 2% |
+   * | -1 to -2 | Hold weight (no increase) |
+   * | <= -3 | Reduce weight by minimum equipment increment |
+   */
+  private static calculateAutoRegulatedLoadTargets(
+    previousSet: CompletedWorkoutSet,
+    surplus: number,
+    repRange: { min: number; max: number },
+    equipment: WorkoutEquipmentType
+  ): { targetWeight: number; targetReps: number } {
+    const targetReps = repRange.max;
+    let targetWeight = previousSet.plannedWeight;
+
+    if (surplus >= 2) {
+      // Accelerate: increase by ~4%
+      const fourPercentIncrease = targetWeight * 1.04;
+      const nextWeight = WorkoutEquipmentTypeService.findNearestWeight(
+        equipment,
+        fourPercentIncrease,
+        'up'
+      );
+      if (nextWeight !== null) {
+        targetWeight = nextWeight;
+      }
+    } else if (surplus >= 0) {
+      // Normal: increase by 2%
+      const nextWeight = this.findNextTwoPercentWeight(targetWeight, equipment);
+      if (nextWeight !== null) {
+        targetWeight = nextWeight;
+      }
+    } else if (surplus >= -2) {
+      // Hold weight - no change
+    } else {
+      // Reduce by minimum equipment increment
+      const reducedWeight = WorkoutEquipmentTypeService.findNearestWeight(
+        equipment,
+        targetWeight - 0.01,
+        'down'
+      );
+      if (reducedWeight !== null) {
+        targetWeight = reducedWeight;
+      }
+    }
+
+    return { targetWeight, targetReps };
+  }
+
+  /**
+   * Checks whether a set has all the data needed for autoregulation calculations.
+   */
+  private static hasCompleteAutoRegulationData(set: WorkoutSet): set is CompletedWorkoutSet {
+    return (
+      set.actualReps != null &&
+      set.plannedReps != null &&
+      set.rir != null &&
+      set.plannedRir != null &&
+      set.plannedWeight != null
+    );
+  }
+
+  /**
+   * Calculates targets using the calibration-based formula (original behavior).
+   */
+  private static calculateCalibrationBasedTargets(params: {
+    exercise: WorkoutExercise;
+    calibration: WorkoutExerciseCalibration;
+    equipment: WorkoutEquipmentType;
+    microcycleIndex: number;
+    firstMicrocycleRir: number;
+    repRange: { min: number; max: number };
+    repRangeMidpoint: number;
+  }): { targetWeight: number; targetReps: number } {
+    const {
+      exercise,
+      calibration,
+      equipment,
+      microcycleIndex,
+      firstMicrocycleRir,
+      repRange,
+      repRangeMidpoint
+    } = params;
+
     // For rep progression, calculate weight based on reps at microcycle 0
     // For load progression, use max reps
     let baseRepsForWeight: number;

package/lib/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.d.ts

@@ -45,6 +45,21 @@ export default class WorkoutExerciseCalibrationService {
      * @param targetReps The target number of reps.
      */
     static getTargetWeight(calibration: WorkoutExerciseCalibration, targetReps: number): number;
+    /**
+     * Calculates the target weight from a raw 1RM value and a target rep count.
+     *
+     * This applies the same targetPercentage formula as {@link getTargetWeight}
+     * but accepts a pre-computed 1RM instead of a calibration document. Useful
+     * when the effective 1RM is derived from multiple sources (calibrations and
+     * actual sets).
+     *
+     * Returns the calculated weight without rounding. Consumer can use
+     * WorkoutEquipmentTypeService.findNearestWeight() to round if needed.
+     *
+     * @param effective1RM The effective 1 Rep Max value.
+     * @param targetReps The target number of reps.
+     */
+    static getTargetWeightFrom1RM(effective1RM: number, targetReps: number): number;
     /**
      * Generates auto-calibrations from exercise CTOs whose best set 1RM exceeds
      * their best calibration 1RM.

package/lib/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutExerciseCalibrationService.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACtF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAC;AAM3G;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,iCAAiC;IACpD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,0BAA0B,GAAG,MAAM;IAI9D;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAItD;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;;IAM7D;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,0BAA0B,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAM3F;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,wBAAwB,CAC7B,YAAY,EAAE,kBAAkB,EAAE,EAClC,MAAM,EAAE,IAAI,EACZ,YAAY,EAAE,IAAI,GACjB,0BAA0B,EAAE;IA4B/B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAGnC"}
+{"version":3,"file":"WorkoutExerciseCalibrationService.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACtF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAC;AAM3G;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,iCAAiC;IACpD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,0BAA0B,GAAG,MAAM;IAI9D;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAItD;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;;IAM7D;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,0BAA0B,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAK3F;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAK/E;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,wBAAwB,CAC7B,YAAY,EAAE,kBAAkB,EAAE,EAClC,MAAM,EAAE,IAAI,EACZ,YAAY,EAAE,IAAI,GACjB,0BAA0B,EAAE;IA4B/B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAGnC"}

package/lib/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.js

@@ -48,8 +48,25 @@ export default class WorkoutExerciseCalibrationService {
      */
     static getTargetWeight(calibration, targetReps) {
         const oneRepMax = this.get1RM(calibration);
+        return this.getTargetWeightFrom1RM(oneRepMax, targetReps);
+    }
+    /**
+     * Calculates the target weight from a raw 1RM value and a target rep count.
+     *
+     * This applies the same targetPercentage formula as {@link getTargetWeight}
+     * but accepts a pre-computed 1RM instead of a calibration document. Useful
+     * when the effective 1RM is derived from multiple sources (calibrations and
+     * actual sets).
+     *
+     * Returns the calculated weight without rounding. Consumer can use
+     * WorkoutEquipmentTypeService.findNearestWeight() to round if needed.
+     *
+     * @param effective1RM The effective 1 Rep Max value.
+     * @param targetReps The target number of reps.
+     */
+    static getTargetWeightFrom1RM(effective1RM, targetReps) {
         const targetPercentage = this.getTargetPercentage(targetReps);
-        return (targetPercentage / 100) * oneRepMax;
+        return (targetPercentage / 100) * effective1RM;
     }
     /**
      * Generates auto-calibrations from exercise CTOs whose best set 1RM exceeds

package/lib/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutExerciseCalibrationService.js","sourceRoot":"","sources":["../../../../src/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gCAAgC,EAAE,MAAM,0DAA0D,CAAC;AAE5G,mFAAmF;AACnF,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,iCAAiC;IACpD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,WAAuC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAc,EAAE,IAAY;QAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACrD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,WAAmB,EAAE,SAAiB;QAC3D,OAAO;YACL,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,EAAE,gBAAgB,CAAC,EAAE,EAAE,WAAW,CAAC;SAC9F,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,WAAuC,EAAE,UAAkB;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC3C,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;QAC9D,OAAO,CAAC,gBAAgB,GAAG,GAAG,CAAC,GAAG,SAAS,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,wBAAwB,CAC7B,YAAkC,EAClC,MAAY,EACZ,YAAkB;QAElB,MAAM,eAAe,GAAiC,EAAE,CAAC;QAEzD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,GAAG,CAAC;YACzC,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC;gBAAE,SAAS;YAEvF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YACxE,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAElE,IAAI,MAAM,GAAG,MAAM,EAAE,CAAC;gBACpB,eAAe,CAAC,IAAI,CAClB,gCAAgC,CAAC,KAAK,CAAC;oBACrC,MAAM;oBACN,iBAAiB,EAAE,GAAG,CAAC,GAAG;oBAC1B,MAAM,EAAE,OAAO,CAAC,YAAY;oBAC5B,IAAI,EAAE,OAAO,CAAC,UAAU;oBACxB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;oBAC9C,YAAY;oBACZ,sBAAsB,EAAE,OAAO,CAAC,GAAG;iBACpC,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;IAED;;;;;;;;;OASG;IACK,MAAM,CAAC,mBAAmB,CAAC,UAAkB;QACnD,OAAO,EAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;CACF"}
+{"version":3,"file":"WorkoutExerciseCalibrationService.js","sourceRoot":"","sources":["../../../../src/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gCAAgC,EAAE,MAAM,0DAA0D,CAAC;AAE5G,mFAAmF;AACnF,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,iCAAiC;IACpD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,WAAuC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAc,EAAE,IAAY;QAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACrD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,WAAmB,EAAE,SAAiB;QAC3D,OAAO;YACL,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,EAAE,gBAAgB,CAAC,EAAE,EAAE,WAAW,CAAC;SAC9F,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,WAAuC,EAAE,UAAkB;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,sBAAsB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,sBAAsB,CAAC,YAAoB,EAAE,UAAkB;QACpE,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;QAC9D,OAAO,CAAC,gBAAgB,GAAG,GAAG,CAAC,GAAG,YAAY,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,wBAAwB,CAC7B,YAAkC,EAClC,MAAY,EACZ,YAAkB;QAElB,MAAM,eAAe,GAAiC,EAAE,CAAC;QAEzD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,GAAG,CAAC;YACzC,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC;gBAAE,SAAS;YAEvF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YACxE,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAElE,IAAI,MAAM,GAAG,MAAM,EAAE,CAAC;gBACpB,eAAe,CAAC,IAAI,CAClB,gCAAgC,CAAC,KAAK,CAAC;oBACrC,MAAM;oBACN,iBAAiB,EAAE,GAAG,CAAC,GAAG;oBAC1B,MAAM,EAAE,OAAO,CAAC,YAAY;oBAC5B,IAAI,EAAE,OAAO,CAAC,UAAU;oBACxB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;oBAC9C,YAAY;oBACZ,sBAAsB,EAAE,OAAO,CAAC,GAAG;iBACpC,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;IAED;;;;;;;;;OASG;IACK,MAAM,CAAC,mBAAmB,CAAC,UAAkB;QACnD,OAAO,EAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;CACF"}

package/lib/services/workout/ExerciseCalibration/WorkoutExerciseCalibrationService.ts

@@ -56,8 +56,26 @@ export default class WorkoutExerciseCalibrationService {
    */
   static getTargetWeight(calibration: WorkoutExerciseCalibration, targetReps: number): number {
     const oneRepMax = this.get1RM(calibration);
+    return this.getTargetWeightFrom1RM(oneRepMax, targetReps);
+  }
+
+  /**
+   * Calculates the target weight from a raw 1RM value and a target rep count.
+   *
+   * This applies the same targetPercentage formula as {@link getTargetWeight}
+   * but accepts a pre-computed 1RM instead of a calibration document. Useful
+   * when the effective 1RM is derived from multiple sources (calibrations and
+   * actual sets).
+   *
+   * Returns the calculated weight without rounding. Consumer can use
+   * WorkoutEquipmentTypeService.findNearestWeight() to round if needed.
+   *
+   * @param effective1RM The effective 1 Rep Max value.
+   * @param targetReps The target number of reps.
+   */
+  static getTargetWeightFrom1RM(effective1RM: number, targetReps: number): number {
     const targetPercentage = this.getTargetPercentage(targetReps);
-    return (targetPercentage / 100) * oneRepMax;
+    return (targetPercentage / 100) * effective1RM;
   }
 
   /**

package/lib/services/workout/Mesocycle/WorkoutMesocyclePlanContext.d.ts

@@ -1,5 +1,6 @@
 import type { UUID } from 'crypto';
 import type { WorkoutExerciseCTO } from '../../../ctos/workout/WorkoutExerciseCTO.js';
+import type { WorkoutMuscleGroupVolumeCTO } from '../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
 import type { WorkoutEquipmentType } from '../../../documents/workout/WorkoutEquipmentType.js';
 import type { WorkoutExercise } from '../../../documents/workout/WorkoutExercise.js';
 import type { WorkoutMesocycle } from '../../../documents/workout/WorkoutMesocycle.js';
@@ -7,6 +8,7 @@ import type { WorkoutMicrocycle } from '../../../documents/workout/WorkoutMicroc
 import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
 import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
 import type { WorkoutSet } from '../../../documents/workout/WorkoutSet.js';
+import type { WorkoutVolumeLandmarkEstimate } from '../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
 /**
  * Central shared context for generating or updating a {@link WorkoutMesocycle}.
  *
@@ -21,14 +23,25 @@ export default class WorkoutMesocyclePlanContext {
     existingSessionExercises: WorkoutSessionExercise[];
     existingSets: WorkoutSet[];
     /**
-     * A constant for now that defines what the target RIR is for the first microcycle of every mesocycle,
-     * regardless of anything else.
+     * The target RIR for the first microcycle of the mesocycle. Varies by cycle
+     * type: MuscleGain starts at 4, Cut starts at 3, Resensitization stays at 3.
      */
-    readonly FIRST_MICROCYCLE_RIR = 4;
+    readonly firstMicrocycleRir: number;
+    /**
+     * Number of microcycles between each baseline set addition.
+     * MuscleGain = 1 (every microcycle), Cut = 2 (every other), Resensitization = 0 (never).
+     */
+    readonly progressionInterval: number;
+    /**
+     * Whether this mesocycle type skips the deload microcycle. True for
+     * Resensitization cycles.
+     */
+    readonly skipDeload: boolean;
     readonly exerciseMap: Map<UUID, WorkoutExercise>;
     readonly equipmentMap: Map<UUID, WorkoutEquipmentType>;
     readonly sessionMap: Map<UUID, WorkoutSession>;
     readonly sessionExerciseMap: Map<UUID, WorkoutSessionExercise>;
+    readonly setMap: Map<UUID, WorkoutSet>;
     readonly microcyclesToCreate: WorkoutMicrocycle[];
     /**
      * All microcycles for this mesocycle in chronological order.
@@ -53,11 +66,16 @@ export default class WorkoutMesocyclePlanContext {
      * ended up in.
      */
     muscleGroupToExerciseCTOsMap: Map<UUID, WorkoutExerciseCTO[]> | undefined;
+    /**
+     * Maps muscle group ID to its estimated volume landmarks (MEV, MRV, MAV).
+     * Populated from WorkoutMuscleGroupVolumeCTOs when provided.
+     */
+    muscleGroupToVolumeLandmarkMap: Map<UUID, WorkoutVolumeLandmarkEstimate>;
     exerciseIdToSessionIndex: Map<UUID, number> | undefined;
     /**
      * Creates a new workout mesocycle planning context.
      */
-    constructor(mesocycle: WorkoutMesocycle, exerciseCTOs: WorkoutExerciseCTO[], existingMicrocycles?: WorkoutMicrocycle[], existingSessions?: WorkoutSession[], existingSessionExercises?: WorkoutSessionExercise[], existingSets?: WorkoutSet[]);
+    constructor(mesocycle: WorkoutMesocycle, exerciseCTOs: WorkoutExerciseCTO[], volumeCTOs?: WorkoutMuscleGroupVolumeCTO[], existingMicrocycles?: WorkoutMicrocycle[], existingSessions?: WorkoutSession[], existingSessionExercises?: WorkoutSessionExercise[], existingSets?: WorkoutSet[]);
     /**
      * Adds a microcycle to the list of microcycles to create and the overall chronological list.
      */
@@ -70,6 +88,10 @@ export default class WorkoutMesocyclePlanContext {
      * Adds a session exercise to the context and updates internal maps.
      */
     addSessionExercise(sessionExercise: WorkoutSessionExercise): void;
+    /**
+     * Adds sets to the context and updates the set map for O(1) lookup.
+     */
+    addSets(sets: WorkoutSet[]): void;
     /**
      * Stores the planned session -> exercises structure for the mesocycle and derives
      * the muscle-group-wide ordering used for set progression.

package/lib/services/workout/Mesocycle/WorkoutMesocyclePlanContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutMesocyclePlanContext.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/Mesocycle/WorkoutMesocyclePlanContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACtF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAC;AAC/F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+CAA+C,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iDAAiD,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,2BAA2B;IA2CrC,SAAS,EAAE,gBAAgB;IAE3B,mBAAmB,EAAE,iBAAiB,EAAE;IACxC,gBAAgB,EAAE,cAAc,EAAE;IAClC,wBAAwB,EAAE,sBAAsB,EAAE;IAClD,YAAY,EAAE,UAAU,EAAE;IA/CnC;;;OAGG;IACH,SAAgB,oBAAoB,KAAK;IAEzC,SAAgB,WAAW,EAAE,GAAG,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACxD,SAAgB,YAAY,EAAE,GAAG,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC9D,SAAgB,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACtD,SAAgB,kBAAkB,EAAE,GAAG,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;IAEtE,SAAgB,mBAAmB,EAAE,iBAAiB,EAAE,CAAM;IAC9D;;;;;OAKG;IACH,SAAgB,kBAAkB,EAAE,iBAAiB,EAAE,CAAM;IAC7D,SAAgB,gBAAgB,EAAE,cAAc,EAAE,CAAM;IACxD,SAAgB,wBAAwB,EAAE,sBAAsB,EAAE,CAAM;IACxE,SAAgB,YAAY,EAAE,UAAU,EAAE,CAAM;IAEhD;;;OAGG;IACI,0BAA0B,EAAE,kBAAkB,EAAE,EAAE,GAAG,SAAS,CAAC;IACtE;;;;;;OAMG;IACI,4BAA4B,EAAE,GAAG,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,GAAG,SAAS,CAAC;IAC1E,wBAAwB,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAE/D;;OAEG;gBAEM,SAAS,EAAE,gBAAgB,EAClC,YAAY,EAAE,kBAAkB,EAAE,EAC3B,mBAAmB,GAAE,iBAAiB,EAAO,EAC7C,gBAAgB,GAAE,cAAc,EAAO,EACvC,wBAAwB,GAAE,sBAAsB,EAAO,EACvD,YAAY,GAAE,UAAU,EAAO;IAmBxC;;OAEG;IACI,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAKvD;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAKhD;;OAEG;IACI,kBAAkB,CAAC,eAAe,EAAE,sBAAsB,GAAG,IAAI;IAKxE;;;OAGG;IACI,6BAA6B,CAAC,0BAA0B,EAAE,kBAAkB,EAAE,EAAE,GAAG,IAAI;IAK9F;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CA0B5B"}
+{"version":3,"file":"WorkoutMesocyclePlanContext.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/Mesocycle/WorkoutMesocyclePlanContext.ts"],"names":[],"mappings":"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"}

package/lib/services/workout/Mesocycle/WorkoutMesocyclePlanContext.js

@@ -1,3 +1,5 @@
+import { CycleType } from '../../../documents/workout/WorkoutMesocycle.js';
+import WorkoutVolumePlanningService from '../util/VolumePlanning/WorkoutVolumePlanningService.js';
 /**
  * Central shared context for generating or updating a {@link WorkoutMesocycle}.
  *
@@ -12,14 +14,25 @@ export default class WorkoutMesocyclePlanContext {
     existingSessionExercises;
     existingSets;
     /**
-     * A constant for now that defines what the target RIR is for the first microcycle of every mesocycle,
-     * regardless of anything else.
+     * The target RIR for the first microcycle of the mesocycle. Varies by cycle
+     * type: MuscleGain starts at 4, Cut starts at 3, Resensitization stays at 3.
      */
-    FIRST_MICROCYCLE_RIR = 4;
+    firstMicrocycleRir;
+    /**
+     * Number of microcycles between each baseline set addition.
+     * MuscleGain = 1 (every microcycle), Cut = 2 (every other), Resensitization = 0 (never).
+     */
+    progressionInterval;
+    /**
+     * Whether this mesocycle type skips the deload microcycle. True for
+     * Resensitization cycles.
+     */
+    skipDeload;
     exerciseMap;
     equipmentMap;
     sessionMap;
     sessionExerciseMap;
+    setMap;
     microcyclesToCreate = [];
     /**
      * All microcycles for this mesocycle in chronological order.
@@ -44,22 +57,47 @@ export default class WorkoutMesocyclePlanContext {
      * ended up in.
      */
     muscleGroupToExerciseCTOsMap;
+    /**
+     * Maps muscle group ID to its estimated volume landmarks (MEV, MRV, MAV).
+     * Populated from WorkoutMuscleGroupVolumeCTOs when provided.
+     */
+    muscleGroupToVolumeLandmarkMap;
     exerciseIdToSessionIndex;
     /**
      * Creates a new workout mesocycle planning context.
      */
-    constructor(mesocycle, exerciseCTOs, existingMicrocycles = [], existingSessions = [], existingSessionExercises = [], existingSets = []) {
+    constructor(mesocycle, exerciseCTOs, volumeCTOs = [], existingMicrocycles = [], existingSessions = [], existingSessionExercises = [], existingSets = []) {
         this.mesocycle = mesocycle;
         this.existingMicrocycles = existingMicrocycles;
         this.existingSessions = existingSessions;
         this.existingSessionExercises = existingSessionExercises;
         this.existingSets = existingSets;
+        // Set cycle-type-specific planning parameters
+        const { cycleType } = mesocycle;
+        if (cycleType === CycleType.Cut) {
+            this.firstMicrocycleRir = 3;
+            this.progressionInterval = 2;
+            this.skipDeload = false;
+        }
+        else if (cycleType === CycleType.Resensitization) {
+            this.firstMicrocycleRir = 3;
+            this.progressionInterval = 0;
+            this.skipDeload = true;
+        }
+        else {
+            this.firstMicrocycleRir = 4;
+            this.progressionInterval = 1;
+            this.skipDeload = false;
+        }
+        // Build volume landmark estimates from historical CTOs
+        this.muscleGroupToVolumeLandmarkMap = new Map(volumeCTOs.map((cto) => [cto._id, WorkoutVolumePlanningService.estimateVolumeLandmarks(cto)]));
         // Derive exercise map from CTOs
         this.exerciseMap = new Map(exerciseCTOs.map((cto) => [cto._id, cto]));
         // Derive equipment map from CTOs
         this.equipmentMap = new Map(exerciseCTOs.map((cto) => [cto.equipmentType._id, cto.equipmentType]));
         this.sessionMap = new Map(existingSessions.map((s) => [s._id, s]));
         this.sessionExerciseMap = new Map(existingSessionExercises.map((s) => [s._id, s]));
+        this.setMap = new Map(existingSets.map((s) => [s._id, s]));
         const existingMicrocyclesForMesocycle = existingMicrocycles
             .filter((m) => m.workoutMesocycleId === mesocycle._id)
             .sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
@@ -86,6 +124,15 @@ export default class WorkoutMesocyclePlanContext {
         this.sessionExercisesToCreate.push(sessionExercise);
         this.sessionExerciseMap.set(sessionExercise._id, sessionExercise);
     }
+    /**
+     * Adds sets to the context and updates the set map for O(1) lookup.
+     */
+    addSets(sets) {
+        this.setsToCreate.push(...sets);
+        for (const set of sets) {
+            this.setMap.set(set._id, set);
+        }
+    }
     /**
      * Stores the planned session -> exercises structure for the mesocycle and derives
      * the muscle-group-wide ordering used for set progression.

package/lib/services/workout/Mesocycle/WorkoutMesocyclePlanContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutMesocyclePlanContext.js","sourceRoot":"","sources":["../../../../src/services/workout/Mesocycle/WorkoutMesocyclePlanContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WorkoutMesocyclePlanContext.js","sourceRoot":"","sources":["../../../../src/services/workout/Mesocycle/WorkoutMesocyclePlanContext.ts"],"names":[],"mappings":"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"}

package/lib/services/workout/Mesocycle/WorkoutMesocyclePlanContext.ts

@@ -1,12 +1,16 @@
 import type { UUID } from 'crypto';
 import type { WorkoutExerciseCTO } from '../../../ctos/workout/WorkoutExerciseCTO.js';
+import type { WorkoutMuscleGroupVolumeCTO } from '../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
 import type { WorkoutEquipmentType } from '../../../documents/workout/WorkoutEquipmentType.js';
 import type { WorkoutExercise } from '../../../documents/workout/WorkoutExercise.js';
 import type { WorkoutMesocycle } from '../../../documents/workout/WorkoutMesocycle.js';
+import { CycleType } from '../../../documents/workout/WorkoutMesocycle.js';
 import type { WorkoutMicrocycle } from '../../../documents/workout/WorkoutMicrocycle.js';
 import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
 import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
 import type { WorkoutSet } from '../../../documents/workout/WorkoutSet.js';
+import type { WorkoutVolumeLandmarkEstimate } from '../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
+import WorkoutVolumePlanningService from '../util/VolumePlanning/WorkoutVolumePlanningService.js';
 
 /**
  * Central shared context for generating or updating a {@link WorkoutMesocycle}.
@@ -17,15 +21,28 @@ import type { WorkoutSet } from '../../../documents/workout/WorkoutSet.js';
  */
 export default class WorkoutMesocyclePlanContext {
   /**
-   * A constant for now that defines what the target RIR is for the first microcycle of every mesocycle,
-   * regardless of anything else.
+   * The target RIR for the first microcycle of the mesocycle. Varies by cycle
+   * type: MuscleGain starts at 4, Cut starts at 3, Resensitization stays at 3.
    */
-  public readonly FIRST_MICROCYCLE_RIR = 4;
+  public readonly firstMicrocycleRir: number;
+
+  /**
+   * Number of microcycles between each baseline set addition.
+   * MuscleGain = 1 (every microcycle), Cut = 2 (every other), Resensitization = 0 (never).
+   */
+  public readonly progressionInterval: number;
+
+  /**
+   * Whether this mesocycle type skips the deload microcycle. True for
+   * Resensitization cycles.
+   */
+  public readonly skipDeload: boolean;
 
   public readonly exerciseMap: Map<UUID, WorkoutExercise>;
   public readonly equipmentMap: Map<UUID, WorkoutEquipmentType>;
   public readonly sessionMap: Map<UUID, WorkoutSession>;
   public readonly sessionExerciseMap: Map<UUID, WorkoutSessionExercise>;
+  public readonly setMap: Map<UUID, WorkoutSet>;
 
   public readonly microcyclesToCreate: WorkoutMicrocycle[] = [];
   /**
@@ -52,6 +69,11 @@ export default class WorkoutMesocyclePlanContext {
    * ended up in.
    */
   public muscleGroupToExerciseCTOsMap: Map<UUID, WorkoutExerciseCTO[]> | undefined;
+  /**
+   * Maps muscle group ID to its estimated volume landmarks (MEV, MRV, MAV).
+   * Populated from WorkoutMuscleGroupVolumeCTOs when provided.
+   */
+  public muscleGroupToVolumeLandmarkMap: Map<UUID, WorkoutVolumeLandmarkEstimate>;
   public exerciseIdToSessionIndex: Map<UUID, number> | undefined;
 
   /**
@@ -60,11 +82,33 @@ export default class WorkoutMesocyclePlanContext {
   constructor(
     public mesocycle: WorkoutMesocycle,
     exerciseCTOs: WorkoutExerciseCTO[],
+    volumeCTOs: WorkoutMuscleGroupVolumeCTO[] = [],
     public existingMicrocycles: WorkoutMicrocycle[] = [],
     public existingSessions: WorkoutSession[] = [],
     public existingSessionExercises: WorkoutSessionExercise[] = [],
     public existingSets: WorkoutSet[] = []
   ) {
+    // Set cycle-type-specific planning parameters
+    const { cycleType } = mesocycle;
+    if (cycleType === CycleType.Cut) {
+      this.firstMicrocycleRir = 3;
+      this.progressionInterval = 2;
+      this.skipDeload = false;
+    } else if (cycleType === CycleType.Resensitization) {
+      this.firstMicrocycleRir = 3;
+      this.progressionInterval = 0;
+      this.skipDeload = true;
+    } else {
+      this.firstMicrocycleRir = 4;
+      this.progressionInterval = 1;
+      this.skipDeload = false;
+    }
+
+    // Build volume landmark estimates from historical CTOs
+    this.muscleGroupToVolumeLandmarkMap = new Map(
+      volumeCTOs.map((cto) => [cto._id, WorkoutVolumePlanningService.estimateVolumeLandmarks(cto)])
+    );
+
     // Derive exercise map from CTOs
     this.exerciseMap = new Map(exerciseCTOs.map((cto) => [cto._id, cto]));
 
@@ -75,6 +119,7 @@ export default class WorkoutMesocyclePlanContext {
 
     this.sessionMap = new Map(existingSessions.map((s) => [s._id, s]));
     this.sessionExerciseMap = new Map(existingSessionExercises.map((s) => [s._id, s]));
+    this.setMap = new Map(existingSets.map((s) => [s._id, s]));
 
     const existingMicrocyclesForMesocycle = existingMicrocycles
       .filter((m) => m.workoutMesocycleId === mesocycle._id)
@@ -106,6 +151,16 @@ export default class WorkoutMesocyclePlanContext {
     this.sessionExerciseMap.set(sessionExercise._id, sessionExercise);
   }
 
+  /**
+   * Adds sets to the context and updates the set map for O(1) lookup.
+   */
+  public addSets(sets: WorkoutSet[]): void {
+    this.setsToCreate.push(...sets);
+    for (const set of sets) {
+      this.setMap.set(set._id, set);
+    }
+  }
+
   /**
    * Stores the planned session -> exercises structure for the mesocycle and derives
    * the muscle-group-wide ordering used for set progression.