@aneuhold/core-ts-db-lib 4.0.3 → 4.1.0

package/lib/services/workout/SessionExercise/WorkoutSessionExerciseService.ts

@@ -0,0 +1,77 @@
+import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
+import WorkoutSFRService from '../util/SFR/WorkoutSFRService.js';
+
+/**
+ * A service for handling operations related to {@link WorkoutSessionExercise}s.
+ */
+export default class WorkoutSessionExerciseService {
+  /**
+   * Calculates the total Raw Stimulus Magnitude for a specific exercise within a session.
+   *
+   * @param sessionExercise The workout session exercise.
+   */
+  static getRsmTotal(sessionExercise: WorkoutSessionExercise): number | null {
+    return WorkoutSFRService.getRsmTotal(sessionExercise.rsm);
+  }
+
+  /**
+   * Calculates the total fatigue score for a specific exercise within a session.
+   *
+   * @param sessionExercise The workout session exercise.
+   */
+  static getFatigueTotal(sessionExercise: WorkoutSessionExercise): number | null {
+    return WorkoutSFRService.getFatigueTotal(sessionExercise.fatigue);
+  }
+
+  /**
+   * Calculates the Stimulus to Fatigue Ratio (SFR) for a specific exercise.
+   *
+   * @param sessionExercise The workout session exercise.
+   */
+  static getSFR(sessionExercise: WorkoutSessionExercise): number | null {
+    return WorkoutSFRService.getSFR(sessionExercise.rsm, sessionExercise.fatigue);
+  }
+
+  /**
+   * Uses the soreness/performance table from the workout model notes to recommend whether to add
+   * sets next microcycle or employ recovery sessions.
+   *
+   * Interpretation:
+   * - Returns `-1` when recovery sessions should be employed.
+   * - Returns `0` when no sets should be added.
+   * - Returns a non-negative integer when sets should be added.
+   * - Returns `null` when insufficient data is available.
+   * 
+   * The table is:
+   * 
+   * | Soreness Score ↓ \ Performance Score → | 0 | 1 | 2 | 3 |
+     |---|---|---|---|---|
+     | **0** | Add 1–3 sets | Add 0–2 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+     | **1** | Add 1–2 sets | Add 0–1 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+     | **2** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+     | **3** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+   */
+  static getRecommendedSetAdditionsOrRecovery(
+    workoutSessionExercise: WorkoutSessionExercise
+  ): number | null {
+    const { performanceScore, sorenessScore } = workoutSessionExercise;
+    if (sorenessScore == null || performanceScore == null) {
+      return null;
+    }
+
+    // Table mapping (sorenessScore rows, performanceScore columns).
+    // Values are representative set additions (midpoint of table ranges), or -1 for recovery.
+    const table: number[][] = [
+      // Soreness 0: [Add 1-3, Add 0-2, Do not add, Recovery]
+      [2, 1, 0, -1],
+      // Soreness 1: [Add 1-2, Add 0-1, Do not add, Recovery]
+      [1, 0, 0, -1],
+      // Soreness 2: [Do not add, Do not add, Do not add, Recovery]
+      [0, 0, 0, -1],
+      // Soreness 3: [Do not add, Do not add, Do not add, Recovery]
+      [0, 0, 0, -1]
+    ];
+
+    return table[sorenessScore]?.[performanceScore] ?? null;
+  }
+}

package/lib/services/workout/Set/WorkoutSetService.d.ts

