@dgpholdings/greatoak-shared 1.2.16 → 1.2.17

package/dist/utils/scoring/calculateMuscleFatiue.js

@@ -0,0 +1,290 @@
+"use strict";
+// calculateMuscleFatiue.ts
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 2: Muscle Fatigue
+ * ============================================================================
+ *
+ * Calculates per-muscle fatigue scores (0–100) for a single exercise.
+ *
+ * HOW IT WORKS:
+ *
+ * 1. For each set, compute a "fatigue stimulus" — how much mechanical work
+ *    the muscles experienced. This is type-specific:
+ *      weight-reps:   kg × reps
+ *      reps-only:     (bodyweightLoad + auxWeight) × reps
+ *      duration:      durationSecs × (difficultyLevel + 1) × auxBoost
+ *      cardio:        durationSecs × speedFactor
+ *
+ * 2. Multiply by effort (RPE/RIR → 0.5–1.3) and the exercise's
+ *    fatigueMultiplier from timingGuardrails.
+ *
+ * 3. Accumulate across sets with DIMINISHING RETURNS — later sets contribute
+ *    less because the muscle is pre-fatigued and can't generate as much force.
+ *    Decay: setDecay = 1 / (1 + 0.15 × setIndex)
+ *
+ * 4. Distribute the accumulated fatigue to muscles:
+ *      Primary muscles   → 100% of stimulus
+ *      Secondary muscles → 35% of stimulus
+ *
+ * 5. Normalize to 0–100 using an EXERCISE-AWARE reference maximum.
+ *    The reference max is what "5 hard sets of THIS exercise" would produce,
+ *    scaled by the exercise's difficultyLevel so bicep curls and squats
+ *    get fair scores.
+ *
+ * IMPORTANT: This function scores ONE exercise. The caller aggregates
+ * across exercises for full-workout muscle fatigue maps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateMuscleFatigue = calculateMuscleFatigue;
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+// ---------------------------------------------------------------------------
+// Main Fatigue Calculation
+// ---------------------------------------------------------------------------
+/**
+ * Calculate per-muscle fatigue scores for an exercise.
+ *
+ * @param sets              Parsed & validated sets (from parseRecords)
+ * @param exercise          Exercise metadata (muscles, difficulty, metabolic)
+ * @param user              Validated user context
+ * @param timingGuardrails  For fatigueMultiplier
+ * @returns                 Map of muscle key → fatigue score (0–100)
+ *
+ * @example
+ * const fatigue = calculateMuscleFatigue(parsedSets, exercise, userCtx, exercise.timingGuardrails);
+ * // → { "pectoralis-major": 24, "pectoralis-minor": 24, "deltoids-anterior": 8, ... }
+ */
+function calculateMuscleFatigue(sets, exercise, user, timingGuardrails) {
+    var _a;
+    if (sets.length === 0)
+        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);
+    // --- 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);
+    return normalizeScores(rawMuscleFatigue, referenceMax);
+}
+// ---------------------------------------------------------------------------
+// Step 1: Volume Load per Set
+// ---------------------------------------------------------------------------
+/**
+ * Calculate raw volume load for a single set.
+ *
+ * Volume load represents the mechanical work experienced by the muscles.
+ * Different exercise types produce volume in fundamentally different ways:
+ *
+ * weight-reps:   Force (kg) × repetitions
+ * reps-only:     Effective load (BW fraction + aux) × repetitions
+ * duration:      Time under tension × difficulty scaling × aux boost
+ * cardio:        Duration × speed factor (represents sustained effort)
+ */
+function computeVolumeLoad(set, difficultyLevel, user) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    switch (set.type) {
+        case "weight-reps": {
+            const kg = (_a = set.kg) !== null && _a !== void 0 ? _a : 0;
+            const reps = (_b = set.reps) !== null && _b !== void 0 ? _b : 0;
+            return kg * reps;
+        }
+        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;
+            return totalLoad * reps;
+        }
+        case "duration": {
+            const durationSecs = (_e = set.durationSecs) !== null && _e !== void 0 ? _e : set.activeDurationSecs;
+            const auxWeightKg = (_f = set.auxWeightKg) !== null && _f !== void 0 ? _f : 0;
+            // Duration exercises: time under tension is the primary driver
+            // Scale by (difficultyLevel + 1) so even difficulty-0 produces some fatigue
+            // Aux weight adds load (holding a plate during plank, etc.)
+            const auxBoost = 1 + (auxWeightKg / user.weightKg) * 0.3;
+            return durationSecs * (difficultyLevel + 1) * auxBoost;
+        }
+        case "cardio-machine": {
+            const durationSecs = (_g = set.cardioDurationSecs) !== null && _g !== void 0 ? _g : set.activeDurationSecs;
+            const speedMin = (_h = set.speedMin) !== null && _h !== void 0 ? _h : 0;
+            const speedMax = (_j = set.speedMax) !== null && _j !== void 0 ? _j : 0;
+            const avgSpeed = (speedMin + speedMax) / 2;
+            // Speed factor: faster pace = more muscle engagement per second
+            // Normalize against expected speed range (3–20 km/h)
+            const speedFactor = avgSpeed > 0 ? (0, helpers_1.clamp)(avgSpeed / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5) : 0.3; // fallback: light effort
+            // Cardio dampener: running fatigues muscles less than lifting
+            // A 30-min jog ≠ 30 min of squats for muscle fatigue
+            return durationSecs * speedFactor * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+        }
+        case "cardio-free": {
+            const durationSecs = (_k = set.cardioDurationSecs) !== null && _k !== void 0 ? _k : set.activeDurationSecs;
+            const distance = (_l = set.distance) !== null && _l !== void 0 ? _l : 0;
+            let baseVolume;
+            if (distance > 0 && durationSecs > 0) {
+                const speedKmh = distance / (durationSecs / 3600);
+                const speedFactor = (0, helpers_1.clamp)(speedKmh / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5);
+                baseVolume = durationSecs * speedFactor;
+            }
+            else {
+                baseVolume = durationSecs * 0.3;
+            }
+            return baseVolume * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+        }
+        default:
+            return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Steps 2–3: Effort × Decay Accumulation
+// ---------------------------------------------------------------------------
+/**
+ * Compute cumulative fatigue stimulus across all sets.
+ *
+ * For each set:
+ *   stimulus = volumeLoad × effortFraction × fatigueMultiplier
+ *
+ * Then accumulated with diminishing returns:
+ *   total += stimulus × (1 / (1 + 0.15 × setIndex))
+ *
+ * The decay models real physiology: set 1 creates the most novel stimulus,
+ * later sets work a pre-fatigued muscle that can't generate as much force.
+ *
+ * @returns Single number representing total fatigue stimulus
+ */
+function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier) {
+    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);
+        // Step 2: Scale by effort and exercise fatigue multiplier
+        const stimulus = volumeLoad * set.effortFraction * fatigueMultiplier;
+        // Step 3: Apply diminishing returns decay
+        //   set 0: 1.000 (full stimulus)
+        //   set 1: 0.870
+        //   set 2: 0.769
+        //   set 3: 0.690
+        //   set 4: 0.625
+        const setDecay = 1 / (1 + constants_1.SET_FATIGUE_DECAY_RATE * i);
+        cumulative += stimulus * setDecay;
+    }
+    return cumulative;
+}
+// ---------------------------------------------------------------------------
+// Step 4: Distribute to Muscles
+// ---------------------------------------------------------------------------
+/**
+ * Distribute cumulative fatigue to individual muscles.
+ *
+ * Primary muscles receive 100% of the stimulus (they're doing the work).
+ * Secondary muscles receive 35% (they assist but aren't the prime movers).
+ *
+ * If a muscle appears in BOTH primary and secondary (unlikely but possible
+ * with data inconsistencies), the values are summed — not overwritten.
+ */
+function distributeFatigueToMuscles(cumulativeFatigue, primaryMuscles, secondaryMuscles) {
+    var _a, _b;
+    const muscleFatigue = {};
+    for (const muscle of primaryMuscles) {
+        muscleFatigue[muscle] =
+            ((_a = muscleFatigue[muscle]) !== null && _a !== void 0 ? _a : 0) +
+                cumulativeFatigue * constants_1.PRIMARY_MUSCLE_ALLOCATION;
+    }
+    for (const muscle of secondaryMuscles) {
+        muscleFatigue[muscle] =
+            ((_b = muscleFatigue[muscle]) !== null && _b !== void 0 ? _b : 0) +
+                cumulativeFatigue * constants_1.SECONDARY_MUSCLE_ALLOCATION;
+    }
+    return muscleFatigue;
+}
+// ---------------------------------------------------------------------------
+// Step 5: Normalize to 0–100
+// ---------------------------------------------------------------------------
+/**
+ * Compute the reference maximum for normalization.
+ *
+ * This represents "what would 5 hard sets of THIS exercise produce?"
+ * The answer depends on:
+ *   - Exercise type (weight vs duration vs cardio)
+ *   - Difficulty level (scales expected weight/load)
+ *   - User weight (heavier users move more mass)
+ *
+ * NOTE: fatigueMultiplier is intentionally NOT included here.
+ * It only applies to the stimulus (numerator), not the reference (denominator).
+ * This way, exercises with high fatigueMultiplier (e.g., bench press 1.3)
+ * actually produce HIGHER fatigue scores — the multiplier amplifies the
+ * stimulus without raising the bar to score against.
+ *
+ * muscleGroupFactor IS included because it's a property of the exercise's
+ * muscle engagement pattern, not the user's effort. It scales both sides
+ * proportionally so exercises with more muscle groups don't get inflated scores.
+ *
+ * WHY exercise-aware: A bicep curl (difficulty 1) and a squat (difficulty 3)
+ * 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) {
+    let singleSetMax;
+    switch (exerciseType) {
+        case "weight-reps": {
+            // Expected max weight for this difficulty: 0.3×BW (easy) → 1.5×BW (hard)
+            const typicalMaxWeight = (0, constants_1.DIFFICULTY_TO_WEIGHT_FRACTION)(difficultyLevel) * user.weightKg;
+            singleSetMax = typicalMaxWeight * constants_1.REFERENCE_MAX_REPS;
+            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;
+            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);
+            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
+            singleSetMax = 1800 * 0.75 * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+            break;
+        }
+        default:
+            singleSetMax = 100;
+    }
+    // Simulate 5 sets with decay (same decay as actual calculation)
+    let totalWithDecay = 0;
+    for (let i = 0; i < constants_1.REFERENCE_MAX_SETS; i++) {
+        const setDecay = 1 / (1 + constants_1.SET_FATIGUE_DECAY_RATE * i);
+        totalWithDecay += setDecay;
+    }
+    return (singleSetMax * constants_1.REFERENCE_MAX_EFFORT * totalWithDecay * muscleGroupFactor);
+}
+/**
+ * Normalize raw fatigue values to 0–100 scale using the reference maximum.
+ *
+ * muscleGroupFactor is already baked into the reference max, so it
+ * naturally adjusts: exercises that engage more/larger muscles (higher factor)
+ * have a proportionally higher reference max, keeping scores fair.
+ */
+function normalizeScores(rawFatigue, referenceMax) {
+    if (referenceMax <= 0)
+        return rawFatigue;
+    const normalized = {};
+    const keys = Object.keys(rawFatigue);
+    for (let i = 0; i < keys.length; i++) {
+        const muscle = keys[i];
+        const raw = rawFatigue[muscle];
+        normalized[muscle] = Math.round((0, helpers_1.clamp)((raw / referenceMax) * 100, 0, 100));
+    }
+    return normalized;
+}

