@dgpholdings/greatoak-shared 1.2.54 → 1.2.55

package/dist/utils/scoringWorkout/constants.js

@@ -0,0 +1,247 @@
+"use strict";
+// constants.ts
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Constants
+ * ============================================================================
+ *
+ * All magic numbers, default values, and tuning parameters live here.
+ * When we need to adjust scoring behavior, this is the ONLY file to change.
+ *
+ * Naming convention:
+ *   DEFAULT_*   = user-related fallbacks (weight, height, age)
+ *   FALLBACK_*  = exercise timing fallbacks (only when timingGuardrails is missing)
+ *   ABSOLUTE_*  = hard safety bounds (catches truly broken data)
+ *   QUALITY_*   = quality score weights and thresholds
+ *   FACTOR_*    = multipliers used in formulas
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REST_NO_DATA_SCORE = exports.REST_OUTSIDE_SCORE = exports.REST_ACCEPTABLE_BASE = exports.REST_OPTIMAL_SCORE = exports.EFFORT_NO_DATA_SCORE = exports.EFFORT_MIN_SCORE = exports.EFFORT_DISTANCE_PENALTY = exports.OPTIMAL_RPE_RANGE = exports.OPTIMAL_RIR_RANGE = exports.PROGRESSIVE_OVERLOAD_FLOOR = exports.CONSISTENCY_MIN_SCORE = exports.CONSISTENCY_CV_PENALTY = exports.QUALITY_WEIGHTS = exports.REFERENCE_MAX_EFFORT = exports.REFERENCE_MAX_REPS = exports.REFERENCE_MAX_SETS = exports.DIFFICULTY_TO_WEIGHT_FRACTION = exports.LOADED_CARRY_WEIGHT_MET_SCALE = exports.CONTINUOUS_DURATION_INTENSITY_FACTOR = exports.PLYOMETRIC_LOAD_MULTIPLIER = exports.CARDIO_MUSCLE_FATIGUE_DAMPENER = exports.SET_FATIGUE_DECAY_RATE = exports.SECONDARY_MUSCLE_ALLOCATION = exports.PRIMARY_MUSCLE_ALLOCATION = exports.CARDIO_SPEED_RANGE = exports.BW_FRACTION_SCALE = exports.DURATION_CATEGORY_THRESHOLDS = exports.DEFAULT_DURATION_FACTORS = exports.WEIGHT_CATEGORY_THRESHOLDS = exports.DEFAULT_WEIGHT_FACTORS = exports.REST_MET = exports.EFFORT_FRACTION_RANGE = exports.EFFORT_FRACTION_BASE = exports.EFFORT_CURVE_EXPONENT = exports.DEFAULT_EFFORT_FRACTION = exports.ABSOLUTE_WORK_MAX = exports.ABSOLUTE_WORK_MIN = exports.ABSOLUTE_REST_MAX = exports.ABSOLUTE_REST_MIN = exports.FALLBACK_STRESS_REST_BONUS = exports.FALLBACK_FATIGUE_MULTIPLIER = exports.FALLBACK_REST_SECS = exports.FALLBACK_SET_DURATION_SECS = exports.FALLBACK_SECS_PER_REP = exports.DEFAULT_USER_AGE = exports.DEFAULT_USER_HEIGHT_CM = exports.DEFAULT_USER_WEIGHT_KG = void 0;
+// ---------------------------------------------------------------------------
+// User Defaults (when TUserMetric has missing fields)
+// ---------------------------------------------------------------------------
+/** Average adult weight when user hasn't provided theirs */
+exports.DEFAULT_USER_WEIGHT_KG = 70;
+/** Average adult height */
+exports.DEFAULT_USER_HEIGHT_CM = 170;
+/** Assumed age when DOB is missing */
+exports.DEFAULT_USER_AGE = 30;
+// ---------------------------------------------------------------------------
+// Timing: Last-Resort Fallbacks
+// ---------------------------------------------------------------------------
+//
+// IMPORTANT: These are only used when timingGuardrails is COMPLETELY MISSING
+// from the exercise. In normal operation, validation bounds and defaults come
+// from the exercise's own timingGuardrails:
+//
+//   Rest validation  → timingGuardrails.restPeriods.minimum / maximum
+//   Rest fallback    → timingGuardrails.restPeriods.typical
+//   Work duration    → timingGuardrails.setDuration.min / max (duration type)
+//                    → timingGuardrails.singleRep.min / max (rep-based types)
+//   Fatigue scaling  → timingGuardrails.fatigueMultiplier
+//   Rest quality     → timingGuardrails.stressRestBonus
+//
+// The constants below are emergency defaults for malformed exercise data.
+/** Seconds per rep when timingGuardrails.singleRep is missing entirely */
+exports.FALLBACK_SECS_PER_REP = 3;
+/** Set duration when timingGuardrails.setDuration is missing entirely */
+exports.FALLBACK_SET_DURATION_SECS = 30;
+/** Rest period when timingGuardrails.restPeriods is missing entirely */
+exports.FALLBACK_REST_SECS = 90;
+/** Fatigue multiplier when timingGuardrails.fatigueMultiplier is missing */
+exports.FALLBACK_FATIGUE_MULTIPLIER = 1.0;
+/** Stress rest bonus when timingGuardrails.stressRestBonus is missing */
+exports.FALLBACK_STRESS_REST_BONUS = 1.0;
+/**
+ * Absolute sanity bounds — these catch truly absurd sensor/input errors
+ * that even the exercise's own guardrails wouldn't expect.
+ * These are NOT the exercise's min/max; they're a safety net.
+ *
+ * Example: a restDurationSecs of 86400 (24 hours) is clearly a bug,
+ * regardless of what the exercise's guardrails say.
+ */
+exports.ABSOLUTE_REST_MIN = 0;
+exports.ABSOLUTE_REST_MAX = 3600; // 1 hour — no exercise rests longer
+exports.ABSOLUTE_WORK_MIN = 1; // At least 1 second of work
+exports.ABSOLUTE_WORK_MAX = 14400; // 4 hours (ultra marathon cardio)
+// ---------------------------------------------------------------------------
+// Effort Conversion
+// ---------------------------------------------------------------------------
+/**
+ * Effort fraction when neither RPE nor RIR is provided.
+ * 0.6 = moderate effort assumption.
+ */
+exports.DEFAULT_EFFORT_FRACTION = 0.6;
+/**
+ * Exponent for non-linear RPE/RIR → effort conversion.
+ * Values > 1.0 make the last reps near failure disproportionately harder,
+ * which matches real physiology (RPE 9→10 is a bigger jump than 5→6).
+ */
+exports.EFFORT_CURVE_EXPONENT = 1.3;
+/**
+ * Effort fraction output range.
+ * effort = BASE + RANGE × (normalized_input ^ EXPONENT)
+ */
+exports.EFFORT_FRACTION_BASE = 0.5;
+exports.EFFORT_FRACTION_RANGE = 0.8;
+// ---------------------------------------------------------------------------
+// Calorie Calculation
+// ---------------------------------------------------------------------------
+/**
+ * MET value during rest periods.
+ * Not true resting (1.0) because the body is still elevated after a set.
+ * 1.5 accounts for elevated heart rate and recovery metabolism.
+ */
+exports.REST_MET = 1.5;
+/**
+ * Default weight intensity multipliers when metabolicData.weightFactors
+ * is missing. Keyed by intensity category.
+ */
+exports.DEFAULT_WEIGHT_FACTORS = {
+    light: 0.8, // < 25% bodyweight
+    moderate: 1.0, // 25–50% bodyweight
+    heavy: 1.3, // > 50% bodyweight
+};
+/** Thresholds for weight category classification (as ratio of bodyweight) */
+exports.WEIGHT_CATEGORY_THRESHOLDS = {
+    lightMax: 0.25,
+    moderateMax: 0.5,
+};
+/**
+ * Default duration multipliers when metabolicData.durationFactors is missing.
+ */
+exports.DEFAULT_DURATION_FACTORS = {
+    short: 0.9, // < 30 seconds
+    medium: 1.0, // 30s – 2min
+    long: 1.2, // > 2 min
+};
+/** Thresholds for duration category classification (in seconds) */
+exports.DURATION_CATEGORY_THRESHOLDS = {
+    shortMax: 30,
+    mediumMax: 120,
+};
+/**
+ * For reps-only / bodyweight exercises: how much of bodyweight is "the load".
+ * Scaled by exercise difficultyLevel (0–4):
+ *   load = (difficultyLevel / 4) × BW_FRACTION_SCALE × userWeightKg
+ *
+ * difficulty 0 → 0.0 × 0.65 = 0% (basically no BW load, e.g. finger exercise)
+ * difficulty 1 → 0.25 × 0.65 = 16% (light BW, e.g. easy crunches)
+ * difficulty 2 → 0.50 × 0.65 = 33% (moderate, e.g. push-ups)
+ * difficulty 4 → 1.00 × 0.65 = 65% (heavy, e.g. pistol squats)
+ */
+exports.BW_FRACTION_SCALE = 0.65;
+/**
+ * Expected min/max speed range for cardio (km/h) when paceFactors are missing.
+ * Used to normalize speed into a 0–1 fraction for MET interpolation.
+ */
+exports.CARDIO_SPEED_RANGE = {
+    min: 3, // slow walk
+    max: 20, // fast sprint
+};
+// ---------------------------------------------------------------------------
+// Muscle Fatigue
+// ---------------------------------------------------------------------------
+/** Fraction of total fatigue stimulus allocated to primary muscles */
+exports.PRIMARY_MUSCLE_ALLOCATION = 1.0;
+/** Fraction of total fatigue stimulus allocated to secondary muscles */
+exports.SECONDARY_MUSCLE_ALLOCATION = 0.35;
+/**
+ * Diminishing returns decay rate for consecutive sets.
+ * setDecay = 1 / (1 + DECAY_RATE × setIndex)
+ *
+ * With 0.15:  set0=1.00, set1=0.87, set2=0.77, set3=0.69, set4=0.63
+ */
+exports.SET_FATIGUE_DECAY_RATE = 0.15;
+/**
+ * Cardio exercises create cardiovascular fatigue, not the same mechanical
+ * muscle fatigue as strength training. A 30-minute jog doesn't fatigue
+ * your quads the way 5 sets of heavy squats does.
+ *
+ * This dampener reduces the volume-load contribution of cardio exercises
+ * so their muscle fatigue scores are proportional to actual muscle damage/stress.
+ *
+ * 0.3 means cardio produces ~30% of the muscle fatigue that an equivalent
+ * "volume" of strength work would.
+ */
+exports.CARDIO_MUSCLE_FATIGUE_DAMPENER = 0.3;
+/**
+ * Load multiplier for plyometric / explosive reps-only exercises.
+ * Accounts for impact forces (3–5× BW) and neuromotor demand that
+ * simple BW × reps volume underestimates.
+ * Applied to volume load before fatigue distribution.
+ */
+exports.PLYOMETRIC_LOAD_MULTIPLIER = 1.5;
+/**
+ * Intensity factor for continuous-movement duration exercises
+ * (battle ropes, high knees, jump rope) when no speed/distance is available.
+ * Represents moderate continuous effort — higher than isometric holds but
+ * routed through the cardio dampener like other cardio types.
+ */
+exports.CONTINUOUS_DURATION_INTENSITY_FACTOR = 0.5;
+/**
+ * MET scale factor for loaded-carry exercises (farmer's walk, overhead carry).
+ * For every 100% of bodyweight carried, MET is boosted by this fraction.
+ * e.g. carrying 50% BW → MET × (1 + 0.5 × 0.5) = MET × 1.25
+ */
+exports.LOADED_CARRY_WEIGHT_MET_SCALE = 0.5;
+/**
+ * Reference max scaling by difficulty level.
+ * Maps difficultyLevel (0–4) → expected max weight as a fraction of bodyweight.
+ *
+ * This makes fatigue normalization exercise-aware:
+ * - Bicep curl (difficulty 1) → ref weight ~0.6× BW → smaller denominator → fair score
+ * - Squat (difficulty 3)      → ref weight ~1.2× BW → larger denominator → fair score
+ */
+const DIFFICULTY_TO_WEIGHT_FRACTION = (difficulty) => 0.3 + difficulty * 0.3;
+exports.DIFFICULTY_TO_WEIGHT_FRACTION = DIFFICULTY_TO_WEIGHT_FRACTION;
+/** Reference set count for "fully fatigued" benchmark */
+exports.REFERENCE_MAX_SETS = 5;
+/** Reference rep count for "fully fatigued" benchmark */
+exports.REFERENCE_MAX_REPS = 12;
+/** Reference effort multiplier for "fully fatigued" benchmark */
+exports.REFERENCE_MAX_EFFORT = 1.3;
+// ---------------------------------------------------------------------------
+// Quality Score
+// ---------------------------------------------------------------------------
+/**
+ * Weights for the four quality sub-components.
+ * Must sum to 1.0.
+ */
+exports.QUALITY_WEIGHTS = {
+    completion: 0.2,
+    consistency: 0.35,
+    effortAdequacy: 0.3,
+    restDiscipline: 0.15,
+};
+/**
+ * Consistency scoring: how aggressively CV (coefficient of variation) is penalized.
+ * consistencyScore = 100 - CV × PENALTY
+ * CV 0.0 → 100, CV 0.15 → 70, CV 0.50 → 0
+ */
+exports.CONSISTENCY_CV_PENALTY = 200;
+/** Minimum consistency score (even very inconsistent sets get some credit) */
+exports.CONSISTENCY_MIN_SCORE = 20;
+/** Floor score for intentional progressive/descending sets (≥3 sets) */
+exports.PROGRESSIVE_OVERLOAD_FLOOR = 75;
+/**
+ * Optimal RIR range for effort adequacy scoring.
+ * Within this range → 100 points. Outside → penalized by distance.
+ */
+exports.OPTIMAL_RIR_RANGE = [1, 4];
+/** Optimal RPE range for effort adequacy scoring. */
+exports.OPTIMAL_RPE_RANGE = [6, 9];
+/** Penalty per unit of distance from the optimal effort range */
+exports.EFFORT_DISTANCE_PENALTY = 20;
+/** Minimum effort adequacy score */
+exports.EFFORT_MIN_SCORE = 20;
+/** Default effort adequacy score when no RPE/RIR data is available */
+exports.EFFORT_NO_DATA_SCORE = 70;
+/** Score when rest is within the optimal range */
+exports.REST_OPTIMAL_SCORE = 100;
+/** Score when rest is within acceptable (min–max) but not optimal */
+exports.REST_ACCEPTABLE_BASE = 70;
+/** Score when rest is completely outside the acceptable range */
+exports.REST_OUTSIDE_SCORE = 50;
+/** Default rest discipline score when no valid rest data exists */
+exports.REST_NO_DATA_SCORE = 75;

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