@@ -0,0 +1,36 @@
+import type { WorkoutExercise } from '../../../documents/workout/WorkoutExercise.js';
+import type { WorkoutExerciseCalibration } from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
+import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
+import type WorkoutMesocyclePlanContext from '../Mesocycle/WorkoutMesocyclePlanContext.js';
+export default class WorkoutSetService {
+    /**
+     * Generates a list of workout sets for a given session exercise based on progression logic.
+     *
+     * This handles the "micro" decisions of load selection:
+     * - Calculating the initial target weight/reps based on microcycle progression.
+     * - Handling intra-session fatigue (dropping reps/weight across sets).
+     * - Applying Deload phase modifications (cutting volume/intensity).
+     */
+    static generateSetsForSessionExercise({ context, exercise, calibration, session, sessionExercise, microcycleIndex, sessionIndex, setCount, targetRir, isDeloadMicrocycle }: {
+        context: WorkoutMesocyclePlanContext;
+        exercise: WorkoutExercise;
+        calibration: WorkoutExerciseCalibration;
+        session: WorkoutSession;
+        sessionExercise: WorkoutSessionExercise;
+        microcycleIndex: number;
+        sessionIndex: number;
+        setCount: number;
+        targetRir: number;
+        isDeloadMicrocycle: boolean;
+    }): void;
+    /**
+     * Generates the planned reps and weight for a specific set within a session exercise, only
+     * taking into account simple -2 reps drop per set logic, and deload modifications.
+     *
+     * This needs to be checked with the source material to see if it needs to be adjusted based
+     * on actual reps performed in previous sets.
+     */
+    private static generateSetRepsAndWeight;
+}
+//# sourceMappingURL=WorkoutSetService.d.ts.map

package/lib/services/workout/Set/WorkoutSetService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSetService.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/Set/WorkoutSetService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,eAAe,EAChB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAC;AAC3G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAInG,OAAO,KAAK,2BAA2B,MAAM,6CAA6C,CAAC;AAE3F,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,8BAA8B,CAAC,EACpC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,OAAO,EACP,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,kBAAkB,EACnB,EAAE;QACD,OAAO,EAAE,2BAA2B,CAAC;QACrC,QAAQ,EAAE,eAAe,CAAC;QAC1B,WAAW,EAAE,0BAA0B,CAAC;QACxC,OAAO,EAAE,cAAc,CAAC;QACxB,eAAe,EAAE,sBAAsB,CAAC;QACxC,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,kBAAkB,EAAE,OAAO,CAAC;KAC7B,GAAG,IAAI;IAoDR;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CAiDxC"}

package/lib/services/workout/Set/WorkoutSetService.js

