@dgpholdings/greatoak-shared 1.2.58 → 1.2.59

package/dist/utils/scoringWorkout/computeMuscleFatigueMap.d.ts

@@ -12,6 +12,7 @@
  *   P2-7  Age          — recovery slows with age (< 35 → 1.0×, > 55 → 0.85×)
  *   P2-8  Gender       — females recover slightly faster (1.05×)
  *   P2-9  fitnessLevel — sedentary 0.8× → very-active 1.15×
+ *   P3-7  Weekly volume — muscles trained multiple times this week recover slower
  *   P3-8  Muscle group — small muscles (biceps) recover 1.4× faster than legs (0.80×)
  *
  * Accumulation model:

package/dist/utils/scoringWorkout/computeMuscleFatigueMap.js

@@ -13,6 +13,7 @@
  *   P2-7  Age          — recovery slows with age (< 35 → 1.0×, > 55 → 0.85×)
  *   P2-8  Gender       — females recover slightly faster (1.05×)
  *   P2-9  fitnessLevel — sedentary 0.8× → very-active 1.15×
+ *   P3-7  Weekly volume — muscles trained multiple times this week recover slower
  *   P3-8  Muscle group — small muscles (biceps) recover 1.4× faster than legs (0.80×)
  *
  * Accumulation model:
@@ -79,6 +80,35 @@ function getMuscleRecoveryRate(muscle) {
     return (_a = MUSCLE_RECOVERY_RATE[muscle]) !== null && _a !== void 0 ? _a : 1.0;
 }
 // ---------------------------------------------------------------------------