@@ -0,0 +1,127 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Helpers
+ * ============================================================================
+ *
+ * Pure utility functions with no business logic. These handle:
+ * - Safe parsing of string values from TRecord
+ * - Duration parsing ("MM:SS" → seconds)
+ * - Clamping and validation
+ * - Effort fraction conversion (RPE/RIR → 0–1)
+ * - User context extraction with fallbacks
+ *
+ * All functions are deterministic and side-effect free.
+ */
+import { TGender } from "../../types";
+import type { IUserContext } from "./types";
+/**
+ * Safely parse a string to a float.
+ * Returns `fallback` if the input is undefined, empty, NaN, or negative.
+ *
+ * @example
+ * safeParseFloat("10.5")       // 10.5
+ * safeParseFloat("")           // 0
+ * safeParseFloat(undefined)    // 0
+ * safeParseFloat("abc", 5)    // 5
+ */
+export declare function safeParseFloat(value: string | undefined | null, fallback?: number): number;
+/**
+ * Parse a "MM:SS" or "M:SS" or "HH:MM:SS" duration string into total seconds.
+ *
+ * Handles edge cases:
+ * - "04:55" → 295 seconds
+ * - "10:00" → 600 seconds
+ * - "1:30:00" → 5400 seconds
+ * - "0:45" → 45 seconds (could be MM:SS with 0 min, or just 45 sec)
+ * - "" or invalid → fallbackSecs
+ *
+ * @param duration   The "MM:SS" string from TRecord.durationMmSs
+ * @param fallbackSecs  Returned when parsing fails (default: 0)
+ */
+export declare function parseDurationMmSs(duration: string | undefined | null, fallbackSecs?: number): number;
+/**
+ * Clamp a value between min and max (inclusive).
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Calculate the arithmetic mean of an array of numbers.
+ * Returns 0 for an empty array.
+ */
+export declare function mean(values: number[]): number;
+/**
+ * Calculate the standard deviation (population) of an array of numbers.
+ * Returns 0 for arrays with fewer than 2 elements.
+ */
+export declare function standardDeviation(values: number[]): number;
+/**
+ * Coefficient of variation: stdDev / mean.
+ * Returns 0 if mean is 0 (avoids division by zero).
+ * A CV of 0 means perfect consistency; higher = more variable.
+ */
+export declare function coefficientOfVariation(values: number[]): number;
+/**
+ * Convert RIR (Reps In Reserve) to an effort fraction (0.0 – 1.0).
+ *
+ * RIR scale: 0 = at failure (max effort), 10 = trivial (minimal effort).
+ *
+ * Uses a non-linear curve (exponent 1.3) because the perceptual and
+ * physiological cost of the last 2–3 reps near failure is disproportionately
+ * higher than the middle reps.
+ *
+ * Output range: ~0.50 (RIR 10) → ~1.30 (RIR 0)
+ * This is an "effort multiplier" not a pure 0–1, but the naming matches
+ * its usage in calorie and fatigue calculations.
+ *
+ * @example
+ * rirToEffortFraction(0)  // ~1.30 (at failure)
+ * rirToEffortFraction(3)  // ~0.94
+ * rirToEffortFraction(5)  // ~0.82
+ * rirToEffortFraction(10) // ~0.50
+ */
+export declare function rirToEffortFraction(rir: number): number;
+/**
+ * Convert RPE (Rate of Perceived Exertion) to an effort fraction.
+ *
+ * RPE scale: 1 = very easy, 10 = maximal effort.
+ * Same non-linear curve as RIR conversion.
+ *
+ * @example
+ * rpeToEffortFraction(10) // ~1.30 (max effort)
+ * rpeToEffortFraction(7)  // ~0.94
+ * rpeToEffortFraction(5)  // ~0.82
+ * rpeToEffortFraction(1)  // ~0.54
+ */
+export declare function rpeToEffortFraction(rpe: number): number;
+/**
+ * Extract effort fraction from a raw TRecord.
+ *
+ * Priority: RIR > RPE > default (0.6).
+ * RIR is preferred because it's more objective (countable reps left)
+ * while RPE is subjective.
+ *
+ * @param record - Any TRecord (we only read the rpe/rir fields)
+ */
+export declare function getEffortFraction(record: {
+    rpe?: string;
+    rir?: string;
+}): number;
+/**
+ * Extract a validated user context from TUserMetric.
+ * Guarantees all fields have usable values (no undefined).
+ *
+ * @param user - The raw TUserMetric object
+ */
+export declare function extractUserContext(user: {
+    weightKg?: number;
+    heightCm?: number;
+    gender?: TGender;
+    dob?: Date | string;
+    fitnessLevel?: import("../../types").TActivityLevel;
+    fitnessGoal?: import("../../types").TFitnessGoal;
+    bodyFatPercentage?: number;
+}): IUserContext;
+/**
+ * Derives a user's training age bracket based on their account age and workout frequency.
+ * Used for RIR attenuation and reference max scaling (P2-10).
+ */
+export declare function deriveTrainingAgeBracket(accountAgeDays: number, totalSessionCount: number): import("./types").TTrainingAgeBracket;