@@ -0,0 +1,90 @@
+import { WorkoutSetSchema } from '../../../documents/workout/WorkoutSet.js';
+import WorkoutEquipmentTypeService from '../EquipmentType/WorkoutEquipmentTypeService.js';
+import WorkoutExerciseService from '../Exercise/WorkoutExerciseService.js';
+export default class WorkoutSetService {
+    /**
+     * Generates a list of workout sets for a given session exercise based on progression logic.
+     *
+     * This handles the "micro" decisions of load selection:
+     * - Calculating the initial target weight/reps based on microcycle progression.
+     * - Handling intra-session fatigue (dropping reps/weight across sets).
+     * - Applying Deload phase modifications (cutting volume/intensity).
+     */
+    static generateSetsForSessionExercise({ context, exercise, calibration, session, sessionExercise, microcycleIndex, sessionIndex, setCount, targetRir, isDeloadMicrocycle }) {
+        const equipment = context.equipmentMap.get(exercise.workoutEquipmentTypeId);
+        if (!equipment) {
+            throw new Error(`Equipment type not found for exercise ${exercise._id}, ${exercise.exerciseName}`);
+        }
+        const sets = [];
+        // Calculate progressed targets for the first set
+        const { targetWeight: firstSetWeight, targetReps: firstSetReps } = WorkoutExerciseService.calculateTargetRepsAndWeightForFirstSet({
+            exercise,
+            calibration,
+            equipment,
+            microcycleIndex,
+            firstMicrocycleRir: context.FIRST_MICROCYCLE_RIR
+        });
+        for (let setIndex = 0; setIndex < setCount; setIndex++) {
+            const { plannedReps, plannedWeight } = this.generateSetRepsAndWeight(
+            // If there is a previous set, base off that, otherwise use first set targets
+            sets[setIndex - 1]?.plannedReps || firstSetReps, sets[setIndex - 1]?.plannedWeight || firstSetWeight, setIndex, exercise.repRange, equipment, {
+                isDeloadMicrocycle,
+                sessionIndex,
+                plannedSessionCountPerMicrocycle: context.mesocycle.plannedSessionCountPerMicrocycle
+            });
+            const workoutSet = WorkoutSetSchema.parse({
+                userId: exercise.userId,
+                workoutExerciseId: exercise._id,
+                workoutSessionId: session._id,
+                workoutSessionExerciseId: sessionExercise._id,
+                plannedReps,
+                plannedWeight,
+                plannedRir: targetRir,
+                exerciseProperties: calibration.exerciseProperties
+            });
+            sets.push(workoutSet);
+        }
+        context.setsToCreate.push(...sets);
+    }
+    /**
+     * Generates the planned reps and weight for a specific set within a session exercise, only
+     * taking into account simple -2 reps drop per set logic, and deload modifications.
+     *
+     * This needs to be checked with the source material to see if it needs to be adjusted based
+     * on actual reps performed in previous sets.
+     */
+    static generateSetRepsAndWeight(firstSetOrPreviousSetReps, firstSetOrPreviousSetWeight, setIndex, repRange, equipment, deloadInfo) {
+        const repRangeValues = WorkoutExerciseService.getRepRangeValues(repRange);
+        let currentReps = firstSetOrPreviousSetReps;
+        let currentWeight = firstSetOrPreviousSetWeight;
+        // Ideally, drop 2 reps per set within the session (19 -> 17 -> 15, etc.)
+        // But if that would go below the min reps, keep it at min reps.
+        if (firstSetOrPreviousSetReps - 2 < repRangeValues.min && setIndex > 0) {
+            // Reduce weight by 2% using the same technique as progression
+            const twoPercentDecrease = currentWeight / 1.02;
+            const reducedWeight = WorkoutEquipmentTypeService.findNearestWeight(equipment, twoPercentDecrease, 'down');
+            if (reducedWeight !== null) {
+                currentWeight = reducedWeight;
+            }
+            else if (firstSetOrPreviousSetReps - 2 > 5) {
+                // If we can't reduce weight, but we can reduce reps without going too low,
+                // then do that.
+                currentReps = firstSetOrPreviousSetReps - 2;
+            }
+        }
+        else if (setIndex > 0) {
+            currentReps = firstSetOrPreviousSetReps - 2;
+        }
+        // Apply deload modifications, but only if the set is the first in the session
+        if (deloadInfo.isDeloadMicrocycle && setIndex === 0) {
+            currentReps = Math.floor(firstSetOrPreviousSetReps / 2);
+            // First half of deload microcycle: same weight, half reps/sets
+            // Second half: half weight too
+            if (deloadInfo.sessionIndex >= Math.floor(deloadInfo.plannedSessionCountPerMicrocycle / 2)) {
+                currentWeight = Math.floor(currentWeight / 2);
+            }
+        }
+        return { plannedReps: currentReps, plannedWeight: currentWeight };
+    }
+}
+//# sourceMappingURL=WorkoutSetService.js.map

