@dgpholdings/greatoak-shared 1.2.53 → 1.2.55

package/dist/utils/scoringWorkout/index.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * ============================================================================
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateExerciseScoreV2 = exports.calculateTotalVolume = void 0;
+const calculateMuscleFatiue_1 = require("./calculateMuscleFatiue");
+const calculateQualityScore_1 = require("./calculateQualityScore");
+const helpers_1 = require("./helpers");
+const parseRecords_1 = require("./parseRecords");
+var calculateTotalVolume_1 = require("./calculateTotalVolume");
+Object.defineProperty(exports, "calculateTotalVolume", { enumerable: true, get: function () { return calculateTotalVolume_1.calculateTotalVolume; } });
+// ---------------------------------------------------------------------------
+// Main Function — existing signature
+// ---------------------------------------------------------------------------
+const calculateExerciseScoreV2 = (param) => {
+    const { exercise, record, user, historicalContext } = param;
+    const userContext = (0, helpers_1.extractUserContext)(user);
+    const parsedSets = (0, parseRecords_1.parseRecords)(record, exercise.timingGuardrails, historicalContext);
+    // Pillar 2: Muscle Fatigue → muscleScores
+    const muscleScores = (0, calculateMuscleFatiue_1.calculateMuscleFatigue)(parsedSets, {
+        primaryMuscles: exercise.primaryMuscles,
+        secondaryMuscles: exercise.secondaryMuscles,
+        difficultyLevel: exercise.difficultyLevel,
+        metabolicData: {
+            compoundMultiplier: exercise.metabolicData.compoundMultiplier,
+            muscleGroupFactor: exercise.metabolicData.muscleGroupFactor,
+        },
+        scoringSpecialHandling: exercise.scoringSpecialHandling,
+    }, userContext, exercise.timingGuardrails, historicalContext);
+    // Pillar 3: Quality Score → score
+    const isStrictTimingModeScoring = record.some((r) => r.isStrictMode);
+    const { score, breakdown } = (0, calculateQualityScore_1.calculateQualityScore)(parsedSets, record, exercise.timingGuardrails, isStrictTimingModeScoring, userContext, historicalContext);
+    return {
+        score,
+        muscleScores,
+        calorieBurn: 0, // Placeholder until Pillar 1 is fully wired in Phase 3
+        qualityBreakdown: breakdown,
+    };
+};
+exports.calculateExerciseScoreV2 = calculateExerciseScoreV2;

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

@@ -0,0 +1,68 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Record Parser
+ * ============================================================================
+ *
+ * Transforms raw TRecord[] into clean IParsedSet[].
+ *
+ * This is the SINGLE POINT of data cleaning. After this step, all downstream
+ * code (calories, fatigue, quality) works with guaranteed-valid numbers.
+ *
+ * VALIDATION STRATEGY:
+ * The exercise's `timingGuardrails` is the PRIMARY source of truth for
+ * what constitutes valid timing data. Each exercise defines its own:
+ *   - restPeriods.minimum / maximum  → acceptable rest range
+ *   - setDuration.min / max          → acceptable work duration (duration type)
+ *   - singleRep.min / max            → acceptable rep timing (rep-based types)
+ *
+ * Global constants (ABSOLUTE_* and FALLBACK_*) are ONLY used when
+ * timingGuardrails is completely missing from the exercise.
+ *
+ * Responsibilities:
+ * 1. Filter out incomplete sets (isDone === false)
+ * 2. Parse all string fields to numbers
+ * 3. Estimate active work duration when not measured
+ * 4. Validate timing against exercise-specific guardrails
+ * 5. Compute effort fraction per set
+ */
+import type { TRecord } from "../../types";
+import type { IParsedSet, IHistoricalContext } from "./types";
+/**
+ * Full timing guardrails shape from TExercise.
+ */
+export interface ITimingGuardrails {
+    type?: string;
+    stressRestBonus?: number;
+    fatigueMultiplier?: number;
+    setupTypicalSecs?: number;
+    restPeriods?: {
+        minimum?: number;
+        typical?: number;
+        maximum?: number;
+        optimalRange?: [number, number];
+    };
+    singleRep?: {
+        min?: number;
+        max?: number;
+        typical?: number;
+    };
+    setDuration?: {
+        min?: number;
+        max?: number;
+        typical?: number;
+    };
+    pacing?: {
+        minPacePerUnit?: number;
+        maxPacePerUnit?: number;
+        typicalPacePerUnit?: number;
+    };
+}
+/**
+ * Parse and clean raw records into a validated set array.
+ *
+ * @param records           Raw TRecord[] from the workout
+ * @param timingGuardrails  Exercise's timing guardrails (for validation & fallbacks)
+ * @param historicalContext Optional historical data (used for RIR attenuation)
+ * @returns                 Cleaned IParsedSet[] with only completed, valid sets
+ */
+export declare function parseRecords(records: TRecord[], timingGuardrails?: ITimingGuardrails, historicalContext?: IHistoricalContext): IParsedSet[];