package/dist/utils/scoring/calculateQualityScore.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 3: Quality Score
+ * ============================================================================
+ *
+ * Measures HOW WELL the user performed the exercise (0–100).
+ * This is NOT about volume or calories — those are separate pillars.
+ * Quality is about execution: did you finish, stay consistent, push hard
+ * enough, and rest appropriately?
+ *
+ * FOUR SUB-COMPONENTS:
+ *
+ * ┌─────────────────────┬────────┬──────────────────────────────────────────┐
+ * │ Component           │ Weight │ What it measures                         │
+ * ├─────────────────────┼────────┼──────────────────────────────────────────┤
+ * │ Completion          │  20%   │ Did you finish all planned sets?         │
+ * │ Consistency         │  35%   │ Were sets stable or intentionally        │
+ * │                     │        │ progressive? (not random drops)          │
+ * │ Effort Adequacy     │  30%   │ Were you in the productive effort zone?  │
+ * │                     │        │ (RPE 6–9 or RIR 1–4)                     │
+ * │ Rest Discipline     │  15%   │ Did you respect optimal rest windows?    │
+ * └─────────────────────┴────────┴──────────────────────────────────────────┘
+ *
+ * Each sub-component produces 0–100. The final score is a weighted average.
+ *
+ * DESIGN PRINCIPLES:
+ * - Motivational: even a mediocre workout should score 40–60, not 10
+ * - Honest: perfect scores require real effort and discipline
+ * - Fair across types: cardio and strength use the same framework
+ * - Transparent: the breakdown is returned so the UI can explain the score
+ */
+import type { IParsedSet, IQualityBreakdown } from "./types";
+import type { ITimingGuardrails } from "./parseRecords";
+/**
+ * Raw record shape — we need the original RPE/RIR strings and isDone flag
+ * that aren't in IParsedSet (which only contains completed sets).
+ */
+interface IRawRecord {
+    type: string;
+    isDone: boolean;
+    rpe?: string;
+    rir?: string;
+    kg?: string;
+    reps?: string;
+    durationMmSs?: string;
+    auxWeightKg?: string;
+    speedMin?: string;
+    speedMax?: string;
+    distance?: string;
+    restDurationSecs?: number;
+}
+/**
+ * Calculate the overall quality score and its breakdown.
+ *
+ * @param parsedSets        Cleaned sets (from parseRecords) — only completed sets
+ * @param rawRecords        Original TRecord[] — needed for completion count (includes skipped)
+ * @param timingGuardrails  Exercise's guardrails — for rest period validation
+ * @returns                 { score: 0–100, breakdown: { completion, consistency, effortAdequacy, restDiscipline } }
+ *
+ * @example
+ * const { score, breakdown } = calculateQualityScore(parsed, raw, guardrails);
+ * // score: 81
+ * // breakdown: { completion: 100, consistency: 75, effortAdequacy: 80, restDiscipline: 73 }
+ */
+export declare function calculateQualityScore(parsedSets: IParsedSet[], rawRecords: IRawRecord[], timingGuardrails?: ITimingGuardrails): {
+    score: number;
+    breakdown: IQualityBreakdown;
+};
+export {};