package/lib/services/workout/Set/WorkoutSetService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSetService.js","sourceRoot":"","sources":["../../../../src/services/workout/Set/WorkoutSetService.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAmB,MAAM,0CAA0C,CAAC;AAC7F,OAAO,2BAA2B,MAAM,iDAAiD,CAAC;AAC1F,OAAO,sBAAsB,MAAM,uCAAuC,CAAC;AAG3E,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,8BAA8B,CAAC,EACpC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,OAAO,EACP,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,kBAAkB,EAYnB;QACC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;QAC5E,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,yCAAyC,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,YAAY,EAAE,CAClF,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAiB,EAAE,CAAC;QAE9B,iDAAiD;QACjD,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,GAC9D,sBAAsB,CAAC,uCAAuC,CAAC;YAC7D,QAAQ;YACR,WAAW;YACX,SAAS;YACT,eAAe;YACf,kBAAkB,EAAE,OAAO,CAAC,oBAAoB;SACjD,CAAC,CAAC;QAEL,KAAK,IAAI,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC;YACvD,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,wBAAwB;YAClE,6EAA6E;YAC7E,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,WAAW,IAAI,YAAY,EAC/C,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,aAAa,IAAI,cAAc,EACnD,QAAQ,EACR,QAAQ,CAAC,QAAQ,EACjB,SAAS,EACT;gBACE,kBAAkB;gBAClB,YAAY;gBACZ,gCAAgC,EAAE,OAAO,CAAC,SAAS,CAAC,gCAAgC;aACrF,CACF,CAAC;YAEF,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC;gBACxC,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,iBAAiB,EAAE,QAAQ,CAAC,GAAG;gBAC/B,gBAAgB,EAAE,OAAO,CAAC,GAAG;gBAC7B,wBAAwB,EAAE,eAAe,CAAC,GAAG;gBAC7C,WAAW;gBACX,aAAa;gBACb,UAAU,EAAE,SAAS;gBACrB,kBAAkB,EAAE,WAAW,CAAC,kBAAkB;aACnD,CAAC,CAAC;YAEH,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,wBAAwB,CACrC,yBAAiC,EACjC,2BAAmC,EACnC,QAAgB,EAChB,QAA0B,EAC1B,SAA+B,EAC/B,UAIC;QAED,MAAM,cAAc,GAAG,sBAAsB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC1E,IAAI,WAAW,GAAG,yBAAyB,CAAC;QAC5C,IAAI,aAAa,GAAG,2BAA2B,CAAC;QAEhD,yEAAyE;QACzE,gEAAgE;QAChE,IAAI,yBAAyB,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACvE,8DAA8D;YAC9D,MAAM,kBAAkB,GAAG,aAAa,GAAG,IAAI,CAAC;YAChD,MAAM,aAAa,GAAG,2BAA2B,CAAC,iBAAiB,CACjE,SAAS,EACT,kBAAkB,EAClB,MAAM,CACP,CAAC;YACF,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;gBAC3B,aAAa,GAAG,aAAa,CAAC;YAChC,CAAC;iBAAM,IAAI,yBAAyB,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,2EAA2E;gBAC3E,gBAAgB;gBAChB,WAAW,GAAG,yBAAyB,GAAG,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;aAAM,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACxB,WAAW,GAAG,yBAAyB,GAAG,CAAC,CAAC;QAC9C,CAAC;QAED,8EAA8E;QAC9E,IAAI,UAAU,CAAC,kBAAkB,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;YACpD,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,yBAAyB,GAAG,CAAC,CAAC,CAAC;YACxD,+DAA+D;YAC/D,+BAA+B;YAC/B,IAAI,UAAU,CAAC,YAAY,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,gCAAgC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC3F,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;IACpE,CAAC;CACF"}

package/lib/services/workout/Set/WorkoutSetService.ts

