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

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

@@ -1,10 +1,9 @@
 import type { UUID } from 'crypto';
+import type { WorkoutMuscleGroupVolumeCTO, WorkoutVolumeLandmarkEstimate } from '../../../../ctos/workout/WorkoutMuscleGroupVolumeCTO.js';
 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)
@@ -17,8 +16,39 @@ import type WorkoutMesocyclePlanContext from '../../Mesocycle/WorkoutMesocyclePl
  * - {@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: boolean;
     private static readonly MAX_SETS_PER_EXERCISE;
     private static readonly MAX_SETS_PER_MUSCLE_GROUP_PER_SESSION;
+    /** Minimum average RSM required for a mesocycle to count toward MEV estimation. */
+    private static readonly MEV_RSM_THRESHOLD;
+    /** Default estimated MEV when no qualifying mesocycle history exists. Per-exercise value. */
+    private static readonly DEFAULT_MEV_PER_EXERCISE;
+    /** Minimum average performance score (or recovery presence) to count a mesocycle toward MRV estimation. */
+    private static readonly MRV_PERFORMANCE_THRESHOLD;
+    /** Extra sets added above the historical peak when no stressed mesocycles exist, to estimate MRV. */
+    private static readonly MRV_HEADROOM;
+    /** Default estimated MRV when no mesocycle history exists at all. Per-exercise value. */
+    private static readonly DEFAULT_MRV_PER_EXERCISE;
+    /** Maximum sets that can be added to a single exercise in one progression step. */
+    private static readonly MAX_SET_ADDITION_PER_EXERCISE;
+    /** Maximum total sets to distribute across a muscle group in one progression step. */
+    private static readonly MAX_TOTAL_SET_ADDITIONS;
     /**
      * Calculates the set plan for an entire microcycle.
      */
@@ -26,23 +56,143 @@ export default class WorkoutVolumePlanningService {
         exerciseIdToSetCount: Map<UUID, number>;
         recoveryExerciseIds: Set<UUID>;
     };
+    /**
+     * 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;
     /**
      * 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;
     /**
-     * Calculates the default number of sets for an exercise based on microcycle progression.
+     * Determines the start and end volume targets for a muscle group based on
+     * historical volume landmarks and cycle type.
      *
-     * 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.
+     * @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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Determines if the session containing the given exercise is already at the
+     * per-muscle-group-per-session cap, based on previous microcycle set counts.
+     *
+     * @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 sessionIsCapped;
+    /**
+     * 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;
+    /**
+     * Attempts to add sets to an exercise, respecting per-exercise, per-session, and
+     * per-addition caps. Mutates `exerciseIdToSetCount` in place.
      *
-     * 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).
+     * @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 calculateBaselineSetCount;
+    private static addSetsToExercise;
 }
 //# sourceMappingURL=WorkoutVolumePlanningService.d.ts.map

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

@@ -1 +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;IAoP5D;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;CA6BzC"}
+{"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;AAEnC,OAAO,KAAK,EACV,2BAA2B,EAC3B,6BAA6B,EAC9B,MAAM,yDAAyD,CAAC;AAEjE,OAAO,KAAK,2BAA2B,MAAM,gDAAgD,CAAC;AAW9F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IAC/C;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,+BAA+B,UAAS;IAE/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAK;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qCAAqC,CAAM;IAEnE,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAE9C,6FAA6F;IAC7F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAErD,2GAA2G;IAC3G,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAO;IAExD,qGAAqG;IACrG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAK;IAEzC,yFAAyF;IACzF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAErD,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,6BAA6B,CAAK;IAE1D,sFAAsF;IACtF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAK;IAEpD;;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;;;;;;OAMG;IACH,MAAM,CAAC,uBAAuB,CAC5B,SAAS,EAAE,2BAA2B,GACrC,6BAA6B;IA+ChC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,6CAA6C;IAqG5D;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAuC7C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;IA4CzC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAM/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAuD5C;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAwCvC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAgEzC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAkCxC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAuB9B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAoBjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;CA8BjC"}