package/dist/utils/scoringWorkout/parseRecords.js

@@ -0,0 +1,281 @@
+"use strict";
+// parseRecords.ts
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Record Parser
+ * ============================================================================
+ *
+ * Transforms raw TRecord[] into clean IParsedSet[].
+ *
+ * This is the SINGLE POINT of data cleaning. After this step, all downstream
+ * code (calories, fatigue, quality) works with guaranteed-valid numbers.
+ *
+ * VALIDATION STRATEGY:
+ * The exercise's `timingGuardrails` is the PRIMARY source of truth for
+ * what constitutes valid timing data. Each exercise defines its own:
+ *   - restPeriods.minimum / maximum  → acceptable rest range
+ *   - setDuration.min / max          → acceptable work duration (duration type)
+ *   - singleRep.min / max            → acceptable rep timing (rep-based types)
+ *
+ * Global constants (ABSOLUTE_* and FALLBACK_*) are ONLY used when
+ * timingGuardrails is completely missing from the exercise.
+ *
+ * Responsibilities:
+ * 1. Filter out incomplete sets (isDone === false)
+ * 2. Parse all string fields to numbers
+ * 3. Estimate active work duration when not measured
+ * 4. Validate timing against exercise-specific guardrails
+ * 5. Compute effort fraction per set
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRecords = parseRecords;
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+// ---------------------------------------------------------------------------
+// Main Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse and clean raw records into a validated set array.
+ *
+ * @param records           Raw TRecord[] from the workout
+ * @param timingGuardrails  Exercise's timing guardrails (for validation & fallbacks)
+ * @param historicalContext Optional historical data (used for RIR attenuation)
+ * @returns                 Cleaned IParsedSet[] with only completed, valid sets
+ */
+function parseRecords(records, timingGuardrails, historicalContext) {
+    const doneRecords = records.filter((r) => r.isDone);
+    return doneRecords
+        .map((record, index) => parseOneRecord(record, index, doneRecords.length, timingGuardrails, historicalContext))
+        .filter((set) => set !== null);
+}
+// ---------------------------------------------------------------------------
+// Single Record Parser
+// ---------------------------------------------------------------------------
+function parseOneRecord(record, index, totalSets, guardrails, historicalContext) {
+    const type = record.type;
+    let effortFraction = (0, helpers_1.getEffortFraction)(record);
+    // P2-10: RIR/RPE attenuation for beginners
+    if ((historicalContext === null || historicalContext === void 0 ? void 0 : historicalContext.trainingAgeBracket) === "beginner") {
+        effortFraction =
+            constants_1.DEFAULT_EFFORT_FRACTION +
+                (effortFraction - constants_1.DEFAULT_EFFORT_FRACTION) * 0.5;
+    }
+    // Parse rest duration using exercise-specific guardrails for validation
+    const restDurationSecs = resolveRestDuration(record.restDurationSecs, index, totalSets, guardrails);
+    switch (type) {
+        case "weight-reps":
+            return parseWeightReps(record, effortFraction, restDurationSecs, guardrails);
+        case "reps-only":
+            return parseRepsOnly(record, effortFraction, restDurationSecs, guardrails);
+        case "duration":
+            return parseDuration(record, effortFraction, restDurationSecs, guardrails);
+        case "cardio-machine":
+            return parseCardioMachine(record, effortFraction, restDurationSecs);
+        case "cardio-free":
+            return parseCardioFree(record, effortFraction, restDurationSecs);
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type-Specific Parsers
+// ---------------------------------------------------------------------------
+function parseWeightReps(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b, _c;
+    const kg = (0, helpers_1.safeParseFloat)(record.kg);
+    const reps = (0, helpers_1.safeParseFloat)(record.reps);
+    // Estimate active duration: (reps × seconds-per-rep) + setup
+    const secsPerRep = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SECS_PER_REP;
+    const setup = (_c = guardrails === null || guardrails === void 0 ? void 0 : guardrails.setupTypicalSecs) !== null && _c !== void 0 ? _c : 0;
+    const estimatedDuration = reps * secsPerRep + setup;
+    const activeDurationSecs = resolveWorkDuration(record.workDurationSecs, estimatedDuration, guardrails);
+    return {
+        type: "weight-reps",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        kg,
+        reps,
+    };
+}
+function parseRepsOnly(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b, _c;
+    const reps = (0, helpers_1.safeParseFloat)(record.reps);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
+    const secsPerRep = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SECS_PER_REP;
+    const setup = (_c = guardrails === null || guardrails === void 0 ? void 0 : guardrails.setupTypicalSecs) !== null && _c !== void 0 ? _c : 0;
+    const estimatedDuration = reps * secsPerRep + setup;
+    const activeDurationSecs = resolveWorkDuration(record.workDurationSecs, estimatedDuration, guardrails);
+    return {
+        type: "reps-only",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        reps,
+        auxWeightKg,
+    };
+}
+function parseDuration(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b;
+    // Primary: parse the user's recorded duration
+    // Fallback: exercise's typical set duration → global fallback
+    const fallbackDuration = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.setDuration) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SET_DURATION_SECS;
+    const durationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs, fallbackDuration);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
+    if (durationSecs === 0)
+        return null;
+    // For duration exercises, the parsed durationMmSs IS the active duration
+    // We validate it against guardrails to get the final value
+    const activeDurationSecs = resolveWorkDuration(durationSecs, fallbackDuration, guardrails);
+    return {
+        type: "duration",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        // Use the SAME validated value for both — activeDurationSecs is used
+        // for calorie time calculation, durationSecs is used for the
+        // short/medium/long multiplier classification. They must agree.
+        durationSecs: activeDurationSecs,
+        auxWeightKg,
+    };
+}
+function parseCardioMachine(record, effortFraction, restDurationSecs) {
+    const speed = (0, helpers_1.safeParseFloat)(record.speed);
+    const inclinePercentage = (0, helpers_1.safeParseFloat)(record.inclinePercentage);
+    const resistanceLevel = (0, helpers_1.safeParseFloat)(record.resistanceLevel);
+    const distance = (0, helpers_1.safeParseFloat)(record.distance);
+    const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
+    // Need at least duration or distance to be meaningful
+    if (cardioDurationSecs === 0 && distance === 0)
+        return null;
+    const activeDurationSecs = cardioDurationSecs > 0 ? cardioDurationSecs : 0;
+    return {
+        type: "cardio-machine",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        speed,
+        inclinePercentage,
+        resistanceLevel,
+        distance,
+        cardioDurationSecs,
+    };
+}
+function parseCardioFree(record, effortFraction, restDurationSecs) {
+    const distance = (0, helpers_1.safeParseFloat)(record.distance);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
+    const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
+    if (cardioDurationSecs === 0 && distance === 0)
+        return null;
+    const activeDurationSecs = cardioDurationSecs > 0 ? cardioDurationSecs : 0;
+    return {
+        type: "cardio-free",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        distance,
+        auxWeightKg,
+        cardioDurationSecs,
+    };
+}
+// ---------------------------------------------------------------------------
+// Duration Resolution Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve and validate work duration for a set.
+ *
+ * Validation cascade:
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │ 1. Absolute sanity check (catches truly broken data)        │
+ * │    measured < 1s or > 14400s → reject                       │
+ * │                                                             │
+ * │ 2. Exercise-specific validation (PRIMARY)                   │
+ * │    duration type: check against setDuration.min / max       │
+ * │    rep type: check against estimate ± tolerance             │
+ * │    Grace factor: 2× on max, 0.5× on min                    │
+ * │                                                             │
+ * │ 3. Passed all checks → use measured value                   │
+ * │                                                             │
+ * │ 4. No measured value → use estimated                        │
+ * └──────────────────────────────────────────────────────────────┘
+ */
+function resolveWorkDuration(measured, estimated, guardrails) {
+    var _a, _b;
+    if (measured !== undefined && measured > 0) {
+        // 1. Absolute sanity check
+        if (measured < constants_1.ABSOLUTE_WORK_MIN || measured > constants_1.ABSOLUTE_WORK_MAX) {
+            return Math.max(estimated, constants_1.ABSOLUTE_WORK_MIN);
+        }
+        // 2. Exercise-specific validation for duration-type exercises
+        if (guardrails === null || guardrails === void 0 ? void 0 : guardrails.setDuration) {
+            const minReasonable = ((_a = guardrails.setDuration.min) !== null && _a !== void 0 ? _a : 1) * 0.5;
+            const maxReasonable = ((_b = guardrails.setDuration.max) !== null && _b !== void 0 ? _b : constants_1.ABSOLUTE_WORK_MAX) * 2;
+            if (measured < minReasonable || measured > maxReasonable) {
+                return estimated; // Measured seems wrong for this exercise
+            }
+        }
+        // 2b. Exercise-specific validation for rep-based exercises
+        if ((guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) && estimated > 0) {
+            // Measured should be within 3× of our estimate
+            // (generous because user might pause mid-set)
+            if (measured > estimated * 3 || measured < estimated * 0.2) {
+                return estimated;
+            }
+        }
+        // 3. Passed validation
+        return measured;
+    }
+    // 4. No measured value
+    return Math.max(estimated, constants_1.ABSOLUTE_WORK_MIN);
+}
+/**
+ * Resolve and validate rest duration for a set.
+ *
+ * Validation cascade:
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │ 1. Last set with no data → null (no rest after final set)   │
+ * │                                                             │
+ * │ 2. Absolute sanity check (< 0 or > 3600s)                  │
+ * │    → use exercise typical rest                              │
+ * │                                                             │
+ * │ 3. Exercise-specific validation (PRIMARY)                   │
+ * │    Check against restPeriods.minimum / maximum              │
+ * │    Grace factor: 50% on each side                           │
+ * │    Outside → use exercise typical rest                      │
+ * │                                                             │
+ * │ 4. Passed checks → use measured value                       │
+ * │                                                             │
+ * │ 5. No measured data → exercise typical → global fallback    │
+ * └──────────────────────────────────────────────────────────────┘
+ */
+function resolveRestDuration(measured, setIndex, totalSets, guardrails) {
+    var _a, _b, _c;
+    // 1. Last set with no rest data → null
+    if (setIndex === totalSets - 1 &&
+        (measured === undefined || measured === 0)) {
+        return null;
+    }
+    // Extract exercise-specific rest config
+    const exerciseRestMin = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _a === void 0 ? void 0 : _a.minimum;
+    const exerciseRestMax = (_b = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _b === void 0 ? void 0 : _b.maximum;
+    const exerciseRestTypical = (_c = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _c === void 0 ? void 0 : _c.typical;
+    if (measured !== undefined && measured > 0) {
+        // 2. Absolute sanity check
+        if (measured < constants_1.ABSOLUTE_REST_MIN || measured > constants_1.ABSOLUTE_REST_MAX) {
+            return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+        }
+        // 3. Exercise-specific validation
+        if (exerciseRestMin !== undefined && exerciseRestMax !== undefined) {
+            const graceFactor = 0.5;
+            const lowerBound = exerciseRestMin * (1 - graceFactor);
+            const upperBound = exerciseRestMax * (1 + graceFactor);
+            if (measured < lowerBound || measured > upperBound) {
+                return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+            }
+        }
+        // 4. Passed validation
+        return measured;
+    }
+    // 5. No measured data → exercise typical → global fallback
+    return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+}

package/dist/utils/scoringWorkout/scoringWorkout.integration.test.d.ts

@@ -0,0 +1 @@
+export {};