@dgpholdings/greatoak-shared 1.2.57 → 1.2.59

package/dist/types/TApiExercise.d.ts

@@ -135,6 +135,9 @@ export type TExercise = {
         female: number;
         default: number;
     };
+    /** True for single-arm / single-leg exercises. The user enters weight per side,
+     *  so the scoring engine doubles it to get total mechanical load. */
+    isUnilateral?: boolean;
 };
 export type TBodyPartExercises = Record<TBodyPart, TExercise[]>;
 export type TApiCreateOrUpdateExerciseReq = {

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

@@ -49,6 +49,8 @@ interface IFatigueExerciseData {
         muscleGroupFactor: number;
     };
     scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry";
+    /** P3-9: Single-arm/leg exercises. User enters weight per side; double it for total load. */
+    isUnilateral?: boolean;
 }
 /**
  * Calculate per-muscle fatigue scores for an exercise.

package/dist/utils/scoringWorkout/calculateMuscleFatiue.js

@@ -64,7 +64,7 @@ function calculateMuscleFatigue(sets, exercise, user, timingGuardrails, historic
         return {};
     const fatigueMultiplier = (_a = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.fatigueMultiplier) !== null && _a !== void 0 ? _a : constants_1.FALLBACK_FATIGUE_MULTIPLIER;
     // --- Step 1–3: Compute cumulative fatigue stimulus ---
-    const cumulativeFatigue = computeCumulativeFatigue(sets, exercise.difficultyLevel, user, fatigueMultiplier, exercise.scoringSpecialHandling);
+    const cumulativeFatigue = computeCumulativeFatigue(sets, exercise.difficultyLevel, user, fatigueMultiplier, exercise.scoringSpecialHandling, exercise.isUnilateral);
     // --- Step 4: Distribute to muscles ---
     const rawMuscleFatigue = distributeFatigueToMuscles(cumulativeFatigue, exercise.primaryMuscles, exercise.secondaryMuscles);
     // --- Step 5: Normalize to 0–100 ---
@@ -88,11 +88,12 @@ function calculateMuscleFatigue(sets, exercise, user, timingGuardrails, historic
  * cardio:             Duration × speed factor (represents sustained effort)
  *   loaded-carry:     Speed factor boosted by carried weight relative to bodyweight
  */
-function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling) {
+function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, isUnilateral) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     switch (set.type) {
         case "weight-reps": {
-            const kg = (_a = set.kg) !== null && _a !== void 0 ? _a : 0;
+            // P3-9: User enters weight per side for unilateral exercises — double for total load
+            const kg = ((_a = set.kg) !== null && _a !== void 0 ? _a : 0) * (isUnilateral ? 2 : 1);
             const reps = (_b = set.reps) !== null && _b !== void 0 ? _b : 0;
             return kg * reps;
         }
@@ -175,12 +176,12 @@ function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling) {
  *
  * @returns Single number representing total fatigue stimulus
  */
-function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier, scoringSpecialHandling) {
+function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier, scoringSpecialHandling, isUnilateral) {
     let cumulative = 0;
     for (let i = 0; i < sets.length; i++) {
         const set = sets[i];
         // Step 1: Raw volume for this set
-        const volumeLoad = computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling);
+        const volumeLoad = computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, isUnilateral);
         // Step 2: Scale by effort and exercise fatigue multiplier
         const stimulus = volumeLoad * set.effortFraction * fatigueMultiplier;
         // Step 3: Apply diminishing returns decay

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

@@ -15,4 +15,4 @@ import { TRecord, TUserMetric } from "../../types";
  * @param difficultyLevel  Exercise difficulty (0–4). Used for bodyweight load
  *                         scaling on reps-only exercises (matches fatigue pillar).
  */
-export declare const calculateTotalVolume: (record: TRecord[], user: TUserMetric, scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry", difficultyLevel?: number) => number;
+export declare const calculateTotalVolume: (record: TRecord[], user: TUserMetric, scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry", difficultyLevel?: number, isUnilateral?: boolean) => number;

package/dist/utils/scoringWorkout/calculateTotalVolume.js

@@ -19,7 +19,7 @@ const constants_1 = require("./constants");
  * @param difficultyLevel  Exercise difficulty (0–4). Used for bodyweight load
  *                         scaling on reps-only exercises (matches fatigue pillar).
  */
-const calculateTotalVolume = (record, user, scoringSpecialHandling, difficultyLevel = 2) => {
+const calculateTotalVolume = (record, user, scoringSpecialHandling, difficultyLevel = 2, isUnilateral = false) => {
     if (scoringSpecialHandling === "stretch-mobility")
         return 0;
     // Bug A fix: only completed sets contribute to volume.
@@ -28,7 +28,8 @@ const calculateTotalVolume = (record, user, scoringSpecialHandling, difficultyLe
         switch (set.type) {
             case "weight-reps": {
                 const reps = parseFloat(set.reps) || 0;
-                const weight = parseFloat(set.kg) || 0;
+                // P3-9: User enters weight per side for unilateral exercises — double for total load
+                const weight = (parseFloat(set.kg) || 0) * (isUnilateral ? 2 : 1);
                 return total + reps * weight;
             }
             case "reps-only": {

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/dist/utils/scoringWorkout/index.js

@@ -45,6 +45,7 @@ const calculateExerciseScoreV2 = (param) => {
             muscleGroupFactor: exercise.metabolicData.muscleGroupFactor,
         },
         scoringSpecialHandling: exercise.scoringSpecialHandling,
+        isUnilateral: exercise.isUnilateral,
     }, userContext, exercise.timingGuardrails, historicalContext);
     // Pillar 3: Quality Score → score
     const isStrictTimingModeScoring = record.some((r) => r.isStrictMode);

package/package.json

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