@dgpholdings/greatoak-shared 1.2.58 → 1.2.60

package/dist/__mocks__/exercises.mock.js

@@ -8,6 +8,7 @@ exports.mockExercisesDictionary = exports.mockExerciseNoGuardrails = exports.moc
 exports.mockExerciseWeightReps = {
     exerciseId: "mock-exercise-weight-reps-123",
     name: "Generic Barbell Squat",
+    status: "active",
     bodyPart: ["Legs"],
     recordType: "weight-reps",
     primaryMuscles: ["quadriceps"],
@@ -56,7 +57,7 @@ exports.mockExerciseWeightReps = {
  * MOCK EXERCISE: Reps-Only
  * Simulates a bodyweight movement (e.g., Push-up).
  */
-exports.mockExerciseRepsOnly = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-reps-only-456", name: "Generic Push-Up", bodyPart: ["Chest", "Core"], recordType: "reps-only", primaryMuscles: ["pectoralis-major"], secondaryMuscles: ["tricep-brachii-lateral", "abs-lower"], trainingTypes: ["body-weight"], timingGuardrails: {
+exports.mockExerciseRepsOnly = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-reps-only-456", name: "Generic Push-Up", status: "active", bodyPart: ["Chest", "Core"], recordType: "reps-only", primaryMuscles: ["pectoralis-major"], secondaryMuscles: ["tricep-brachii-lateral", "abs-lower"], trainingTypes: ["body-weight"], timingGuardrails: {
         type: "reps-only",
         stressRestBonus: 2,
         fatigueMultiplier: 1.05,
@@ -77,7 +78,7 @@ exports.mockExerciseRepsOnly = Object.assign(Object.assign({}, exports.mockExerc
  * MOCK EXERCISE: Duration
  * Simulates an isometric hold (e.g., Plank).
  */
-exports.mockExerciseDuration = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-duration-789", name: "Generic Forearm Plank", bodyPart: ["Core"], recordType: "duration", primaryMuscles: ["abs-lower", "abs-upper"], secondaryMuscles: ["lower-back"], trainingTypes: ["body-weight", "isometric"], timingGuardrails: {
+exports.mockExerciseDuration = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-duration-789", name: "Generic Forearm Plank", status: "active", bodyPart: ["Core"], recordType: "duration", primaryMuscles: ["abs-lower", "abs-upper"], secondaryMuscles: ["lower-back"], trainingTypes: ["body-weight", "isometric"], timingGuardrails: {
         type: "duration",
         stressRestBonus: 3,
         fatigueMultiplier: 1.1,
@@ -98,7 +99,7 @@ exports.mockExerciseDuration = Object.assign(Object.assign({}, exports.mockExerc
  * MOCK EXERCISE: Cardio-Machine
  * Simulates a machine cardio session (e.g., Treadmill).
  */
-exports.mockExerciseCardioMachine = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-machine-101", name: "Generic Treadmill Run", bodyPart: ["Legs"], recordType: "cardio-machine", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
+exports.mockExerciseCardioMachine = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-machine-101", name: "Generic Treadmill Run", status: "active", bodyPart: ["Legs"], recordType: "cardio-machine", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
         type: "cardio-machine",
         stressRestBonus: 0,
         fatigueMultiplier: 1.0,
@@ -114,7 +115,7 @@ exports.mockExerciseCardioMachine = Object.assign(Object.assign({}, exports.mock
  * MOCK EXERCISE: Cardio-Free
  * Simulates an outdoor/untracked cardio session (e.g., Outdoor Run).
  */
-exports.mockExerciseCardioFree = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-free-202", name: "Generic Outdoor Jog", bodyPart: ["Legs"], recordType: "cardio-free", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
+exports.mockExerciseCardioFree = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-free-202", name: "Generic Outdoor Jog", status: "active", bodyPart: ["Legs"], recordType: "cardio-free", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
         type: "cardio-free",
         stressRestBonus: 0,
         fatigueMultiplier: 1.0,
@@ -130,7 +131,7 @@ exports.mockExerciseCardioFree = Object.assign(Object.assign({}, exports.mockExe
  * MOCK EXERCISE: No Guardrails
  * Simulates an older DB entry or custom exercise missing guardrails.
  */
-exports.mockExerciseNoGuardrails = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-no-guardrails-303", name: "Legacy Exercise", timingGuardrails: undefined });
+exports.mockExerciseNoGuardrails = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-no-guardrails-303", name: "Legacy Exercise", status: "active", timingGuardrails: undefined });
 /**
  * Helper dictionary containing all mock exercises mapped by their ID.
  */

package/dist/types/TApiExercise.d.ts

@@ -123,6 +123,10 @@ export type TExercise = {
     isFavorite?: boolean;
     scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry";
     isFlaggedCorrection?: boolean;
+    /** 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;
+    status: "active" | "inactive" | "archived";
     regressionExerciseId?: string;
     progressionExerciseId?: string;
     bodyweightDependency?: "high" | "medium" | "low" | "none";
@@ -135,9 +139,6 @@ 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.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, exercise.isUnilateral);
+    const cumulativeFatigue = computeCumulativeFatigue(sets, exercise.difficultyLevel, user, fatigueMultiplier, exercise.scoringSpecialHandling, exercise.isUnilateral, historicalContext);
     // --- Step 4: Distribute to muscles ---
     const rawMuscleFatigue = distributeFatigueToMuscles(cumulativeFatigue, exercise.primaryMuscles, exercise.secondaryMuscles);
     // --- Step 5: Normalize to 0–100 ---
@@ -88,7 +88,7 @@ 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, isUnilateral) {
+function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, isUnilateral, historicalContext) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     switch (set.type) {
         case "weight-reps": {
@@ -100,15 +100,26 @@ function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, i
         case "reps-only": {
             const reps = (_c = set.reps) !== null && _c !== void 0 ? _c : 0;
             const auxWeightKg = (_d = set.auxWeightKg) !== null && _d !== void 0 ? _d : 0;
-            // Estimate how much bodyweight the exercise loads
-            // difficulty 0 → 0%, difficulty 2 → ~33%, difficulty 4 → 65%
-            const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * user.weightKg;
-            const totalLoad = bodyweightLoad + auxWeightKg;
-            const baseVolume = totalLoad * reps;
-            // Plyometric: impact forces and neuromotor demand exceed simple BW × reps
-            if (scoringSpecialHandling === "plyometric") {
-                return baseVolume * constants_1.PLYOMETRIC_LOAD_MULTIPLIER;
+            // Epley Adaptation (P4-1): when a historical 1RM equivalent is available
+            // (bodyweight × (1 + bestReps/30)), use it to derive relative intensity.
+            // This means a user doing 20/25 max pull-ups scores higher fatigue than a
+            // user doing 20/80 max — identical reps, very different physiological effort.
+            //
+            // Fallback: difficulty-based bodyweight fraction (pre-P4-1 behaviour).
+            // Used when no history exists (first session on this exercise).
+            let effectiveLoad;
+            if ((historicalContext === null || historicalContext === void 0 ? void 0 : historicalContext.estimatedOneRepMax) && user.weightKg > 0 && reps > 0) {
+                const sessionEpley = user.weightKg * (1 + reps / 30);
+                const relativeIntensity = Math.min(1.0, sessionEpley / historicalContext.estimatedOneRepMax);
+                effectiveLoad = relativeIntensity * user.weightKg + auxWeightKg;
+            }
+            else {
+                const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * user.weightKg;
+                effectiveLoad = bodyweightLoad + auxWeightKg;
             }
+            const baseVolume = effectiveLoad * reps;
+            if (scoringSpecialHandling === "plyometric")
+                return baseVolume * constants_1.PLYOMETRIC_LOAD_MULTIPLIER;
             return baseVolume;
         }
         case "duration": {
@@ -176,12 +187,12 @@ function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, i
  *
  * @returns Single number representing total fatigue stimulus
  */
-function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier, scoringSpecialHandling, isUnilateral) {
+function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier, scoringSpecialHandling, isUnilateral, historicalContext) {
     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, isUnilateral);
+        const volumeLoad = computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling, isUnilateral, historicalContext);
         // Step 2: Scale by effort and exercise fatigue multiplier
         const stimulus = volumeLoad * set.effortFraction * fatigueMultiplier;
         // Step 3: Apply diminishing returns decay
@@ -260,9 +271,17 @@ function computeReferenceMax(exerciseType, difficultyLevel, user, muscleGroupFac
             break;
         }
         case "reps-only": {
-            const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * user.weightKg;
-            const typicalAux = 5; // assume up to 5kg aux for reference
-            singleSetMax = (bodyweightLoad + typicalAux) * 15;
+            // Epley Adaptation (P4-1): use the stored 1RM equivalent as the capacity
+            // anchor when available. This means the reference max scales to the
+            // individual's actual strength, not a population-average estimate.
+            if (historicalContext === null || historicalContext === void 0 ? void 0 : historicalContext.estimatedOneRepMax) {
+                singleSetMax = historicalContext.estimatedOneRepMax * constants_1.REFERENCE_MAX_REPS;
+            }
+            else {
+                // Fallback: difficulty-based bodyweight fraction
+                const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * user.weightKg;
+                singleSetMax = (bodyweightLoad + 5) * 15;
+            }
             break;
         }
         case "duration": {

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.60",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",