@dgpholdings/greatoak-shared 1.2.56 → 1.2.58

package/dist/typeGuards/index.js

@@ -1,13 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isRecordCardioMachineTypeGuard = exports.isRecordCardioFreeTypeGuard = exports.isRecordBodyWeightTypeGuard = exports.isRecordDurationTypeGuard = exports.isRecordWeightTypeGuard = void 0;
-const isRecordWeightTypeGuard = (param) => { var _a; return ((_a = param === null || param === void 0 ? void 0 : param[0]) === null || _a === void 0 ? void 0 : _a.type) === "weight-reps"; };
+// ---------------------------------------------------------------------------
+// Array type guards
+//
+// Each guard checks EVERY element, not just [0].
+// Checking only the first element and asserting the full array type is unsafe:
+// a mixed array passes the guard incorrectly if the first record happens to
+// match. Every element must agree.
+//
+// An empty array returns false — a zero-length record set has no meaningful type.
+// ---------------------------------------------------------------------------
+const isRecordWeightTypeGuard = (param) => param.length > 0 && param.every((r) => r.type === "weight-reps");
 exports.isRecordWeightTypeGuard = isRecordWeightTypeGuard;
-const isRecordDurationTypeGuard = (param) => { var _a; return ((_a = param === null || param === void 0 ? void 0 : param[0]) === null || _a === void 0 ? void 0 : _a.type) === "duration"; };
+const isRecordDurationTypeGuard = (param) => param.length > 0 && param.every((r) => r.type === "duration");
 exports.isRecordDurationTypeGuard = isRecordDurationTypeGuard;
-const isRecordBodyWeightTypeGuard = (param) => { var _a; return ((_a = param === null || param === void 0 ? void 0 : param[0]) === null || _a === void 0 ? void 0 : _a.type) === "reps-only"; };
+const isRecordBodyWeightTypeGuard = (param) => param.length > 0 && param.every((r) => r.type === "reps-only");
 exports.isRecordBodyWeightTypeGuard = isRecordBodyWeightTypeGuard;
-const isRecordCardioFreeTypeGuard = (param) => param[0].type === "cardio-free";
+const isRecordCardioFreeTypeGuard = (param) => param.length > 0 && param.every((r) => r.type === "cardio-free");
 exports.isRecordCardioFreeTypeGuard = isRecordCardioFreeTypeGuard;
-const isRecordCardioMachineTypeGuard = (param) => param[0].type === "cardio-machine";
+const isRecordCardioMachineTypeGuard = (param) => param.length > 0 && param.every((r) => r.type === "cardio-machine");
 exports.isRecordCardioMachineTypeGuard = isRecordCardioMachineTypeGuard;

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/index.d.ts

@@ -7,8 +7,8 @@ export { toError } from "./toError.util";
 export { generatePlanCode } from "./planCode.util";
 export { maskEmail, isAnonymousEmail, isEmail } from "./email.utils";
 export { NOOP } from "./noop.utils";
-export { calculateExerciseScoreV2, calculateTotalVolume, deriveTrainingAgeBracket } from "./scoringWorkout";
-export type { IHistoricalContext, TTrainingAgeBracket } from "./scoringWorkout";
+export { calculateExerciseScoreV2, calculateTotalVolume, deriveTrainingAgeBracket, computeMuscleFatigueMap } from "./scoringWorkout";
+export type { IHistoricalContext, TTrainingAgeBracket, TEnrichedSessionScore, TEnrichedExerciseRecord, TMuscleFatigueEntry, TMuscleFatigueResult } from "./scoringWorkout";
 export { scaleProPlan, calculateBMI, calculateDayPlanDuration, calculateExerciseDurationSecs } from "./adoptionEngine/scaleProPlan.util";
 export * from "./exerciseRecord/workoutMath";
 export * from "./exerciseRecord/recordValidator";