package/dist/utils/scoringWorkout/helpers.js

@@ -0,0 +1,245 @@
+"use strict";
+// helpers.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeParseFloat = safeParseFloat;
+exports.parseDurationMmSs = parseDurationMmSs;
+exports.clamp = clamp;
+exports.mean = mean;
+exports.standardDeviation = standardDeviation;
+exports.coefficientOfVariation = coefficientOfVariation;
+exports.rirToEffortFraction = rirToEffortFraction;
+exports.rpeToEffortFraction = rpeToEffortFraction;
+exports.getEffortFraction = getEffortFraction;
+exports.extractUserContext = extractUserContext;
+exports.deriveTrainingAgeBracket = deriveTrainingAgeBracket;
+const constants_1 = require("./constants");
+// We reference these types but don't import them to keep this module decoupled.
+// The caller passes the raw values; we just parse them.
+// ---------------------------------------------------------------------------
+// Numeric Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Safely parse a string to a float.
+ * Returns `fallback` if the input is undefined, empty, NaN, or negative.
+ *
+ * @example
+ * safeParseFloat("10.5")       // 10.5
+ * safeParseFloat("")           // 0
+ * safeParseFloat(undefined)    // 0
+ * safeParseFloat("abc", 5)    // 5
+ */
+function safeParseFloat(value, fallback = 0) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const parsed = parseFloat(value);
+    if (isNaN(parsed) || parsed < 0)
+        return fallback;
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Duration Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse a "MM:SS" or "M:SS" or "HH:MM:SS" duration string into total seconds.
+ *
+ * Handles edge cases:
+ * - "04:55" → 295 seconds
+ * - "10:00" → 600 seconds
+ * - "1:30:00" → 5400 seconds
+ * - "0:45" → 45 seconds (could be MM:SS with 0 min, or just 45 sec)
+ * - "" or invalid → fallbackSecs
+ *
+ * @param duration   The "MM:SS" string from TRecord.durationMmSs
+ * @param fallbackSecs  Returned when parsing fails (default: 0)
+ */
+function parseDurationMmSs(duration, fallbackSecs = 0) {
+    if (!duration || typeof duration !== "string")
+        return fallbackSecs;
+    const parts = duration.split(":").map(Number);
+    // Filter out NaN parts
+    if (parts.some(isNaN))
+        return fallbackSecs;
+    if (parts.length === 3) {
+        // HH:MM:SS
+        const [hours, minutes, seconds] = parts;
+        const total = hours * 3600 + minutes * 60 + seconds;
+        return total > 0 ? total : fallbackSecs;
+    }
+    if (parts.length === 2) {
+        // MM:SS
+        const [minutes, seconds] = parts;
+        const total = minutes * 60 + seconds;
+        return total > 0 ? total : fallbackSecs;
+    }
+    if (parts.length === 1 && parts[0] > 0) {
+        // Just seconds
+        return parts[0];
+    }
+    return fallbackSecs;
+}
+// ---------------------------------------------------------------------------
+// Math Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Clamp a value between min and max (inclusive).
+ */
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Calculate the arithmetic mean of an array of numbers.
+ * Returns 0 for an empty array.
+ */
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+/**
+ * Calculate the standard deviation (population) of an array of numbers.
+ * Returns 0 for arrays with fewer than 2 elements.
+ */
+function standardDeviation(values) {
+    if (values.length < 2)
+        return 0;
+    const avg = mean(values);
+    const squaredDiffs = values.map((v) => Math.pow((v - avg), 2));
+    return Math.sqrt(mean(squaredDiffs));
+}
+/**
+ * Coefficient of variation: stdDev / mean.
+ * Returns 0 if mean is 0 (avoids division by zero).
+ * A CV of 0 means perfect consistency; higher = more variable.
+ */
+function coefficientOfVariation(values) {
+    const avg = mean(values);
+    if (avg === 0)
+        return 0;
+    return standardDeviation(values) / avg;
+}
+// ---------------------------------------------------------------------------
+// Effort Conversion
+// ---------------------------------------------------------------------------
+/**
+ * Convert RIR (Reps In Reserve) to an effort fraction (0.0 – 1.0).
+ *
+ * RIR scale: 0 = at failure (max effort), 10 = trivial (minimal effort).
+ *
+ * Uses a non-linear curve (exponent 1.3) because the perceptual and
+ * physiological cost of the last 2–3 reps near failure is disproportionately
+ * higher than the middle reps.
+ *
+ * Output range: ~0.50 (RIR 10) → ~1.30 (RIR 0)
+ * This is an "effort multiplier" not a pure 0–1, but the naming matches
+ * its usage in calorie and fatigue calculations.
+ *
+ * @example
+ * rirToEffortFraction(0)  // ~1.30 (at failure)
+ * rirToEffortFraction(3)  // ~0.94
+ * rirToEffortFraction(5)  // ~0.82
+ * rirToEffortFraction(10) // ~0.50
+ */
+function rirToEffortFraction(rir) {
+    const clampedRir = clamp(rir, 0, 10);
+    const normalized = (10 - clampedRir) / 10; // 0 at RIR 10, 1 at RIR 0
+    return (constants_1.EFFORT_FRACTION_BASE +
+        constants_1.EFFORT_FRACTION_RANGE * Math.pow(normalized, constants_1.EFFORT_CURVE_EXPONENT));
+}
+/**
+ * Convert RPE (Rate of Perceived Exertion) to an effort fraction.
+ *
+ * RPE scale: 1 = very easy, 10 = maximal effort.
+ * Same non-linear curve as RIR conversion.
+ *
+ * @example
+ * rpeToEffortFraction(10) // ~1.30 (max effort)
+ * rpeToEffortFraction(7)  // ~0.94
+ * rpeToEffortFraction(5)  // ~0.82
+ * rpeToEffortFraction(1)  // ~0.54
+ */
+function rpeToEffortFraction(rpe) {
+    const clampedRpe = clamp(rpe, 1, 10);
+    const normalized = clampedRpe / 10; // 0.1 at RPE 1, 1.0 at RPE 10
+    return (constants_1.EFFORT_FRACTION_BASE +
+        constants_1.EFFORT_FRACTION_RANGE * Math.pow(normalized, constants_1.EFFORT_CURVE_EXPONENT));
+}
+/**
+ * Extract effort fraction from a raw TRecord.
+ *
+ * Priority: RIR > RPE > default (0.6).
+ * RIR is preferred because it's more objective (countable reps left)
+ * while RPE is subjective.
+ *
+ * @param record - Any TRecord (we only read the rpe/rir fields)
+ */
+function getEffortFraction(record) {
+    // Try RIR first (more objective)
+    if (record.rir !== undefined && record.rir !== "") {
+        const rir = safeParseFloat(record.rir, -1);
+        if (rir >= 0)
+            return rirToEffortFraction(rir);
+    }
+    // Fall back to RPE
+    if (record.rpe !== undefined && record.rpe !== "") {
+        const rpe = safeParseFloat(record.rpe, -1);
+        if (rpe >= 1)
+            return rpeToEffortFraction(rpe);
+    }
+    // No effort data available
+    return constants_1.DEFAULT_EFFORT_FRACTION;
+}
+// ---------------------------------------------------------------------------
+// User Context
+// ---------------------------------------------------------------------------
+/**
+ * Extract a validated user context from TUserMetric.
+ * Guarantees all fields have usable values (no undefined).
+ *
+ * @param user - The raw TUserMetric object
+ */
+function extractUserContext(user) {
+    var _a, _b, _c;
+    const weightKg = user.weightKg && user.weightKg > 20 && user.weightKg < 300
+        ? user.weightKg
+        : constants_1.DEFAULT_USER_WEIGHT_KG;
+    const heightCm = user.heightCm && user.heightCm > 100 && user.heightCm < 250
+        ? user.heightCm
+        : constants_1.DEFAULT_USER_HEIGHT_CM;
+    let age = constants_1.DEFAULT_USER_AGE;
+    if (user.dob) {
+        const dob = typeof user.dob === "string" ? new Date(user.dob) : user.dob;
+        if (!isNaN(dob.getTime())) {
+            const today = new Date();
+            age = today.getFullYear() - dob.getFullYear();
+            // Adjust if birthday hasn't happened yet this year
+            const monthDiff = today.getMonth() - dob.getMonth();
+            if (monthDiff < 0 ||
+                (monthDiff === 0 && today.getDate() < dob.getDate())) {
+                age--;
+            }
+            // Sanity check
+            if (age < 10 || age > 100)
+                age = constants_1.DEFAULT_USER_AGE;
+        }
+    }
+    return {
+        weightKg,
+        heightCm,
+        gender: user.gender || "unmentioned",
+        age,
+        fitnessLevel: (_a = user.fitnessLevel) !== null && _a !== void 0 ? _a : "moderately-active",
+        fitnessGoal: (_b = user.fitnessGoal) !== null && _b !== void 0 ? _b : "general",
+        bodyFatPercentage: (_c = user.bodyFatPercentage) !== null && _c !== void 0 ? _c : 20,
+    };
+}
+/**
+ * Derives a user's training age bracket based on their account age and workout frequency.
+ * Used for RIR attenuation and reference max scaling (P2-10).
+ */
+function deriveTrainingAgeBracket(accountAgeDays, totalSessionCount) {
+    if (accountAgeDays < 90 || totalSessionCount < 20)
+        return "beginner";
+    if (accountAgeDays < 365 || totalSessionCount < 100)
+        return "intermediate";
+    return "advanced";
+}

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

@@ -0,0 +1,27 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM
+ * ============================================================================
+ *
+ *   calculateExerciseScoreV2({ exercise, record, user, historicalContext? }) => IScoreResult
+ *
+ *   IScoreResult = {
+ *     score: number,                      // 0–100 quality of execution
+ *     muscleScores: Record<string, number>, // 0–100 per muscle fatigue
+ *     calorieBurn: number,                // kcal (placeholder: 0 until Phase 3)
+ *     qualityBreakdown: IQualityBreakdown // completion/consistency/effort/rest sub-scores
+ *   }
+ *
+ * Internally computes muscle fatigue (Pillar 2) and quality score (Pillar 3).
+ * Calorie burn (Pillar 1) is implemented in calculateCalories.ts but not yet
+ * wired into the save flow — scheduled for Phase 3.
+ */
+import { TExercise, TRecord, TUserMetric } from "../../types";
+import type { IScoreResult } from "./types";
+export { calculateTotalVolume } from "./calculateTotalVolume";
+export declare const calculateExerciseScoreV2: (param: {
+    exercise: TExercise;
+    record: TRecord[];
+    user: TUserMetric;
+    historicalContext?: import("./types").IHistoricalContext;
+}) => IScoreResult;