@dgpholdings/greatoak-shared 1.2.86 → 1.2.87

package/dist/utils/scoringWorkout/calculateQualityScore.js

@@ -5,156 +5,181 @@ exports.calculateQualityScore = calculateQualityScore;
 const constants_1 = require("./constants");
 const helpers_1 = require("./helpers");
 // ---------------------------------------------------------------------------
-// Main Quality Calculation
+// Effort scoring tuning (kept local — these describe the score CURVE, not the
+// physiological "optimal zone" the old [min,max] ranges encoded).
 // ---------------------------------------------------------------------------
 /**
- * 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
- * @param isStrictTimingModeScoring If false, ignores the rest discipline penalty.
- * @param userContext       User context for dynamic weighting (P2-3)
- * @param historicalContext Optional history for progressive overload detection (P2-6)
- * @returns                 { score: 0–100, breakdown: { completion, consistency, effortAdequacy, restDiscipline } }
+ * Hard floor for any logged effort. Below the old EFFORT_MIN_SCORE (50) on
+ * purpose: now that every set logs RPE/RIR, a genuinely easy working set must
+ * be allowed to score lower than a no-data session ever could. 20 keeps the
+ * very-easy end from being a literal zero (a logged easy set is still better
+ * data than nothing) while letting it sink the session score.
+ */
+const EFFORT_FLOOR_SCORE = 20;
+/**
+ * RPE → score. Linear, monotonic, peaking at RPE 9 = 100.
+ *   score = 25 + (rpe - 1) * 9.375   (clamped 20–100)
+ * RPE 10 (grinding past failure every set) is capped slightly below 100 (95)
+ * so the model does not reward chronic to-failure training as "perfect".
+ */
+const EFFORT_RPE_BASE = 25;
+const EFFORT_RPE_SLOPE = 9.375; // (100 - 25) / (9 - 1)
+/**
+ * RIR → score. Inverse of RPE (RIR = reps in reserve, lower = harder).
+ *   score = 100 - rir * 8   (clamped 20–100)
+ * RIR 0–1 ≈ failure → ~100; RIR 10 → 20.
+ */
+const EFFORT_RIR_SLOPE = 8;
+/**
+ * Final-set emphasis for effort averaging. The last set's effort score is
+ * weighted this many times a normal set. 2.0 = the finish counts double.
+ */
+const EFFORT_FINAL_SET_WEIGHT = 2.0;
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Calculate the overall quality score and its component breakdown.
  *
- * @example
- * const { score, breakdown } = calculateQualityScore(parsed, raw, guardrails, false, userCtx, historyCtx);
- * // score: 81
- * // breakdown: { completion: 100, consistency: 75, effortAdequacy: 80, restDiscipline: 65 }
+ * @param parsedSets        Cleaned completed sets (output of parseRecords)
+ * @param rawRecords        Original TRecord[] — needed for completion count and RPE/RIR
+ * @param timingGuardrails  Exercise DB guardrails — for rest period validation
+ * @param historicalContext Optional cross-session context for overload detection
  */