@@ -0,0 +1,153 @@
+import type { WorkoutEquipmentType } from '../../../documents/workout/WorkoutEquipmentType.js';
+import type {
+  ExerciseRepRange,
+  WorkoutExercise
+} from '../../../documents/workout/WorkoutExercise.js';
+import type { WorkoutExerciseCalibration } from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
+import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
+import { WorkoutSetSchema, type WorkoutSet } from '../../../documents/workout/WorkoutSet.js';
+import WorkoutEquipmentTypeService from '../EquipmentType/WorkoutEquipmentTypeService.js';
+import WorkoutExerciseService from '../Exercise/WorkoutExerciseService.js';
+import type WorkoutMesocyclePlanContext from '../Mesocycle/WorkoutMesocyclePlanContext.js';
+
+export default class WorkoutSetService {
+  /**
+   * Generates a list of workout sets for a given session exercise based on progression logic.
+   *
+   * This handles the "micro" decisions of load selection:
+   * - Calculating the initial target weight/reps based on microcycle progression.
+   * - Handling intra-session fatigue (dropping reps/weight across sets).
+   * - Applying Deload phase modifications (cutting volume/intensity).
+   */
+  static generateSetsForSessionExercise({
+    context,
+    exercise,
+    calibration,
+    session,
+    sessionExercise,
+    microcycleIndex,
+    sessionIndex,
+    setCount,
+    targetRir,
+    isDeloadMicrocycle
+  }: {
+    context: WorkoutMesocyclePlanContext;
+    exercise: WorkoutExercise;
+    calibration: WorkoutExerciseCalibration;
+    session: WorkoutSession;
+    sessionExercise: WorkoutSessionExercise;
+    microcycleIndex: number;
+    sessionIndex: number;
+    setCount: number;
+    targetRir: number;
+    isDeloadMicrocycle: boolean;
+  }): void {
+    const equipment = context.equipmentMap.get(exercise.workoutEquipmentTypeId);
+    if (!equipment) {
+      throw new Error(
+        `Equipment type not found for exercise ${exercise._id}, ${exercise.exerciseName}`
+      );
+    }
+
+    const sets: WorkoutSet[] = [];
+
+    // Calculate progressed targets for the first set
+    const { targetWeight: firstSetWeight, targetReps: firstSetReps } =
+      WorkoutExerciseService.calculateTargetRepsAndWeightForFirstSet({
+        exercise,
+        calibration,
+        equipment,
+        microcycleIndex,
+        firstMicrocycleRir: context.FIRST_MICROCYCLE_RIR
+      });
+
+    for (let setIndex = 0; setIndex < setCount; setIndex++) {
+      const { plannedReps, plannedWeight } = this.generateSetRepsAndWeight(
+        // If there is a previous set, base off that, otherwise use first set targets
+        sets[setIndex - 1]?.plannedReps || firstSetReps,
+        sets[setIndex - 1]?.plannedWeight || firstSetWeight,
+        setIndex,
+        exercise.repRange,
+        equipment,
+        {
+          isDeloadMicrocycle,
+          sessionIndex,
+          plannedSessionCountPerMicrocycle: context.mesocycle.plannedSessionCountPerMicrocycle
+        }
+      );
+
+      const workoutSet = WorkoutSetSchema.parse({
+        userId: exercise.userId,
+        workoutExerciseId: exercise._id,
+        workoutSessionId: session._id,
+        workoutSessionExerciseId: sessionExercise._id,
+        plannedReps,
+        plannedWeight,
+        plannedRir: targetRir,
+        exerciseProperties: calibration.exerciseProperties
+      });
+
+      sets.push(workoutSet);
+    }
+
+    context.setsToCreate.push(...sets);
+  }
+
+  /**
+   * Generates the planned reps and weight for a specific set within a session exercise, only
+   * taking into account simple -2 reps drop per set logic, and deload modifications.
+   *
+   * This needs to be checked with the source material to see if it needs to be adjusted based
+   * on actual reps performed in previous sets.
+   */
+  private static generateSetRepsAndWeight(
+    firstSetOrPreviousSetReps: number,
+    firstSetOrPreviousSetWeight: number,
+    setIndex: number,
+    repRange: ExerciseRepRange,
+    equipment: WorkoutEquipmentType,
+    deloadInfo: {
+      isDeloadMicrocycle: boolean;
+      sessionIndex: number;
+      plannedSessionCountPerMicrocycle: number;
+    }
+  ) {
+    const repRangeValues = WorkoutExerciseService.getRepRangeValues(repRange);
+    let currentReps = firstSetOrPreviousSetReps;
+    let currentWeight = firstSetOrPreviousSetWeight;
+
+    // Ideally, drop 2 reps per set within the session (19 -> 17 -> 15, etc.)
+    // But if that would go below the min reps, keep it at min reps.
+    if (firstSetOrPreviousSetReps - 2 < repRangeValues.min && setIndex > 0) {
+      // Reduce weight by 2% using the same technique as progression
+      const twoPercentDecrease = currentWeight / 1.02;
+      const reducedWeight = WorkoutEquipmentTypeService.findNearestWeight(
+        equipment,
+        twoPercentDecrease,
+        'down'
+      );
+      if (reducedWeight !== null) {
+        currentWeight = reducedWeight;
+      } else if (firstSetOrPreviousSetReps - 2 > 5) {
+        // If we can't reduce weight, but we can reduce reps without going too low,
+        // then do that.
+        currentReps = firstSetOrPreviousSetReps - 2;
+      }
+    } else if (setIndex > 0) {
+      currentReps = firstSetOrPreviousSetReps - 2;
+    }
+
+    // Apply deload modifications, but only if the set is the first in the session
+    if (deloadInfo.isDeloadMicrocycle && setIndex === 0) {
+      currentReps = Math.floor(firstSetOrPreviousSetReps / 2);
+      // First half of deload microcycle: same weight, half reps/sets
+      // Second half: half weight too
+      if (deloadInfo.sessionIndex >= Math.floor(deloadInfo.plannedSessionCountPerMicrocycle / 2)) {
+        currentWeight = Math.floor(currentWeight / 2);
+      }
+    }
+
+    return { plannedReps: currentReps, plannedWeight: currentWeight };
+  }
+}

package/lib/services/workout/util/SFR/WorkoutSFRService.d.ts