+// P3-7: Weekly volume recovery modifier
+//
+// A muscle trained multiple times this week is carrying accumulated fatigue
+// beyond what any single session decay captures. High weekly volume slows
+// the effective recovery rate for that muscle.
+//
+// Formula: each session beyond the first (~80 score units) reduces recovery
+// rate by 5%, up to a 40% maximum reduction.
+//
+//   1 session  (~80):  0%  reduction → 1.00× multiplier
+//   2 sessions (~160): 5%  reduction → 0.95×
+//   3 sessions (~240): 10% reduction → 0.90×
+//   5 sessions (~400): 20% reduction → 0.80×
+//   9+ sessions (cap): 40% reduction → 0.60×
+// ---------------------------------------------------------------------------
+const WEEKLY_VOLUME_BASELINE = 80; // ~1 normal session score
+const WEEKLY_VOLUME_STEP = 80; // score units per step
+const WEEKLY_VOLUME_REDUCTION_PER_STEP = 0.05; // 5% per additional session
+const WEEKLY_VOLUME_MAX_REDUCTION = 0.40;
+function getWeeklyVolumeMultiplier(muscle, weeklyVolume) {
+    var _a;
+    const total = (_a = weeklyVolume[muscle]) !== null && _a !== void 0 ? _a : 0;
+    if (total <= WEEKLY_VOLUME_BASELINE)
+        return 1.0;
+    const steps = (total - WEEKLY_VOLUME_BASELINE) / WEEKLY_VOLUME_STEP;
+    const reduction = Math.min(WEEKLY_VOLUME_MAX_REDUCTION, steps * WEEKLY_VOLUME_REDUCTION_PER_STEP);
+    return 1.0 - reduction;
+}
+// ---------------------------------------------------------------------------
 // Core recovery formula
 // ---------------------------------------------------------------------------
 function calculateRecoveryFatigue(originalFatigue, hoursSinceWorkout, recoveryMultiplier = 1.0) {
@@ -124,7 +154,7 @@ const RECOVERY_WINDOW_HOURS = 168; // 7 days
  * @returns              Record<muscleKey, { fatigue 0–100, lastWorked }>
  */
 function computeMuscleFatigueMap(exercises, scoreHistory, user, currentDate = new Date()) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     // Build combined user recovery multiplier (P2-7, P2-8, P2-9)
     let userRecoveryMultiplier = 1.0;
     if (user) {
@@ -137,6 +167,27 @@ function computeMuscleFatigueMap(exercises, scoreHistory, user, currentDate = ne
                 ((_c = FITNESS_RECOVERY_SCALE[(_b = user.fitnessLevel) !== null && _b !== void 0 ? _b : "moderately-active"]) !== null && _c !== void 0 ? _c : 1.0);
     }
     const cutoffTime = currentDate.getTime() - RECOVERY_WINDOW_HOURS * 3600000;
+    const weekCutoff = currentDate.getTime() - 7 * 24 * 3600000; // same as RECOVERY_WINDOW_HOURS
+    // P3-7: First pass — compute weekly accumulated score per muscle across ALL exercises.
+    // This captures "chest trained 3× this week" even when each session appears independent.
+    const weeklyVolume = {};
+    for (const { exerciseId, recordScore } of scoreHistory) {
+        const exercise = exercises[exerciseId];
+        if (!exercise)
+            continue;
+        const weeklyScore = recordScore
+            .filter((r) => r.recordDate >= weekCutoff)
+            .reduce((sum, r) => sum + r.score, 0);
+        if (weeklyScore === 0)
+            continue;
+        for (const muscle of (_d = exercise.primaryMuscles) !== null && _d !== void 0 ? _d : []) {
+            weeklyVolume[muscle] = ((_e = weeklyVolume[muscle]) !== null && _e !== void 0 ? _e : 0) + weeklyScore;
+        }
+        for (const muscle of (_f = exercise.secondaryMuscles) !== null && _f !== void 0 ? _f : []) {
+            // Secondary muscles receive 35% of the stimulus
+            weeklyVolume[muscle] = ((_g = weeklyVolume[muscle]) !== null && _g !== void 0 ? _g : 0) + weeklyScore * 0.35;
+        }
+    }
     const internalMap = new Map();
     for (const { exerciseId, recordScore } of scoreHistory) {
         const exercise = exercises[exerciseId];
@@ -150,14 +201,17 @@ function computeMuscleFatigueMap(exercises, scoreHistory, user, currentDate = ne
             const hasRealMuscleScores = record.muscleScores && Object.keys(record.muscleScores).length > 0;
             if (hasRealMuscleScores) {
                 const allMuscles = new Set([
-                    ...((_d = exercise.primaryMuscles) !== null && _d !== void 0 ? _d : []),
-                    ...((_e = exercise.secondaryMuscles) !== null && _e !== void 0 ? _e : []),
+                    ...((_h = exercise.primaryMuscles) !== null && _h !== void 0 ? _h : []),
+                    ...((_j = exercise.secondaryMuscles) !== null && _j !== void 0 ? _j : []),
                 ]);
                 for (const muscle of allMuscles) {
-                    const baseFatigue = (_f = record.muscleScores[muscle]) !== null && _f !== void 0 ? _f : 0;
+                    const baseFatigue = (_k = record.muscleScores[muscle]) !== null && _k !== void 0 ? _k : 0;
                     if (baseFatigue <= 0)
                         continue;
-                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    // P3-7: weekly volume slows recovery for heavily-trained muscles
+                    const multiplier = userRecoveryMultiplier
+                        * getMuscleRecoveryRate(muscle)
+                        * getWeeklyVolumeMultiplier(muscle, weeklyVolume);
                     const remaining = calculateRecoveryFatigue(baseFatigue, hoursSince, multiplier);
                     if (remaining > 0)
                         updateEntry(internalMap, muscle, remaining, workoutDate, true);
@@ -170,16 +224,20 @@ function computeMuscleFatigueMap(exercises, scoreHistory, user, currentDate = ne
                 const intensityFraction = record.score <= MIN_MEANINGFUL_SCORE
                     ? (record.score / MIN_MEANINGFUL_SCORE) * 0.3
                     : ((record.score - MIN_MEANINGFUL_SCORE) / (MAX_SCORE - MIN_MEANINGFUL_SCORE)) * 0.7 + 0.3;
-                for (const muscle of (_g = exercise.primaryMuscles) !== null && _g !== void 0 ? _g : []) {
+                for (const muscle of (_l = exercise.primaryMuscles) !== null && _l !== void 0 ? _l : []) {
                     const baseFatigue = record.score * 0.7 * intensityFraction;
-                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    const multiplier = userRecoveryMultiplier
+                        * getMuscleRecoveryRate(muscle)
+                        * getWeeklyVolumeMultiplier(muscle, weeklyVolume);
                     const remaining = calculateRecoveryFatigue(baseFatigue, hoursSince, multiplier);
                     if (remaining > 0)
                         updateEntry(internalMap, muscle, remaining, workoutDate, false);
                 }
-                for (const muscle of (_h = exercise.secondaryMuscles) !== null && _h !== void 0 ? _h : []) {
+                for (const muscle of (_m = exercise.secondaryMuscles) !== null && _m !== void 0 ? _m : []) {
                     const baseFatigue = record.score * 0.3 * intensityFraction;
-                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    const multiplier = userRecoveryMultiplier
+                        * getMuscleRecoveryRate(muscle)
+                        * getWeeklyVolumeMultiplier(muscle, weeklyVolume);
                     const remaining = calculateRecoveryFatigue(baseFatigue, hoursSince, multiplier);
                     if (remaining > 0)
                         updateEntry(internalMap, muscle, remaining, workoutDate, false);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dgpholdings/greatoak-shared",
-	"version": "1.2.58",
+	"version": "1.2.59",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",