package/dist/utils/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateExerciseDurationSecs = exports.calculateDayPlanDuration = exports.calculateBMI = exports.scaleProPlan = exports.deriveTrainingAgeBracket = exports.calculateTotalVolume = exports.calculateExerciseScoreV2 = exports.NOOP = exports.isEmail = exports.isAnonymousEmail = exports.maskEmail = exports.generatePlanCode = exports.toError = exports.slugifyText = exports.isDefinedNumber = exports.isDefined = exports.countryToCurrencyCode = exports.getDaysAndHoursDifference = exports.isUserAllowedToUpdate = exports.mmssToSecs = exports.toNumber = void 0;
+exports.calculateExerciseDurationSecs = exports.calculateDayPlanDuration = exports.calculateBMI = exports.scaleProPlan = exports.computeMuscleFatigueMap = exports.deriveTrainingAgeBracket = exports.calculateTotalVolume = exports.calculateExerciseScoreV2 = exports.NOOP = exports.isEmail = exports.isAnonymousEmail = exports.maskEmail = exports.generatePlanCode = exports.toError = exports.slugifyText = exports.isDefinedNumber = exports.isDefined = exports.countryToCurrencyCode = exports.getDaysAndHoursDifference = exports.isUserAllowedToUpdate = exports.mmssToSecs = exports.toNumber = void 0;
 var number_util_1 = require("./number.util");
 Object.defineProperty(exports, "toNumber", { enumerable: true, get: function () { return number_util_1.toNumber; } });
 var time_util_1 = require("./time.util");
@@ -42,6 +42,7 @@ var scoringWorkout_1 = require("./scoringWorkout");
 Object.defineProperty(exports, "calculateExerciseScoreV2", { enumerable: true, get: function () { return scoringWorkout_1.calculateExerciseScoreV2; } });
 Object.defineProperty(exports, "calculateTotalVolume", { enumerable: true, get: function () { return scoringWorkout_1.calculateTotalVolume; } });
 Object.defineProperty(exports, "deriveTrainingAgeBracket", { enumerable: true, get: function () { return scoringWorkout_1.deriveTrainingAgeBracket; } });
+Object.defineProperty(exports, "computeMuscleFatigueMap", { enumerable: true, get: function () { return scoringWorkout_1.computeMuscleFatigueMap; } });
 var scaleProPlan_util_1 = require("./adoptionEngine/scaleProPlan.util");
 Object.defineProperty(exports, "scaleProPlan", { enumerable: true, get: function () { return scaleProPlan_util_1.scaleProPlan; } });
 Object.defineProperty(exports, "calculateBMI", { enumerable: true, get: function () { return scaleProPlan_util_1.calculateBMI; } });

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,11 +64,11 @@ 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 ---
-    const referenceMax = computeReferenceMax(sets[0].type, exercise.difficultyLevel, user, exercise.metabolicData.muscleGroupFactor, historicalContext);
+    const referenceMax = computeReferenceMax(sets[0].type, exercise.difficultyLevel, user, exercise.metabolicData.muscleGroupFactor, historicalContext, exercise.scoringSpecialHandling);
     return normalizeScores(rawMuscleFatigue, referenceMax);
 }
 // ---------------------------------------------------------------------------