@@ -0,0 +1,29 @@
+import type { Fatigue } from '../../../../embedded-types/workout/Fatigue.js';
+import type { RSM } from '../../../../embedded-types/workout/Rsm.js';
+/**
+ * A service for handling Stimulus to Fatigue Ratio (SFR) calculations.
+ *
+ * This service works with any object that has RSM and Fatigue data.
+ */
+export default class WorkoutSFRService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude.
+     *
+     * @param rsm The RSM data.
+     */
+    static getRsmTotal(rsm: RSM | null | undefined): number | null;
+    /**
+     * Calculates the total fatigue score.
+     *
+     * @param fatigue The fatigue data.
+     */
+    static getFatigueTotal(fatigue: Fatigue | null | undefined): number | null;
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR).
+     *
+     * @param rsm The RSM data.
+     * @param fatigue The fatigue data.
+     */
+    static getSFR(rsm: RSM | null | undefined, fatigue: Fatigue | null | undefined): number | null;
+}
+//# sourceMappingURL=WorkoutSFRService.d.ts.map

package/lib/services/workout/util/SFR/WorkoutSFRService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSFRService.d.ts","sourceRoot":"","sources":["../../../../../src/services/workout/util/SFR/WorkoutSFRService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+CAA+C,CAAC;AAC7E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,2CAA2C,CAAC;AAErE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACpC;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI;IAO9D;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI;IAc1E;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI;CAc/F"}

package/lib/services/workout/util/SFR/WorkoutSFRService.js

@@ -0,0 +1,50 @@
+/**
+ * A service for handling Stimulus to Fatigue Ratio (SFR) calculations.
+ *
+ * This service works with any object that has RSM and Fatigue data.
+ */
+export default class WorkoutSFRService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude.
+     *
+     * @param rsm The RSM data.
+     */
+    static getRsmTotal(rsm) {
+        if (!rsm || rsm.mindMuscleConnection == null || rsm.pump == null || rsm.disruption == null) {
+            return null;
+        }
+        return rsm.mindMuscleConnection + rsm.pump + rsm.disruption;
+    }
+    /**
+     * Calculates the total fatigue score.
+     *
+     * @param fatigue The fatigue data.
+     */
+    static getFatigueTotal(fatigue) {
+        if (!fatigue ||
+            fatigue.jointAndTissueDisruption == null ||
+            fatigue.perceivedEffort == null ||
+            fatigue.unusedMusclePerformance == null) {
+            return null;
+        }
+        return (fatigue.jointAndTissueDisruption + fatigue.perceivedEffort + fatigue.unusedMusclePerformance);
+    }
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR).
+     *
+     * @param rsm The RSM data.
+     * @param fatigue The fatigue data.
+     */
+    static getSFR(rsm, fatigue) {
+        const rsmTotal = this.getRsmTotal(rsm);
+        const fatigueTotal = this.getFatigueTotal(fatigue);
+        if (rsmTotal === null || fatigueTotal === null) {
+            return null;
+        }
+        if (fatigueTotal === 0) {
+            return rsmTotal;
+        }
+        return rsmTotal / fatigueTotal;
+    }
+}
+//# sourceMappingURL=WorkoutSFRService.js.map

package/lib/services/workout/util/SFR/WorkoutSFRService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSFRService.js","sourceRoot":"","sources":["../../../../../src/services/workout/util/SFR/WorkoutSFRService.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACpC;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,GAA2B;QAC5C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,oBAAoB,IAAI,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,GAAG,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YAC3F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,CAAC,oBAAoB,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,OAAmC;QACxD,IACE,CAAC,OAAO;YACR,OAAO,CAAC,wBAAwB,IAAI,IAAI;YACxC,OAAO,CAAC,eAAe,IAAI,IAAI;YAC/B,OAAO,CAAC,uBAAuB,IAAI,IAAI,EACvC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CACL,OAAO,CAAC,wBAAwB,GAAG,OAAO,CAAC,eAAe,GAAG,OAAO,CAAC,uBAAuB,CAC7F,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,GAA2B,EAAE,OAAmC;QAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAEnD,IAAI,QAAQ,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,OAAO,QAAQ,GAAG,YAAY,CAAC;IACjC,CAAC;CACF"}

package/lib/services/workout/util/SFR/WorkoutSFRService.ts