-function calculateQualityScore(parsedSets, rawRecords, timingGuardrails, isStrictTimingModeScoring, userContext, historicalContext) {
-    var _a;
-    // Edge case: no records at all or NONE were completed
+function calculateQualityScore(parsedSets, rawRecords, timingGuardrails, historicalContext) {
+    // Nothing completed at all
     if (rawRecords.length === 0 || parsedSets.length === 0) {
-        const emptyScoresByGoal = {};
-        for (const goal of userContext.fitnessGoals) {
-            emptyScoresByGoal[goal] = {
-                score: 0,
-                qualityBreakdown: {
-                    completion: 0,
-                    consistency: 0,
-                    effortAdequacy: 0,
-                    restDiscipline: 0,
-                },
-            };
-        }
         return {
-            scoresByGoal: emptyScoresByGoal,
+            score: 0,
+            qualityBreakdown: {
+                completion: 0,
+                consistency: 0,
+                effortAdequacy: 0,
+                restDiscipline: 0,
+            },
+            restDisciplineActive: false,
         };
     }
+    // ── Three always-active components ──────────────────────────────────────
     const completion = calculateCompletion(parsedSets, rawRecords);
     const consistency = calculateConsistency(parsedSets, historicalContext);
     const effortAdequacy = calculateEffortAdequacy(rawRecords);
-    const restDiscipline = isStrictTimingModeScoring ? calculateRestDiscipline(parsedSets, timingGuardrails) : constants_1.REST_NO_DATA_SCORE;
-    const breakdownBase = {
-        completion: Math.round(completion),
-        consistency: Math.round(consistency),
-        effortAdequacy: Math.round(effortAdequacy),
-        restDiscipline: Math.round(restDiscipline),
-    };
-    // P2-3: Dynamic Quality Weights based on fitnessGoal
-    const goalWeights = {
-        strength: { completion: 0.15, consistency: 0.25, effortAdequacy: 0.45, restDiscipline: 0.15 },
-        hypertrophy: { completion: 0.20, consistency: 0.35, effortAdequacy: 0.30, restDiscipline: 0.15 },
-        endurance: { completion: 0.25, consistency: 0.40, effortAdequacy: 0.20, restDiscipline: 0.15 },
-        fat_loss: { completion: 0.30, consistency: 0.30, effortAdequacy: 0.25, restDiscipline: 0.15 },
-        mobility: { completion: 0.40, consistency: 0.35, effortAdequacy: 0.10, restDiscipline: 0.15 },
-        general_fitness: { completion: 0.20, consistency: 0.35, effortAdequacy: 0.30, restDiscipline: 0.15 },
-        rehabilitation: { completion: 0.40, consistency: 0.40, effortAdequacy: 0.10, restDiscipline: 0.10 },
-        sport_performance: { completion: 0.20, consistency: 0.30, effortAdequacy: 0.35, restDiscipline: 0.15 },
-        core_strength: { completion: 0.25, consistency: 0.35, effortAdequacy: 0.25, restDiscipline: 0.15 },
-    };
-    const scoresByGoal = {};
-    for (const goal of userContext.fitnessGoals) {
-        const goalWeight = (_a = goalWeights[goal]) !== null && _a !== void 0 ? _a : constants_1.QUALITY_WEIGHTS;
-        const goalScore = Math.round(completion * goalWeight.completion +
-            consistency * goalWeight.consistency +
-            effortAdequacy * goalWeight.effortAdequacy +
-            restDiscipline * goalWeight.restDiscipline);
-        scoresByGoal[goal] = {
-            score: (0, helpers_1.clamp)(goalScore, 0, 100),
-            qualityBreakdown: breakdownBase,
-        };
-    }
+    // ── Conditional: rest discipline ─────────────────────────────────────────
+    // null = no rest data logged → excluded from scoring entirely.
+    // The 15% weight is redistributed to the three active components below.
+    // Two-gate check for rest discipline:
+    //
+    // Gate 1 — raw data: did the user actually log rest timing?
+    //   Check rawRecords (not parsedSets). parseRecords synthesises rest values
+    //   from timingGuardrails.typical for non-last sets even when the user never
+    //   logged rest, making parsedSets an unreliable signal.
+    //
+    // Gate 2 — evaluable sets: does calculateRestDiscipline have non-last sets to score?
+    //   Even if raw data exists, a single-set exercise has its only set marked as
+    //   last-set → parsedSet.restDurationSecs = null → no evaluable sets.
+    //   calculateRestDiscipline returns null in this case.
+    //
+    // restDisciplineActive = true only when BOTH gates pass — real data existed
+    // AND produced an evaluable score.
+    const hasRawRestData = rawRecords.some((r) => r.restDurationSecs !== undefined && r.restDurationSecs !== null);
+    const restDiscipline = hasRawRestData
+        ? calculateRestDiscipline(parsedSets, timingGuardrails) // may return null for single-set
+        : null;
+    // ── Dynamic weight normalisation ─────────────────────────────────────────
+    //
+    // With rest:    activeWeightTotal = 1.00  → standard weights apply
+    // Without rest: activeWeightTotal = 0.85  → remaining three components
+    //               are normalised to fill 100% of the score space
+    //
+    // Using the sum of active weights rather than a hardcoded 0.85 means any
+    // future adjustments to QUALITY_WEIGHTS in constants.ts propagate here
+    // automatically without touching this logic.
+    const activeWeightTotal = restDiscipline !== null
+        ? 1.0
+        : constants_1.QUALITY_WEIGHTS.completion +
+            constants_1.QUALITY_WEIGHTS.consistency +
+            constants_1.QUALITY_WEIGHTS.effortAdequacy;
+    const weightedSum = completion * constants_1.QUALITY_WEIGHTS.completion +
+        consistency * constants_1.QUALITY_WEIGHTS.consistency +
+        effortAdequacy * constants_1.QUALITY_WEIGHTS.effortAdequacy +
+        (restDiscipline !== null
+            ? restDiscipline * constants_1.QUALITY_WEIGHTS.restDiscipline
+            : 0);
+    const score = (0, helpers_1.clamp)(Math.round(weightedSum / activeWeightTotal), 0, 100);
     return {
-        scoresByGoal,
+        score,
+        qualityBreakdown: {
+            completion: Math.round(completion),
+            consistency: Math.round(consistency),
+            effortAdequacy: Math.round(effortAdequacy),
+            restDiscipline: restDiscipline !== null ? Math.round(restDiscipline) : 0,
+        },
+        restDisciplineActive: restDiscipline !== null,
     };
 }
 // ---------------------------------------------------------------------------
-// Component A: Completion (0–100)
+// Component A — Completion (0–100)
 // ---------------------------------------------------------------------------
 /**
- * Did the user complete all their sets?
- *
- * Simple ratio: completedSets / totalSets × 100
- *
- * This rewards finishing what you started. Skipping sets tanks the score.
- *
- * Uses rawRecords.length as total (includes isDone:false) and
- * parsedSets.length as completed (only isDone:true after filtering).
+ * Ratio of completed sets to planned sets.
+ * Skipping sets directly reduces this score. Completing everything = 100.
  */
 function calculateCompletion(parsedSets, rawRecords) {
     const total = rawRecords.length;
     if (total === 0)
         return 0;
-    const completed = parsedSets.length;
-    return (completed / total) * 100;
+    return (parsedSets.length / total) * 100;
 }
 // ---------------------------------------------------------------------------
-// Component B: Consistency (0–100)
+// Component B — Consistency (0–100)
 // ---------------------------------------------------------------------------
 /**
  * Were sets consistent in performance output?
  *
- * Measures the coefficient of variation (CV) of the per-set "output metric".
- * CV = 0 → perfectly consistent → score 100
- * CV = 0.50 → very variable → score ~0 (clamped to minimum)
+ * Uses coefficient of variation (CV) of a per-set output metric.
+ *   CV = 0    → perfectly consistent → 100
+ *   CV = 0.5  → very variable → clamped to CONSISTENCY_MIN_SCORE
  *
- * The "output metric" depends on exercise type:
- *   weight-reps:   kg × reps (volume per set)
- *   reps-only:     reps (aux weight change is intentional, so just reps)
- *   duration:      durationSecs
- *   cardio-machine: avg speed (speedMin + speedMax) / 2
- *   cardio-free:    effective speed (distance / time)
+ * Output metric by record type:
+ *   weight-reps    → kg × reps (volume per set — handles pyramids and backoffs)
+ *   reps-only      → rep count
+ *   duration       → hold time in seconds
+ *   cardio-machine → speed
+ *   cardio-free    → effective speed (distance / time)
  *
- * SPECIAL CASE — Progressive overload detection:
- * If values are monotonically increasing (warming up / pyramiding UP)
- * or monotonically decreasing (drop sets / fatigue), this is INTENTIONAL.
- * We don't penalize it — instead, we floor the score at 75.
- * Requires ≥ 3 sets to detect (2 sets are always monotonic).
+ * Progressive overload protection — intentional patterns are NOT penalised:
  *
- * P2-6: Progressive overload across sessions
- * If the session volume matches or beats the previous session's volume,
- * we also floor the score at 75 to reward progression.
+ *   Intra-session (≥ 3 sets required — 2 sets are always trivially monotonic):
+ *     Monotonically ascending  [warm-up pyramid, RPT]  → floor at PROGRESSIVE_OVERLOAD_FLOOR
+ *     Monotonically descending [drop sets]              → floor at PROGRESSIVE_OVERLOAD_FLOOR
+ *     Top-set + stable backoffs [500, 640, 640]         → non-strictly ascending → protected
  *
- * SINGLE SET: Returns 100 (nothing to compare against).
+ *   Cross-session (P2-6):
+ *     Current total volume ≥ previous session volume    → floor at PROGRESSIVE_OVERLOAD_FLOOR
+ *     Rewards users who beat last session even when intra-set CV is high.
+ *
+ * Single set → 100 (nothing to compare against).
  */
 function calculateConsistency(parsedSets, historicalContext) {
     if (parsedSets.length <= 1)
         return 100;
     const values = parsedSets.map(extractConsistencyMetric);
-    // Filter out zero/invalid values
     const validValues = values.filter((v) => v > 0);
     if (validValues.length <= 1)
         return 100;
-    // Calculate coefficient of variation
     const cv = (0, helpers_1.coefficientOfVariation)(validValues);
-    // Base score: penalize variance
     let score = (0, helpers_1.clamp)(100 - cv * constants_1.CONSISTENCY_CV_PENALTY, constants_1.CONSISTENCY_MIN_SCORE, 100);
     let isProgressiveOverload = false;
-    // P2-6: Cross-session progressive overload
-    const currentSessionVolume = validValues.reduce((sum, v) => sum + v, 0);
-    if ((historicalContext === null || historicalContext === void 0 ? void 0 : historicalContext.previousSessionVolume) && currentSessionVolume > 0) {
-        if (currentSessionVolume >= historicalContext.previousSessionVolume) {
-            isProgressiveOverload = true;
-        }
+    // Cross-session: beat last session's total volume?
+    const currentVolume = validValues.reduce((sum, v) => sum + v, 0);
+    if ((historicalContext === null || historicalContext === void 0 ? void 0 : historicalContext.previousSessionVolume) !== undefined &&
+        historicalContext.previousSessionVolume > 0 &&
+        currentVolume >= historicalContext.previousSessionVolume) {
+        isProgressiveOverload = true;
     }
-    // Intra-session progressive overload detection
-    if (validValues.length >= 3) {
-        const isMonotonicallyIncreasing = isMonotonic(validValues, "asc");
-        const isMonotonicallyDecreasing = isMonotonic(validValues, "desc");
-        if (isMonotonicallyIncreasing || isMonotonicallyDecreasing) {
+    // Intra-session: monotonic pattern (≥ 3 sets)
+    if (!isProgressiveOverload && validValues.length >= 3) {
+        if (isMonotonic(validValues, "asc") || isMonotonic(validValues, "desc")) {
             isProgressiveOverload = true;
         }
     }
@@ -164,46 +189,39 @@ function calculateConsistency(parsedSets, historicalContext) {
     return score;
 }
 /**
- * Extract the consistency metric for a set based on its type.
+ * Extract the consistency metric for one set based on its record type.
+ *
+ * weight-reps uses kg × reps (integrated volume) rather than kg alone:
+ *   Straight sets:        [80×8, 80×8, 80×8]   → [640, 640, 640]  CV = 0   → 100
+ *   Top set + backoffs:   [100×5, 80×8, 80×8]  → [500, 640, 640]  ascending → floor
+ *   Pyramid up:           [60×12, 80×8, 100×5] → [720, 640, 500]  descending → floor
+ *   Drop sets:            [100×8, 80×10, 60×12] → [800, 800, 720] descending → floor
  */
 function extractConsistencyMetric(set) {
     var _a, _b, _c, _d, _e, _f, _g;
     switch (set.type) {
-        case "weight-reps": {
-            // Volume per set: 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": {
-            // Just reps (aux weight changes are intentional, not inconsistency)
+        case "weight-reps":
+            return ((_a = set.kg) !== null && _a !== void 0 ? _a : 0) * ((_b = set.reps) !== null && _b !== void 0 ? _b : 0);
+        case "reps-only":
             return (_c = set.reps) !== null && _c !== void 0 ? _c : 0;
-        }
-        case "duration": {
-            // Hold duration
+        case "duration":
             return (_d = set.durationSecs) !== null && _d !== void 0 ? _d : set.activeDurationSecs;
-        }
-        case "cardio-machine": {
-            // Average speed
-            const speed = (_e = set.speed) !== null && _e !== void 0 ? _e : 0;
-            return speed;
-        }
+        case "cardio-machine":
+            return (_e = set.speed) !== null && _e !== void 0 ? _e : 0;
         case "cardio-free": {
-            // Effective speed (km/h)
             const distance = (_f = set.distance) !== null && _f !== void 0 ? _f : 0;
-            const durationSecs = (_g = set.cardioDurationSecs) !== null && _g !== void 0 ? _g : set.activeDurationSecs;
-            if (durationSecs > 0 && distance > 0) {
-                return distance / (durationSecs / 3600);
-            }
-            return 0;
+            const durationSec = (_g = set.cardioDurationSecs) !== null && _g !== void 0 ? _g : set.activeDurationSecs;
+            return durationSec > 0 && distance > 0
+                ? distance / (durationSec / 3600)
+                : 0;
         }
         default:
             return 0;
     }
 }
 /**
- * Check if an array of numbers is monotonically increasing or decreasing.
- * "Allowing equal" — [10, 10, 12] counts as ascending.
+ * True when values are non-strictly monotonic in the given direction.
+ * Equal consecutive values are allowed: [500, 640, 640] is ascending.
  */
 function isMonotonic(values, direction) {
     for (let i = 1; i < values.length; i++) {
@@ -215,143 +233,126 @@ function isMonotonic(values, direction) {
     return true;
 }
 // ---------------------------------------------------------------------------
-// Component C: Effort Adequacy (0–100)
+// Component C — Effort Adequacy (0–100)
 // ---------------------------------------------------------------------------
 /**
- * Was the user working in a productive effort zone?
- *
- * The "productive zone" for most training goals:
- *   RIR 1–4: close enough to failure to stimulate adaptation, not so close
- *            that recovery is impaired
- *   RPE 6–9: same concept from the subjective side
+ * Was the user working hard enough to drive adaptation?
  *
- * Scoring per set:
- * - Within optimal range → 100
- * - Outside by 1 unit → 80
- * - Outside by 2 units → 60
- * - Outside by 3+ units → 40/20
+ * Effort is now logged on EVERY set (post-set one-tap modal), so scoring is
+ * graded and monotonic rather than a flat optimal-band. Each set is scored,
+ * then averaged with the FINAL set weighted EFFORT_FINAL_SET_WEIGHT× because
+ * the last working set is where adequacy is truly decided.
  *
- * If neither RPE nor RIR is provided → 70 (neutral, can't confirm or deny).
+ *   RPE: 9 → 100, 7 → ~81, 4 → ~53, 1 → 25 (floored at 20)
+ *   RIR: 0 → 100, 3 → 76,  6 → 52,  10 → 20
  *
- * Uses RAW records (not parsed sets) because:
- * 1. We need the original RPE/RIR strings
- * 2. We only score completed sets (isDone === true)
+ * RIR is preferred over RPE when both exist (more objective — countable reps).
+ * A set with NO effort data (legacy/pre-update records only) scores the neutral
+ * EFFORT_NO_DATA_SCORE so historical sessions in the Gate 2 window don't break.
  */
 function calculateEffortAdequacy(rawRecords) {
     const completedRecords = rawRecords.filter((r) => r.isDone);
     if (completedRecords.length === 0)
         return 0;
-    const setScores = [];
-    for (const record of completedRecords) {
-        setScores.push(scoreSetEffort(record));
-    }
-    // Average all set effort scores
-    return setScores.reduce((sum, s) => sum + s, 0) / setScores.length;
+    const setScores = completedRecords.map(scoreSetEffort);
+    // Weighted mean — final set counts EFFORT_FINAL_SET_WEIGHT×.
+    const lastIndex = setScores.length - 1;
+    let weightedSum = 0;
+    let weightTotal = 0;
+    setScores.forEach((s, i) => {
+        const w = i === lastIndex ? EFFORT_FINAL_SET_WEIGHT : 1;
+        weightedSum += s * w;
+        weightTotal += w;
+    });
+    return weightTotal > 0 ? weightedSum / weightTotal : constants_1.EFFORT_NO_DATA_SCORE;
 }
-/**
- * Score a single set's effort level.
- *
- * Priority: RIR > RPE > no data.
- * For RIR: optimal range [1, 4]
- * For RPE: optimal range [6, 9]
- */
 function scoreSetEffort(record) {
-    // Try RIR first (more objective)
+    // RIR preferred (more objective — countable remaining reps)
     if (record.rir !== undefined && record.rir !== "") {
-        const rir = (0, helpers_1.safeParseFloat)(record.rir, -1);
-        if (rir >= 0) {
-            return scoreAgainstRange(rir, constants_1.OPTIMAL_RIR_RANGE);
+        const rir = parseFloat(record.rir);
+        if (!isNaN(rir) && rir >= 0) {
+            return scoreEffortRir(rir);
         }
     }
-    // Try RPE
+    // RPE fallback
     if (record.rpe !== undefined && record.rpe !== "") {
-        const rpe = (0, helpers_1.safeParseFloat)(record.rpe, -1);
-        if (rpe >= 1) {
-            return scoreAgainstRange(rpe, constants_1.OPTIMAL_RPE_RANGE);
+        const rpe = parseFloat(record.rpe);
+        if (!isNaN(rpe) && rpe >= 1) {
+            return scoreEffortRpe(rpe);
         }
     }
-    // No effort data — neutral score
+    // No effort data — legacy/pre-update sessions only. Neutral, never a penalty.
     return constants_1.EFFORT_NO_DATA_SCORE;
 }
 /**
- * Score a value against an optimal range.
- *
- * Within [min, max] → 100
- * Distance 1 outside → 100 - penalty
- * Distance 2 outside → 100 - 2×penalty
- * etc., floored at EFFORT_MIN_SCORE
+ * Graded RPE → effort score. Monotonic: harder always scores higher.
+ *   score = EFFORT_RPE_BASE + (rpe - 1) * EFFORT_RPE_SLOPE   (clamped 20–100)
+ * RPE 10 capped at 95 — chronic grinding past failure is not "perfect".
  */
-function scoreAgainstRange(value, range) {
-    const [min, max] = range;
-    if (value >= min && value <= max)
-        return 100;
-    // Distance from nearest edge of the range
-    const distance = value < min ? min - value : value - max;
-    return Math.max(100 - distance * constants_1.EFFORT_DISTANCE_PENALTY, constants_1.EFFORT_MIN_SCORE);
+function scoreEffortRpe(rpe) {
+    const clamped = (0, helpers_1.clamp)(rpe, 1, 10);
+    if (clamped > 9)
+        return 95;
+    const score = EFFORT_RPE_BASE + (clamped - 1) * EFFORT_RPE_SLOPE;
+    return (0, helpers_1.clamp)(score, EFFORT_FLOOR_SCORE, 100);
+}
+/**
+ * Graded RIR → effort score. Inverse of RPE (RIR lower = harder).
+ *   score = 100 - rir * EFFORT_RIR_SLOPE   (clamped 20–100)
+ */
+function scoreEffortRir(rir) {
+    const clamped = (0, helpers_1.clamp)(rir, 0, 10);
+    const score = 100 - clamped * EFFORT_RIR_SLOPE;
+    return (0, helpers_1.clamp)(score, EFFORT_FLOOR_SCORE, 100);
 }
 // ---------------------------------------------------------------------------
-// Component D: Rest Discipline (0–100)
+// Component D — Rest Discipline (0–100, conditional)
 // ---------------------------------------------------------------------------
 /**
  * Were rest periods within the exercise's optimal windows?
  *
- * Uses the exercise's timingGuardrails.restPeriods:
- *   optimalRange [min, max] → 100 points
- *   within [minimum, maximum] → 70–100 (proportional to how close to optimal)
- *   outside [minimum, maximum] → 50 points (Reduced penalty so it doesn't tank the score too much)
+ * Only called when parsedSets has at least one non-null restDurationSecs.
+ * The caller (calculateQualityScore) handles conditional inclusion and
+ * weight redistribution — this function only scores what it receives.
  *
- * Only scores sets that HAVE rest data (last set often doesn't).
- * If no valid rest data exists at all → neutral 70.
+ * Scoring bands (using timingGuardrails.restPeriods from exercise DB):
+ *   Within optimalRange         → 100
+ *   Within [minimum, maximum]   → 70–99 proportional to proximity to optimal
+ *   Outside [minimum, maximum]  → 50  (soft penalty — doesn't crater the score)
  *
- * The stressRestBonus from timingGuardrails is applied as a final multiplier:
- * exercises where proper rest is especially important (heavy compounds)
- * get a boost when rest is done right.
+ * stressRestBonus (from exercise timingGuardrails):
+ *   Heavy compounds benefit more from proper rest. A small bonus is applied
+ *   when avgScore > 60 and the exercise carries a stressRestBonus value.
  */
 function calculateRestDiscipline(parsedSets, timingGuardrails) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-    // Gather sets that have rest data (non-null)
-    const setsWithRest = parsedSets.filter((s) => s.restDurationSecs !== null);
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const setsWithRest = parsedSets.filter((s) => s.restDurationSecs !== null && s.restDurationSecs !== undefined);
+    // No evaluable sets (e.g. single-set exercise where the only set is the last set).
+    // Return null so the caller knows there is genuinely no data to score,
+    // distinct from a score of 0 (which would penalise the user unfairly).
     if (setsWithRest.length === 0)
-        return constants_1.REST_NO_DATA_SCORE;
-    // Extract rest period bounds from guardrails
+        return null;
     const restConfig = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.restPeriods;
-    const optimalMin = (_b = (_a = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : ((_c = restConfig === null || restConfig === void 0 ? void 0 : restConfig.typical) !== null && _c !== void 0 ? _c : constants_1.FALLBACK_REST_SECS) * 0.75;
-    const optimalMax = (_e = (_d = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _d === void 0 ? void 0 : _d[1]) !== null && _e !== void 0 ? _e : ((_f = restConfig === null || restConfig === void 0 ? void 0 : restConfig.typical) !== null && _f !== void 0 ? _f : constants_1.FALLBACK_REST_SECS) * 1.25;
-    const acceptableMin = (_g = restConfig === null || restConfig === void 0 ? void 0 : restConfig.minimum) !== null && _g !== void 0 ? _g : optimalMin * 0.5;
-    const acceptableMax = (_h = restConfig === null || restConfig === void 0 ? void 0 : restConfig.maximum) !== null && _h !== void 0 ? _h : optimalMax * 2;
-    const setScores = [];
-    for (const set of setsWithRest) {
-        const rest = set.restDurationSecs; // Guaranteed non-null by filter
-        if (rest >= optimalMin && rest <= optimalMax) {
-            // Within optimal range → perfect score
-            setScores.push(100); // REST_OPTIMAL_SCORE
-        }
-        else if (rest >= acceptableMin && rest <= acceptableMax) {
-            // Within acceptable range but not optimal
-            // Score proportionally based on how close to optimal, base is 70 now
-            const baseAcceptableScore = 70;
-            let ratio;
-            if (rest < optimalMin) {
-                // Between acceptable min and optimal min
-                ratio = (rest - acceptableMin) / (optimalMin - acceptableMin);
-            }
-            else {
-                // Between optimal max and acceptable max
-                ratio = (acceptableMax - rest) / (acceptableMax - optimalMax);
-            }
-            setScores.push(baseAcceptableScore +
-                ratio * (100 - baseAcceptableScore));
+    const typicalRest = (_a = restConfig === null || restConfig === void 0 ? void 0 : restConfig.typical) !== null && _a !== void 0 ? _a : constants_1.FALLBACK_REST_SECS;
+    const optimalMin = (_c = (_b = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : typicalRest * 0.75;
+    const optimalMax = (_e = (_d = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _d === void 0 ? void 0 : _d[1]) !== null && _e !== void 0 ? _e : typicalRest * 1.25;
+    const acceptMin = (_f = restConfig === null || restConfig === void 0 ? void 0 : restConfig.minimum) !== null && _f !== void 0 ? _f : optimalMin * 0.5;
+    const acceptMax = (_g = restConfig === null || restConfig === void 0 ? void 0 : restConfig.maximum) !== null && _g !== void 0 ? _g : optimalMax * 2;
+    const setScores = setsWithRest.map((set) => {
+        const rest = set.restDurationSecs;
+        if (rest >= optimalMin && rest <= optimalMax)
+            return 100;
+        if (rest >= acceptMin && rest <= acceptMax) {
+            const base = 70;
+            const ratio = rest < optimalMin
+                ? (rest - acceptMin) / (optimalMin - acceptMin)
+                : (acceptMax - rest) / (acceptMax - optimalMax);
+            return base + ratio * (100 - base);
         }
-        else {
-            // Outside even the acceptable range, reduced penalty to 50
-            setScores.push(50);
-        }
-    }
-    // Average rest scores
+        return 50;
+    });
     let avgScore = setScores.reduce((sum, s) => sum + s, 0) / setScores.length;
-    // Apply stressRestBonus (P1-4): exercises where proper rest matters more
-    // (e.g., heavy compounds) get a point bonus if they performed well.
-    const stressRestBonus = (_j = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.stressRestBonus) !== null && _j !== void 0 ? _j : 0;
+    const stressRestBonus = (_h = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.stressRestBonus) !== null && _h !== void 0 ? _h : 0;
     if (avgScore > 60 && stressRestBonus > 0) {
         avgScore = Math.min(100, avgScore + stressRestBonus);
     }

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

@@ -10,18 +10,22 @@
  *
  * 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-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:
- *   P3-3  Real muscleScores → additive with diminishing returns (P3-5)
- *   Legacy (muscleScores={}) → quality score × 0.7/0.3 proxy + MAX accumulation
+ *   P3-3  Real per-session muscleScores → additive with diminishing returns (P3-5)
+ *
+ * Note: the legacy quality-score proxy path (pre-P3-1 sessions with empty
+ * muscleScores) has been removed — every session now saves real muscleScores.
+ * The P2-8 gender recovery factor has also been removed: the 1.05× female
+ * bump was within the noise of the model and not well-evidenced enough to
+ * justify a silent default-male assumption for unmentioned-gender users.
  */
 import type { TBodyPartKeys, TUserMetric } from "../../types";
 import type { TEnrichedExerciseRecord, TMuscleFatigueResult } from "./types";
-interface IExerciseMuscleData {
+export interface IExerciseMuscleData {
     primaryMuscles: TBodyPartKeys;
     secondaryMuscles: TBodyPartKeys;
 }
@@ -35,4 +39,3 @@ interface IExerciseMuscleData {
  * @returns              Record<muscleKey, { fatigue 0–100, lastWorked }>
  */
 export declare function computeMuscleFatigueMap(exercises: Record<string, IExerciseMuscleData>, scoreHistory: TEnrichedExerciseRecord[], user?: Partial<TUserMetric>, currentDate?: Date): TMuscleFatigueResult;
-export {};