@@ -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
@@ -247,7 +248,7 @@ function distributeFatigueToMuscles(cumulativeFatigue, primaryMuscles, secondary
  * should both be able to score 80–100 if performed well. Without scaling,
  * a squat would always dominate because it uses more weight absolutely.
  */
-function computeReferenceMax(exerciseType, difficultyLevel, user, muscleGroupFactor, historicalContext) {
+function computeReferenceMax(exerciseType, difficultyLevel, user, muscleGroupFactor, historicalContext, scoringSpecialHandling) {
     let singleSetMax;
     switch (exerciseType) {
         case "weight-reps": {
@@ -265,18 +266,24 @@ function computeReferenceMax(exerciseType, difficultyLevel, user, muscleGroupFac
             break;
         }
         case "duration": {
-            // Max hold time scales with difficulty:
-            //   difficulty 0 → 60s (easy stretch)
-            //   difficulty 2 → 120s (plank, side plank)
-            //   difficulty 4 → 180s (advanced isometric hold)
-            const maxHoldSecs = 60 + difficultyLevel * 30;
-            singleSetMax = maxHoldSecs * (difficultyLevel + 1);
+            // P3-4: continuous-duration exercises use the cardio dampened path in computeVolumeLoad.
+            // The reference max must mirror that dampener — otherwise the denominator is ~6.7× too
+            // large, causing systematic under-scoring for battle ropes, jump rope, high knees, etc.
+            if (scoringSpecialHandling === "continuous-duration") {
+                const maxDurationSecs = 60 + difficultyLevel * 30;
+                singleSetMax = maxDurationSecs * constants_1.CONTINUOUS_DURATION_INTENSITY_FACTOR * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+            }
+            else {
+                // Static hold: max time scales with difficulty
+                //   difficulty 0 → 60s, difficulty 2 → 120s, difficulty 4 → 180s
+                const maxHoldSecs = 60 + difficultyLevel * 30;
+                singleSetMax = maxHoldSecs * (difficultyLevel + 1);
+            }
             break;
         }
         case "cardio-machine":
         case "cardio-free": {
-            // 30 minutes at 75% max speed is a strong cardio effort
-            // Apply same dampener as volume calculation for consistent scaling
+            // 30 minutes at 75% max speed — same dampener as volume calculation
             singleSetMax = 1800 * 0.75 * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
             break;
         }

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

@@ -1,15 +1,18 @@
 import { TRecord, TUserMetric } from "../../types";
 /**
- * Calculates total volume for a set of records.
+ * Calculates total normalised volume for a completed set of records.
  *
- * - weight-reps:        reps * weight
- * - reps-only:          reps * (auxWeight || 30% of bodyweight)
- *   plyometric:         × 1.5 multiplier for impact/explosive demand
- * - duration:           durationSecs * 10 * (1 + auxWeight/100)
+ * - weight-reps:        reps × weight
+ * - reps-only:          reps × effectiveLoad (difficulty-scaled BW + aux)
+ *   plyometric:         × PLYOMETRIC_LOAD_MULTIPLIER for impact/explosive demand
+ * - duration:           durationSecs × 10 × auxFactor
  *   continuous-duration: durationSecs only (no static-hold multiplier)
  *   stretch-mobility:   0 (no training volume)
- * - cardio-machine:     distance (m) * (1 + speed/20) * inclineBoost * resistanceBoost
- * - cardio-free:        distance (m) * (1 + speed/20)
+ * - cardio-machine:     distance (m) × (1 + speed/20) × inclineBoost × resistanceBoost
+ * - cardio-free:        distance (m) × (1 + speed/20)
  *   loaded-carry:       × carried weight boost
+ *
+ * @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") => 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

@@ -1,73 +1,85 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateTotalVolume = void 0;
-const time_util_1 = require("../time.util");
+const helpers_1 = require("./helpers");
+const constants_1 = require("./constants");
 /**
- * Calculates total volume for a set of records.
+ * Calculates total normalised volume for a completed set of records.
  *
- * - weight-reps:        reps * weight
- * - reps-only:          reps * (auxWeight || 30% of bodyweight)
- *   plyometric:         × 1.5 multiplier for impact/explosive demand
- * - duration:           durationSecs * 10 * (1 + auxWeight/100)
+ * - weight-reps:        reps × weight
+ * - reps-only:          reps × effectiveLoad (difficulty-scaled BW + aux)
+ *   plyometric:         × PLYOMETRIC_LOAD_MULTIPLIER for impact/explosive demand
+ * - duration:           durationSecs × 10 × auxFactor
  *   continuous-duration: durationSecs only (no static-hold multiplier)
  *   stretch-mobility:   0 (no training volume)
- * - cardio-machine:     distance (m) * (1 + speed/20) * inclineBoost * resistanceBoost
- * - cardio-free:        distance (m) * (1 + speed/20)
+ * - cardio-machine:     distance (m) × (1 + speed/20) × inclineBoost × resistanceBoost
+ * - cardio-free:        distance (m) × (1 + speed/20)
  *   loaded-carry:       × carried weight boost
+ *
+ * @param difficultyLevel  Exercise difficulty (0–4). Used for bodyweight load
+ *                         scaling on reps-only exercises (matches fatigue pillar).
  */
-const calculateTotalVolume = (record, user, scoringSpecialHandling) => {
-    // Stretching/mobility produces no training volume
+const calculateTotalVolume = (record, user, scoringSpecialHandling, difficultyLevel = 2, isUnilateral = false) => {
     if (scoringSpecialHandling === "stretch-mobility")
         return 0;
-    return record.reduce((total, set) => {
-        const weight = parseFloat(set.type === "weight-reps"
-            ? set.kg
-            : set.type === "duration" || set.type === "reps-only" || set.type === "cardio-free"
-                ? set.auxWeightKg || "0"
-                : "0") || 0;
-        const reps = parseFloat(set.type === "weight-reps" || set.type === "reps-only" ? set.reps : "0") || 0;
-        const duration = set.type === "duration" ||
-            set.type === "cardio-machine" ||
-            set.type === "cardio-free"
-            ? (0, time_util_1.mmssToSecs)(set.durationMmSs)
-            : 0;
-        if (set.type === "weight-reps") {
-            return total + reps * weight;
-        }
-        else if (set.type === "reps-only") {
-            const bodyweight = user.weightKg || 70;
-            const effectiveWeight = weight > 0 ? weight : bodyweight * 0.3;
-            const baseVolume = reps * effectiveWeight;
-            return total + (scoringSpecialHandling === "plyometric" ? baseVolume * 1.5 : baseVolume);
-        }
-        else if (set.type === "duration") {
-            // Continuous-duration: no static-hold multiplier — just time elapsed
-            if (scoringSpecialHandling === "continuous-duration") {
-                return total + duration;
+    // Bug A fix: only completed sets contribute to volume.
+    // Each case narrows `set` to its exact union variant — no `as any` needed.
+    return record.filter((r) => r.isDone).reduce((total, set) => {
+        switch (set.type) {
+            case "weight-reps": {
+                const reps = parseFloat(set.reps) || 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;
             }
-            const weightFactor = weight > 0 ? 1 + weight / 100 : 1;
-            return total + duration * 10 * weightFactor;
-        }
-        else if (set.type === "cardio-machine") {
-            const speed = parseFloat(set.speed || "10");
-            const inclineBoost = set.inclinePercentage
-                ? 1 + parseFloat(set.inclinePercentage) * 0.02
-                : 1;
-            const resistanceBoost = set.resistanceLevel
-                ? 1 + parseFloat(set.resistanceLevel) * 0.05
-                : 1;
-            const distance = parseFloat(set.distance || "0") || (speed * duration) / 3600;
-            return total + distance * 1000 * (1 + speed / 20) * inclineBoost * resistanceBoost;
-        }
-        else if (set.type === "cardio-free") {
-            const distance = parseFloat(set.distance) || 0;
-            const speed = distance / (duration / 3600);
-            const carryBoost = scoringSpecialHandling === "loaded-carry" && weight > 0
-                ? 1 + weight / (user.weightKg || 70) * 0.5
-                : 1;
-            return total + distance * 1000 * (1 + speed / 20) * carryBoost;
+            case "reps-only": {
+                const reps = parseFloat(set.reps) || 0;
+                const auxWeight = parseFloat(set.auxWeightKg) || 0;
+                const bodyweight = user.weightKg || 70;
+                // Bug C fix: difficulty-aware bodyweight fraction (matches fatigue pillar)
+                const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * bodyweight;
+                const effectiveWeight = auxWeight > 0 ? auxWeight : bodyweightLoad;
+                const baseVolume = reps * effectiveWeight;
+                return total + (scoringSpecialHandling === "plyometric"
+                    ? baseVolume * constants_1.PLYOMETRIC_LOAD_MULTIPLIER
+                    : baseVolume);
+            }
+            case "duration": {
+                const duration = (0, helpers_1.parseDurationMmSs)(set.durationMmSs);
+                if (scoringSpecialHandling === "continuous-duration")
+                    return total + duration;
+                const auxWeight = parseFloat(set.auxWeightKg) || 0;
+                const weightFactor = auxWeight > 0 ? 1 + auxWeight / 100 : 1;
+                return total + duration * 10 * weightFactor;
+            }
+            case "cardio-machine": {
+                const duration = (0, helpers_1.parseDurationMmSs)(set.durationMmSs);
+                const speed = parseFloat(set.speed || "10");
+                const inclineBoost = set.inclinePercentage
+                    ? 1 + parseFloat(set.inclinePercentage) * 0.02
+                    : 1;
+                const resistanceBoost = set.resistanceLevel
+                    ? 1 + parseFloat(set.resistanceLevel) * 0.05
+                    : 1;
+                const distance = parseFloat(set.distance || "0") || (speed * duration) / 3600;
+                return total + distance * 1000 * (1 + speed / 20) * inclineBoost * resistanceBoost;
+            }
+            case "cardio-free": {
+                const distance = parseFloat(set.distance) || 0;
+                const duration = (0, helpers_1.parseDurationMmSs)(set.durationMmSs);
+                // Bug B fix: guard against zero duration → Infinity speed
+                if (distance === 0 || duration === 0)
+                    return total;
+                const speed = distance / (duration / 3600);
+                const auxWeight = parseFloat(set.auxWeightKg || "0") || 0;
+                const carryBoost = scoringSpecialHandling === "loaded-carry" && auxWeight > 0
+                    ? 1 + (auxWeight / (user.weightKg || 70)) * 0.5
+                    : 1;
+                return total + distance * 1000 * (1 + speed / 20) * carryBoost;
+            }
+            default:
+                return total;
         }
-        return total;
     }, 0);
 };
 exports.calculateTotalVolume = calculateTotalVolume;

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

@@ -0,0 +1,37 @@
+/**
+ * ============================================================================
+ * FITFRIX — Muscle Fatigue Aggregation
+ * ============================================================================
+ *
+ * Pure domain logic: takes exercise history (with per-session muscleScores)
+ * and produces a time-decayed per-muscle fatigue map (0–100 per muscle).
+ *
+ * NO UI concerns here. Colors, display names and chart types live in the app.
+ *
+ * Recovery model accounts for:
+ *   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-8  Muscle group — small muscles (biceps) recover 1.4× faster than legs (0.80×)
+ *
+ * Accumulation model:
+ *   P3-3  Real muscleScores → additive with diminishing returns (P3-5)
+ *   Legacy (muscleScores={}) → quality score × 0.7/0.3 proxy + MAX accumulation
+ */
+import type { TBodyPartKeys, TUserMetric } from "../../types";
+import type { TEnrichedExerciseRecord, TMuscleFatigueResult } from "./types";
+interface IExerciseMuscleData {
+    primaryMuscles: TBodyPartKeys;
+    secondaryMuscles: TBodyPartKeys;
+}
+/**
+ * Compute time-decayed per-muscle fatigue from exercise history.
+ *
+ * @param exercises      Map of exerciseId → { primaryMuscles, secondaryMuscles }
+ * @param scoreHistory   Enriched history with per-session muscleScores
+ * @param user           Optional user profile for recovery personalisation
+ * @param currentDate    Override for testing; defaults to now
+ * @returns              Record<muscleKey, { fatigue 0–100, lastWorked }>
+ */
+export declare function computeMuscleFatigueMap(exercises: Record<string, IExerciseMuscleData>, scoreHistory: TEnrichedExerciseRecord[], user?: Partial<TUserMetric>, currentDate?: Date): TMuscleFatigueResult;
+export {};

package/dist/utils/scoringWorkout/computeMuscleFatigueMap.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * ============================================================================
+ * FITFRIX — Muscle Fatigue Aggregation
+ * ============================================================================
+ *
+ * Pure domain logic: takes exercise history (with per-session muscleScores)
+ * and produces a time-decayed per-muscle fatigue map (0–100 per muscle).
+ *
+ * NO UI concerns here. Colors, display names and chart types live in the app.
+ *
+ * Recovery model accounts for:
+ *   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-8  Muscle group — small muscles (biceps) recover 1.4× faster than legs (0.80×)
+ *
+ * Accumulation model:
+ *   P3-3  Real muscleScores → additive with diminishing returns (P3-5)
+ *   Legacy (muscleScores={}) → quality score × 0.7/0.3 proxy + MAX accumulation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeMuscleFatigueMap = computeMuscleFatigueMap;
+// ---------------------------------------------------------------------------
+// P2-7: Age-adjusted recovery multiplier
+// ---------------------------------------------------------------------------
+function getAgeRecoveryMultiplier(age) {
+    if (age < 25)
+        return 1.05;
+    if (age < 35)
+        return 1.00;
+    if (age < 45)
+        return 0.95;
+    if (age < 55)
+        return 0.90;
+    return 0.85;
+}
+// ---------------------------------------------------------------------------
+// P2-8: Gender-adjusted recovery multiplier
+// ---------------------------------------------------------------------------
+function getGenderRecoveryMultiplier(gender) {
+    return gender === "female" ? 1.05 : 1.00;
+}
+// ---------------------------------------------------------------------------
+// P2-9: Fitness-level recovery multiplier
+// ---------------------------------------------------------------------------
+const FITNESS_RECOVERY_SCALE = {
+    sedentary: 0.80,
+    "lightly-active": 0.90,
+    "moderately-active": 1.00,
+    "very-active": 1.15,
+};
+// ---------------------------------------------------------------------------
+// P3-8: Muscle-group-specific recovery rates
+// Values > 1.0 = faster; < 1.0 = slower
+// ---------------------------------------------------------------------------
+const MUSCLE_RECOVERY_RATE = {
+    // Core — very fast
+    "abs-upper": 1.8, "abs-lower": 1.8, "obliques": 1.8,
+    // Small arm muscles — fast
+    "bicep-short-inner": 1.4, "bicep-long-outer": 1.4,
+    "tricep-brachii-long": 1.4, "tricep-brachii-lateral": 1.4,
+    "fore-arm-inner": 1.5, "fore-arm-outer": 1.5,
+    // Calves — fast
+    "calf-inner": 1.3, "calf-outer": 1.3,
+    // Shoulders / upper back — moderate
+    "deltoids-anterior": 1.1, "deltoids-middle": 1.1,
+    "trapezius": 1.0, "rhomboids": 1.0,
+    // Chest — moderate
+    "pectoralis-major": 1.0, "pectoralis-minor": 1.0,
+    // Large compound — slow
+    "latissimus-dorsi": 0.85,
+    "quadriceps": 0.80, "hamstrings": 0.80, "adductors": 0.80,
+    "glutes-maximus": 0.80, "glutes-medius": 0.85,
+    "lower-back": 0.75,
+};
+function getMuscleRecoveryRate(muscle) {
+    var _a;
+    return (_a = MUSCLE_RECOVERY_RATE[muscle]) !== null && _a !== void 0 ? _a : 1.0;
+}
+// ---------------------------------------------------------------------------
+// Core recovery formula
+// ---------------------------------------------------------------------------
+function calculateRecoveryFatigue(originalFatigue, hoursSinceWorkout, recoveryMultiplier = 1.0) {
+    if (hoursSinceWorkout <= 0)
+        return originalFatigue;
+    let recoveryRatePerHour;
+    if (originalFatigue >= 80)
+        recoveryRatePerHour = 1.25;
+    else if (originalFatigue >= 60)
+        recoveryRatePerHour = 1.67;
+    else if (originalFatigue >= 40)
+        recoveryRatePerHour = 2.08;
+    else
+        recoveryRatePerHour = 2.92;
+    recoveryRatePerHour *= recoveryMultiplier;
+    const recovered = originalFatigue * ((recoveryRatePerHour * hoursSinceWorkout) / 100);
+    return Math.max(0, originalFatigue - recovered);
+}
+function updateEntry(map, muscle, remainingFatigue, workoutDate, useAdditive) {
+    var _a;
+    const existing = (_a = map.get(muscle)) !== null && _a !== void 0 ? _a : { fatigue: 0, lastWorked: workoutDate };
+    // P3-5: additive with diminishing returns for real muscleScores
+    // Legacy sessions keep MAX to avoid overcorrection with the proxy
+    const newFatigue = useAdditive
+        ? existing.fatigue + remainingFatigue * (1 - existing.fatigue / 100)
+        : Math.max(existing.fatigue, remainingFatigue);
+    map.set(muscle, {
+        fatigue: Math.min(100, newFatigue),
+        lastWorked: existing.lastWorked > workoutDate ? existing.lastWorked : workoutDate,
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+const RECOVERY_WINDOW_HOURS = 168; // 7 days
+/**
+ * Compute time-decayed per-muscle fatigue from exercise history.
+ *
+ * @param exercises      Map of exerciseId → { primaryMuscles, secondaryMuscles }
+ * @param scoreHistory   Enriched history with per-session muscleScores
+ * @param user           Optional user profile for recovery personalisation
+ * @param currentDate    Override for testing; defaults to now
+ * @returns              Record<muscleKey, { fatigue 0–100, lastWorked }>
+ */
+function computeMuscleFatigueMap(exercises, scoreHistory, user, currentDate = new Date()) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    // Build combined user recovery multiplier (P2-7, P2-8, P2-9)
+    let userRecoveryMultiplier = 1.0;
+    if (user) {
+        const age = user.dob
+            ? currentDate.getFullYear() - new Date(user.dob).getFullYear()
+            : 30;
+        userRecoveryMultiplier =
+            getAgeRecoveryMultiplier(age) *
+                getGenderRecoveryMultiplier((_a = user.gender) !== null && _a !== void 0 ? _a : "unmentioned") *
+                ((_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 internalMap = new Map();
+    for (const { exerciseId, recordScore } of scoreHistory) {
+        const exercise = exercises[exerciseId];
+        if (!exercise || !recordScore.length)
+            continue;
+        const relevantRecords = recordScore.filter((r) => r.recordDate >= cutoffTime);
+        for (const record of relevantRecords) {
+            const workoutDate = new Date(record.recordDate);
+            const hoursSince = (currentDate.getTime() - workoutDate.getTime()) / 3600000;
+            // P3-3: Real path when muscleScores is available (sessions saved after P3-1)
+            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 : []),
+                ]);
+                for (const muscle of allMuscles) {
+                    const baseFatigue = (_f = record.muscleScores[muscle]) !== null && _f !== void 0 ? _f : 0;
+                    if (baseFatigue <= 0)
+                        continue;
+                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    const remaining = calculateRecoveryFatigue(baseFatigue, hoursSince, multiplier);
+                    if (remaining > 0)
+                        updateEntry(internalMap, muscle, remaining, workoutDate, true);
+                }
+            }
+            else {
+                // Legacy path: quality score × 0.7/0.3 proxy (P1-7 band-aid)
+                const MIN_MEANINGFUL_SCORE = 88;
+                const MAX_SCORE = 100;
+                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 : []) {
+                    const baseFatigue = record.score * 0.7 * intensityFraction;
+                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    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 : []) {
+                    const baseFatigue = record.score * 0.3 * intensityFraction;
+                    const multiplier = userRecoveryMultiplier * getMuscleRecoveryRate(muscle);
+                    const remaining = calculateRecoveryFatigue(baseFatigue, hoursSince, multiplier);
+                    if (remaining > 0)
+                        updateEntry(internalMap, muscle, remaining, workoutDate, false);
+                }
+            }
+        }
+    }
+    // Convert internal Map → plain object for the public return type
+    const result = {};
+    internalMap.forEach((entry, muscle) => {
+        result[muscle] = { fatigue: Math.round(entry.fatigue), lastWorked: entry.lastWorked };
+    });
+    return result;
+}

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

@@ -20,8 +20,10 @@ import { TExercise, TRecord, TUserMetric } from "../../types";
 import { deriveTrainingAgeBracket } from "./helpers";
 import type { IScoreResult, IHistoricalContext, TTrainingAgeBracket } from "./types";
 export { calculateTotalVolume } from "./calculateTotalVolume";
+export { computeMuscleFatigueMap } from "./computeMuscleFatigueMap";
 export { deriveTrainingAgeBracket };
 export type { IHistoricalContext, TTrainingAgeBracket };
+export type { TEnrichedSessionScore, TEnrichedExerciseRecord, TMuscleFatigueEntry, TMuscleFatigueResult } from "./types";
 export declare const calculateExerciseScoreV2: (param: {
     exercise: TExercise;
     record: TRecord[];

package/dist/utils/scoringWorkout/index.js

@@ -18,7 +18,7 @@
  * wired into the save flow — scheduled for Phase 3.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateExerciseScoreV2 = exports.deriveTrainingAgeBracket = exports.calculateTotalVolume = void 0;
+exports.calculateExerciseScoreV2 = exports.deriveTrainingAgeBracket = exports.computeMuscleFatigueMap = exports.calculateTotalVolume = void 0;
 const calculateMuscleFatiue_1 = require("./calculateMuscleFatiue");
 const calculateQualityScore_1 = require("./calculateQualityScore");
 const helpers_1 = require("./helpers");
@@ -26,6 +26,8 @@ Object.defineProperty(exports, "deriveTrainingAgeBracket", { enumerable: true, g
 const parseRecords_1 = require("./parseRecords");
 var calculateTotalVolume_1 = require("./calculateTotalVolume");
 Object.defineProperty(exports, "calculateTotalVolume", { enumerable: true, get: function () { return calculateTotalVolume_1.calculateTotalVolume; } });
+var computeMuscleFatigueMap_1 = require("./computeMuscleFatigueMap");
+Object.defineProperty(exports, "computeMuscleFatigueMap", { enumerable: true, get: function () { return computeMuscleFatigueMap_1.computeMuscleFatigueMap; } });
 // ---------------------------------------------------------------------------
 // Main Function — existing signature
 // ---------------------------------------------------------------------------
@@ -43,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/dist/utils/scoringWorkout/types.d.ts

@@ -8,6 +8,25 @@
  * scoring pillars (Calories, Muscle Fatigue, Quality).
  */
 import { TActivityLevel, TFitnessGoal, TGender, TRecord } from "../../types";
+/**
+ * A single scored session with real per-muscle fatigue values.
+ * muscleScores = {} for pre-P3-1 sessions (backward compat fallback).
+ */
+export interface TEnrichedSessionScore {
+    score: number;
+    recordDate: number;
+    muscleScores: Record<string, number>;
+}
+export interface TEnrichedExerciseRecord {
+    exerciseId: string;
+    recordScore: TEnrichedSessionScore[];
+}
+export interface TMuscleFatigueEntry {
+    fatigue: number;
+    lastWorked: Date;
+}
+/** Record<muscleKey, fatigue entry> — pure numbers, no UI concerns. */
+export type TMuscleFatigueResult = Record<string, TMuscleFatigueEntry>;
 /**
  * Quality score breakdown — lets the UI show users WHY they got their score.
  * Each sub-score is 0–100.

package/package.json

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