@@ -0,0 +1,61 @@
+import type { Fatigue } from '../../../../embedded-types/workout/Fatigue.js';
+import type { RSM } from '../../../../embedded-types/workout/Rsm.js';
+
+/**
+ * A service for handling Stimulus to Fatigue Ratio (SFR) calculations.
+ *
+ * This service works with any object that has RSM and Fatigue data.
+ */
+export default class WorkoutSFRService {
+  /**
+   * Calculates the total Raw Stimulus Magnitude.
+   *
+   * @param rsm The RSM data.
+   */
+  static getRsmTotal(rsm: RSM | null | undefined): number | null {
+    if (!rsm || rsm.mindMuscleConnection == null || rsm.pump == null || rsm.disruption == null) {
+      return null;
+    }
+    return rsm.mindMuscleConnection + rsm.pump + rsm.disruption;
+  }
+
+  /**
+   * Calculates the total fatigue score.
+   *
+   * @param fatigue The fatigue data.
+   */
+  static getFatigueTotal(fatigue: Fatigue | null | undefined): number | null {
+    if (
+      !fatigue ||
+      fatigue.jointAndTissueDisruption == null ||
+      fatigue.perceivedEffort == null ||
+      fatigue.unusedMusclePerformance == null
+    ) {
+      return null;
+    }
+    return (
+      fatigue.jointAndTissueDisruption + fatigue.perceivedEffort + fatigue.unusedMusclePerformance
+    );
+  }
+
+  /**
+   * Calculates the Stimulus to Fatigue Ratio (SFR).
+   *
+   * @param rsm The RSM data.
+   * @param fatigue The fatigue data.
+   */
+  static getSFR(rsm: RSM | null | undefined, fatigue: Fatigue | null | undefined): number | null {
+    const rsmTotal = this.getRsmTotal(rsm);
+    const fatigueTotal = this.getFatigueTotal(fatigue);
+
+    if (rsmTotal === null || fatigueTotal === null) {
+      return null;
+    }
+
+    if (fatigueTotal === 0) {
+      return rsmTotal;
+    }
+
+    return rsmTotal / fatigueTotal;
+  }
+}

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

@@ -0,0 +1,48 @@
+import type { UUID } from 'crypto';
+import type WorkoutMesocyclePlanContext from '../../Mesocycle/WorkoutMesocyclePlanContext.js';
+/**
+ * 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)
+ * - Handle recovery exercise identification
+ * - Enforce volume limits (per exercise, per muscle group per session)
+ *
+ * RELATED SERVICES:
+ * - {@link WorkoutMicrocycleService} - Calls this to get set plans before generating sessions
+ * - {@link WorkoutSessionService} - Uses the output to generate actual sessions
+ * - {@link WorkoutSessionExerciseService} - Used to calculate SFR and recovery recommendations
+ */
+export default class WorkoutVolumePlanningService {
+    private static readonly MAX_SETS_PER_EXERCISE;
+    private static readonly MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION;
+    /**
+     * Calculates the set plan for an entire microcycle.
+     */
+    static calculateSetPlanForMicrocycle(context: WorkoutMesocyclePlanContext, microcycleIndex: number, isDeloadMicrocycle: boolean): {
+        exerciseIdToSetCount: Map<UUID, number>;
+        recoveryExerciseIds: Set<UUID>;
+    };
+    /**
+     * 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.
+     */
+    private static calculateSetCountForEachExerciseInMuscleGroup;
+    /**
+     * 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.
+     *
+     * 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).
+     */
+    private static calculateBaselineSetCount;
+}
+//# sourceMappingURL=WorkoutVolumePlanningService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutVolumePlanningService.d.ts","sourceRoot":"","sources":["../../../../../src/services/workout/util/VolumePlanning/WorkoutVolumePlanningService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnC,OAAO,KAAK,2BAA2B,MAAM,gDAAgD,CAAC;AAG9F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IAC/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAK;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qCAAqC,CAAM;IAEnE;;OAEG;IACH,MAAM,CAAC,6BAA6B,CAClC,OAAO,EAAE,2BAA2B,EACpC,eAAe,EAAE,MAAM,EACvB,kBAAkB,EAAE,OAAO,GAC1B;QAAE,oBAAoB,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAAC,mBAAmB,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;KAAE;IA4B9E;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,6CAA6C;IAwO5D;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;CA6BzC"}