@dgpholdings/greatoak-shared 1.2.54 → 1.2.55

package/dist/utils/scoringWorkout/scoringWorkout.integration.test.js

@@ -0,0 +1,439 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("./index");
+const parseRecords_1 = require("./parseRecords");
+const templateExercises_mock_1 = require("../../__mocks__/templateExercises.mock");
+const exercises_mock_1 = require("../../__mocks__/exercises.mock");
+const user_mock_1 = require("../../__mocks__/user.mock");
+(0, vitest_1.describe)("Scoring Engine Phase 1 Integration Tests", () => {
+    (0, vitest_1.it)("P1-1 proper proof: Partial workout with undefined rest on last done set + strict mode", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsPartial;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        // Modify to prove P1-1: the LAST done set (index 1) must have NO rest data.
+        // Set 0 has good rest, Set 1 has no rest. If P1-1 is fixed, Set 1 gets null rest
+        // and is excluded from the rest average, meaning only Set 0's perfect rest is scored.
+        const strictRecords = template.initialRecords.map((r, i) => {
+            if (i === 1) {
+                const { restDurationSecs } = r, rest = __rest(r, ["restDurationSecs"]); // remove rest data
+                return Object.assign(Object.assign({}, rest), { isStrictMode: true });
+            }
+            return Object.assign(Object.assign({}, r), { isStrictMode: true, restDurationSecs: 120 }); // 120 is optimal
+        });
+        // Direct parseRecords assertion — the real proof of P1-1.
+        // With fix (totalSets=doneRecords.length=2): Set1 index=1 === 2-1 → null rest.
+        // Without fix (totalSets=records.length=4): Set1 index=1 !== 3 → gets typical (120s).
+        const parsed = (0, parseRecords_1.parseRecords)(strictRecords, exercise.timingGuardrails);
+        (0, vitest_1.expect)(parsed[1].restDurationSecs).toBeNull();
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: strictRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(50); // 2/4 done
+        // Only Set0 (120s, optimal) contributes to rest — Set1 is correctly excluded
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBeGreaterThan(95);
+    });
+    (0, vitest_1.it)("P1-2: mockTemplateWeightRepsFailedSet - zero rep set still counts towards completion if isDone is true", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsFailedSet;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(67); // 2/3 done
+    });
+    (0, vitest_1.it)("P1-1 + P1-3: mockTemplateLazyLogger - handles missing data gracefully using fallbacks", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.lazyLogger;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        const { score, qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(score).toBeGreaterThan(50);
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(100);
+    });
+    (0, vitest_1.it)("Distracted logger: clamping path (Original 600s rest → clamped to typical → good rest score)", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.distractedLogger;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        // Use 600s rest. 600 > 300 * 1.5, so it gets clamped to typical (120s)
+        // 120s is in the optimal range (90-180), so rest score should be 100.
+        const strictRecords = template.initialRecords.map((r, i) => (Object.assign(Object.assign({}, r), { isStrictMode: true, restDurationSecs: i === 0 ? 600 : 120 })));
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: strictRecords,
+            user: user_mock_1.mockUser,
+        });
+        // Both sets end up evaluating as 120s (optimal) due to clamping + explicit
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBe(100);
+    });
+    (0, vitest_1.it)("Distracted logger: penalty path (350s rest → outside acceptableMax → score 50)", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.distractedLogger;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        // 350s is within grace bounds (450s) but outside acceptableMax (300s).
+        const strictRecords = template.initialRecords.map((r, i) => (Object.assign(Object.assign({}, r), { isStrictMode: true, restDurationSecs: i === 0 ? 350 : 120 })));
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: strictRecords,
+            user: user_mock_1.mockUser,
+        });
+        // Set 1 (350s) -> 50. Set 2 (120s) -> 100. Avg = 75. Plus 5 point bonus = 80.
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBe(80);
+    });
+    (0, vitest_1.it)("mockTemplateAllUndone - Score = 0, no errors", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.allUndone;
+        const exercise = exercises_mock_1.mockExerciseWeightReps;
+        const { score, qualityBreakdown, muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(score).toBe(0);
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(0);
+        (0, vitest_1.expect)(qualityBreakdown.consistency).toBe(0);
+        (0, vitest_1.expect)(qualityBreakdown.effortAdequacy).toBe(0);
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBe(0);
+        (0, vitest_1.expect)(Object.keys(muscleScores).length).toBe(0);
+    });
+    (0, vitest_1.it)("Trivial workout: low muscleScores (3s duration → primary muscle value < 5)", () => {
+        const exercise = exercises_mock_1.mockExerciseDuration;
+        const trivialRecord = [
+            {
+                type: "duration",
+                isDone: true,
+                isStrictMode: false,
+                durationMmSs: "00:03", // 3 seconds
+                auxWeightKg: "0",
+            }
+        ];
+        const { score, qualityBreakdown, muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: trivialRecord,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(100);
+        (0, vitest_1.expect)(score).toBe(87);
+        // Check fatigue pillar correctness
+        const primaryMuscle = exercise.primaryMuscles[0];
+        (0, vitest_1.expect)(muscleScores[primaryMuscle]).toBeLessThan(5);
+    });
+    (0, vitest_1.it)("P1-3 direct proof: parseRecords includes setupTypicalSecs in activeDurationSecs", () => {
+        var _a, _b, _c;
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const parsed = (0, parseRecords_1.parseRecords)(template.initialRecords, exercises_mock_1.mockExerciseWeightReps.timingGuardrails);
+        const record = template.initialRecords[0];
+        const reps = parseFloat(record.type === "weight-reps" ? record.reps : "0");
+        const guardrails = exercises_mock_1.mockExerciseWeightReps.timingGuardrails;
+        const typicalSecs = (guardrails === null || guardrails === void 0 ? void 0 : guardrails.type) === "weight-reps" ? ((_b = (_a = guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : 0) : 0;
+        const setupSecs = (_c = guardrails === null || guardrails === void 0 ? void 0 : guardrails.setupTypicalSecs) !== null && _c !== void 0 ? _c : 0;
+        const expectedDuration = reps * typicalSecs + setupSecs; // 10 * 3.5 + 10 = 45
+        (0, vitest_1.expect)(parsed[0].activeDurationSecs).toBe(expectedDuration);
+    });
+    (0, vitest_1.it)("Muscle fatigue shape: quadriceps and glutes-maximus present in [0, 100]", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const { muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(muscleScores).toHaveProperty("quadriceps");
+        (0, vitest_1.expect)(muscleScores).toHaveProperty("glutes-maximus");
+        (0, vitest_1.expect)(muscleScores["quadriceps"]).toBeGreaterThanOrEqual(0);
+        (0, vitest_1.expect)(muscleScores["quadriceps"]).toBeLessThanOrEqual(100);
+    });
+    (0, vitest_1.it)("stretch-mobility = zero fatigue: muscleScores should be empty", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.duration;
+        const exercise = Object.assign(Object.assign({}, exercises_mock_1.mockExerciseDuration), { scoringSpecialHandling: "stretch-mobility" });
+        const { muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(Object.keys(muscleScores).length).toBe(0);
+    });
+    (0, vitest_1.it)("no guardrails doesn't crash: mockExerciseNoGuardrails scores > 0", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const { score } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseNoGuardrails,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(score).toBeGreaterThan(0);
+    });
+    (0, vitest_1.it)("RPE/RIR scoring: effortAdequacy calculates correctly for various inputs", () => {
+        const records = [
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "10", rpe: "8" }, // 100
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "10", rpe: "4" }, // 60 (Distance = 2 -> 100 - 2*20 = 60)
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "10", rir: "0" }, // 80 (Distance = 1 -> 100 - 1*20 = 80)
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "10" } // 70 (No data)
+        ];
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: records,
+            user: user_mock_1.mockUser,
+        });
+        // Average: (100 + 60 + 80 + 70) / 4 = 77.5 -> 78
+        (0, vitest_1.expect)(qualityBreakdown.effortAdequacy).toBe(78);
+    });
+    (0, vitest_1.it)("Progressive overload detection: mockTemplateWeightRepsMicroLoaded -> consistency >= 75", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsMicroLoaded;
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.consistency).toBeGreaterThanOrEqual(75);
+    });
+    (0, vitest_1.it)("Single-set rest is neutral: mockTemplateSingleSet -> restDiscipline = 75", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.singleSet;
+        const strictRecords = template.initialRecords.map(r => {
+            const { restDurationSecs } = r, rest = __rest(r, ["restDurationSecs"]); // remove rest data so it becomes the null case
+            return Object.assign(Object.assign({}, rest), { isStrictMode: true });
+        });
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: strictRecords,
+            user: user_mock_1.mockUser,
+        });
+        // Single set → last set gets null rest → setsWithRest=[] → REST_NO_DATA_SCORE (75)
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBe(75);
+    });
+    (0, vitest_1.it)("Non-sequential completion: mockTemplateNonSequential -> completion = 67%", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.nonSequential;
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.completion).toBe(67);
+    });
+    (0, vitest_1.it)("IScoreResult has 4 fields: calorieBurn and qualityBreakdown are present", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const result = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(result).toHaveProperty("score");
+        (0, vitest_1.expect)(result).toHaveProperty("muscleScores");
+        (0, vitest_1.expect)(result).toHaveProperty("calorieBurn");
+        (0, vitest_1.expect)(result).toHaveProperty("qualityBreakdown");
+    });
+    (0, vitest_1.it)("Cardio exercises: mockTemplateCardioMachine/Free score > 0 and use correct muscles", () => {
+        const machineResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseCardioMachine,
+            record: templateExercises_mock_1.mockTemplateExercisesDictionary.cardioMachine.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(machineResult.score).toBeGreaterThan(0);
+        (0, vitest_1.expect)(machineResult.muscleScores).toHaveProperty("quadriceps");
+        const freeResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseCardioFree,
+            record: templateExercises_mock_1.mockTemplateExercisesDictionary.cardioFree.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(freeResult.score).toBeGreaterThan(0);
+        (0, vitest_1.expect)(freeResult.muscleScores).toHaveProperty("quadriceps");
+    });
+    (0, vitest_1.it)("reps-only with aux weight: mockTemplateRepsOnly -> score > 0, pectoralis-major mapped", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.repsOnly;
+        const { score, muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseRepsOnly,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(score).toBeGreaterThan(0);
+        (0, vitest_1.expect)(muscleScores).toHaveProperty("pectoralis-major");
+    });
+    (0, vitest_1.it)("Duration exercise: mockTemplateDuration -> abs-lower/abs-upper in muscleScores", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.duration;
+        const { score, muscleScores } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseDuration,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(score).toBeGreaterThan(0);
+        (0, vitest_1.expect)(muscleScores).toHaveProperty("abs-lower");
+        (0, vitest_1.expect)(muscleScores).toHaveProperty("abs-upper");
+    });
+    (0, vitest_1.it)("Default restDiscipline (non-strict): Any non-strict call -> restDiscipline === 75", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        // Standard mock is `isStrictMode: false`
+        const { qualityBreakdown } = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+        });
+        (0, vitest_1.expect)(qualityBreakdown.restDiscipline).toBe(75); // REST_NO_DATA_SCORE from constants.ts
+    });
+});
+(0, vitest_1.describe)("Scoring Engine Phase 2 Integration Tests", () => {
+    // ---------------------------------------------------------------------------
+    // P2-1: fitnessLevel scales referenceMax
+    // ---------------------------------------------------------------------------
+    (0, vitest_1.it)("P2-1: sedentary user scores higher muscle fatigue than very-active for identical work", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const sedentaryUser = Object.assign(Object.assign({}, user_mock_1.mockUser), { fitnessLevel: "sedentary" });
+        const veryActiveUser = Object.assign(Object.assign({}, user_mock_1.mockUser), { fitnessLevel: "very-active" });
+        const sedentaryResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: sedentaryUser,
+        });
+        const veryActiveResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: veryActiveUser,
+        });
+        // sedentary: activityScale 0.70 → lower referenceMax denominator → higher normalised score
+        // very-active: activityScale 1.20 → higher referenceMax denominator → lower normalised score
+        (0, vitest_1.expect)(sedentaryResult.muscleScores["quadriceps"]).toBeGreaterThan(veryActiveResult.muscleScores["quadriceps"]);
+    });
+    // ---------------------------------------------------------------------------
+    // P2-3: fitnessGoal-aware quality weights
+    // ---------------------------------------------------------------------------
+    (0, vitest_1.it)("P2-3: strength goal scores higher than hypertrophy when effort is good but completion is 50%", () => {
+        // 2 of 4 sets done (50% completion) with RPE 8 (effort in productive zone)
+        // strength weights effortAdequacy 0.45 vs hypertrophy 0.30 — effort matters more
+        const partialWithEffort = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsPartial.initialRecords.map((r) => (Object.assign(Object.assign({}, r), { rpe: "8" })));
+        const strengthUser = Object.assign(Object.assign({}, user_mock_1.mockUser), { fitnessGoal: "strength" });
+        const hypertrophyUser = Object.assign(Object.assign({}, user_mock_1.mockUser), { fitnessGoal: "hypertrophy" });
+        const strengthResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: partialWithEffort,
+            user: strengthUser,
+        });
+        const hypertrophyResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: partialWithEffort,
+            user: hypertrophyUser,
+        });
+        // completion=50, consistency=100, effortAdequacy=100, restDiscipline=75
+        // strength:    50×0.15 + 100×0.25 + 100×0.45 + 75×0.15 = 88.75 → 89
+        // hypertrophy: 50×0.20 + 100×0.35 + 100×0.30 + 75×0.15 = 86.25 → 86
+        (0, vitest_1.expect)(strengthResult.score).toBe(89);
+        (0, vitest_1.expect)(hypertrophyResult.score).toBe(86);
+        (0, vitest_1.expect)(strengthResult.score).toBeGreaterThan(hypertrophyResult.score);
+    });
+    // ---------------------------------------------------------------------------
+    // P2-5: estimatedOneRepMax in referenceMax
+    // ---------------------------------------------------------------------------
+    (0, vitest_1.it)("P2-5: user near their 1RM shows higher muscle fatigue than a strong user doing the same weight", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        // Weak user: 1RM=60kg — the session's top set (85kg) exceeds their 1RM,
+        // so referenceMax is low → same absolute volume normalises to a higher score
+        const weakUserResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { estimatedOneRepMax: 60 },
+        });
+        // Strong user: 1RM=200kg — 85kg is only ~43% of max → low relative effort
+        // referenceMax is high → same absolute volume normalises to a lower score
+        const strongUserResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { estimatedOneRepMax: 200 },
+        });
+        (0, vitest_1.expect)(weakUserResult.muscleScores["quadriceps"]).toBeGreaterThan(strongUserResult.muscleScores["quadriceps"]);
+    });
+    // ---------------------------------------------------------------------------
+    // P2-6: previousSessionVolume cross-session progressive overload
+    // ---------------------------------------------------------------------------
+    (0, vitest_1.it)("P2-6: beating previous session volume floors consistency at 75 even with high CV", () => {
+        // Highly inconsistent sets: [100kg×10, 50kg×5, 90kg×8]
+        // volume metric: [1000, 250, 720]
+        // CV ≈ 0.47 → base consistency score = clamp(100 - 0.47×200, 20, 100) = 20
+        const inconsistentRecords = [
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "100", reps: "10" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "5" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "90", reps: "8" },
+        ];
+        const withoutContext = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: inconsistentRecords,
+            user: user_mock_1.mockUser,
+        });
+        // currentSessionVolume = 1970, previousSessionVolume = 1000 → 1970 >= 1000 → progressive
+        const withContext = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: inconsistentRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { previousSessionVolume: 1000 },
+        });
+        (0, vitest_1.expect)(withoutContext.qualityBreakdown.consistency).toBe(20); // CONSISTENCY_MIN_SCORE
+        (0, vitest_1.expect)(withContext.qualityBreakdown.consistency).toBe(75); // PROGRESSIVE_OVERLOAD_FLOOR
+    });
+    (0, vitest_1.it)("P2-6: not beating previous session volume does NOT trigger the floor", () => {
+        const inconsistentRecords = [
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "100", reps: "10" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "50", reps: "5" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "90", reps: "8" },
+        ];
+        // currentSessionVolume = 1970, previousSessionVolume = 3000 → 1970 < 3000 → no floor
+        const result = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: inconsistentRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { previousSessionVolume: 3000 },
+        });
+        (0, vitest_1.expect)(result.qualityBreakdown.consistency).toBe(20); // no floor applied
+    });
+    // ---------------------------------------------------------------------------
+    // P2-10: trainingAgeBracket RIR attenuation + referenceMax scaling
+    // ---------------------------------------------------------------------------
+    (0, vitest_1.it)("P2-10: beginner bracket attenuates near-failure effort → lower muscle fatigue than no bracket", () => {
+        // RIR 0 = near-failure: effortFraction ≈ 1.3 without attenuation
+        // With beginner: effortFraction = 0.6 + (1.3 - 0.6) × 0.5 = 0.95
+        const nearFailureRecords = [
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "80", reps: "5", rir: "0" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "80", reps: "5", rir: "0" },
+            { type: "weight-reps", isDone: true, isStrictMode: false, kg: "80", reps: "5", rir: "0" },
+        ];
+        const noContext = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: nearFailureRecords,
+            user: user_mock_1.mockUser,
+        });
+        const beginnerContext = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: nearFailureRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { trainingAgeBracket: "beginner" },
+        });
+        // Beginner: lower effort (attenuated) + lower referenceMax (0.80 scale)
+        // Net effect: ~9% lower score. Verified: noContext ≈ 20, beginnerContext ≈ 18
+        (0, vitest_1.expect)(beginnerContext.muscleScores["quadriceps"]).toBeLessThan(noContext.muscleScores["quadriceps"]);
+    });
+    (0, vitest_1.it)("P2-10: advanced bracket raises referenceMax → lower fatigue score for same work than intermediate", () => {
+        const template = templateExercises_mock_1.mockTemplateExercisesDictionary.weightRepsStandard;
+        const intermediateResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { trainingAgeBracket: "intermediate" },
+        });
+        const advancedResult = (0, index_1.calculateExerciseScoreV2)({
+            exercise: exercises_mock_1.mockExerciseWeightReps,
+            record: template.initialRecords,
+            user: user_mock_1.mockUser,
+            historicalContext: { trainingAgeBracket: "advanced" },
+        });
+        // advanced: referenceMax × 1.15 → higher denominator → lower normalised fatigue
+        (0, vitest_1.expect)(advancedResult.muscleScores["quadriceps"]).toBeLessThan(intermediateResult.muscleScores["quadriceps"]);
+    });
+});

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

@@ -0,0 +1,104 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Types & Interfaces
+ * ============================================================================
+ *
+ * Central type definitions for the scoring algorithm.
+ * This file defines the output shape and internal types used across all three
+ * scoring pillars (Calories, Muscle Fatigue, Quality).
+ */
+import { TActivityLevel, TFitnessGoal, TGender, TRecord } from "../../types";
+/**
+ * Quality score breakdown — lets the UI show users WHY they got their score.
+ * Each sub-score is 0–100.
+ */
+export interface IQualityBreakdown {
+    /** Did the user complete all sets? */
+    completion: number;
+    /** Were sets consistent in output (or intentionally progressive)? */
+    consistency: number;
+    /** Was effort in the productive RPE/RIR zone? */
+    effortAdequacy: number;
+    /** Were rest periods within the exercise's optimal range? */
+    restDiscipline: number;
+}
+/**
+ * The final result returned by calculateExerciseScore.
+ *
+ * - score:           0–100 overall quality of execution
+ * - muscleScores:    per-muscle fatigue map (keyed by EBodyParts key, value 0–100)
+ * - calorieBurn:     estimated kilocalories burned (gross, including EPOC)
+ * - qualityBreakdown: transparent sub-scores for the UI
+ */
+export interface IScoreResult {
+    score: number;
+    muscleScores: Record<string, number>;
+    calorieBurn: number;
+    qualityBreakdown: IQualityBreakdown;
+}
+export type TTrainingAgeBracket = "beginner" | "intermediate" | "advanced";
+/**
+ * Historical context derived from previous sessions, passed from the app
+ * at save time to provide a cross-session perspective for scoring.
+ */
+export interface IHistoricalContext {
+    /** Best Epley 1RM from previous sessions (weight-reps only) */
+    estimatedOneRepMax?: number;
+    /** Last session total volume for this exercise */
+    previousSessionVolume?: number;
+    /** Account age and workout frequency mapping */
+    trainingAgeBracket?: TTrainingAgeBracket;
+    /** Pre-workout readiness rating (1-5) (P4-2 planned) */
+    readiness?: 1 | 2 | 3 | 4 | 5;
+}
+/**
+ * A cleaned, parsed version of a single TRecord.
+ * All string fields are parsed to numbers, unreliable timings are replaced
+ * with fallbacks, and skipped sets are filtered out before this stage.
+ *
+ * This is the ONLY representation the scoring pillars work with — they never
+ * touch raw TRecord directly.
+ */
+export interface IParsedSet {
+    type: TRecord["type"];
+    /** Active work duration for this set in seconds (estimated or measured) */
+    activeDurationSecs: number;
+    /** Rest duration after this set in seconds (validated or fallback) */
+    restDurationSecs: number | null;
+    /**
+     * Effort fraction: 0.0 (no effort) to 1.0 (max effort).
+     * Derived from RPE, RIR, or fallback (0.6).
+     */
+    effortFraction: number;
+    /** weight-reps: weight in kg */
+    kg?: number;
+    /** weight-reps / reps-only: rep count */
+    reps?: number;
+    /** reps-only / duration: auxiliary weight in kg */
+    auxWeightKg?: number;
+    /** duration: hold time in seconds */
+    durationSecs?: number;
+    /** cardio-machine: speed */
+    speed?: number;
+    /** cardio-machine: incline percentage (Treadmill) */
+    inclinePercentage?: number;
+    /** cardio-machine: resistance level (Elliptical, Cycling) */
+    resistanceLevel?: number;
+    /** cardio-machine / cardio-free: distance (km) */
+    distance?: number;
+    /** cardio-free / cardio-machine: session duration in seconds */
+    cardioDurationSecs?: number;
+}
+/**
+ * Validated user context with guaranteed fallbacks.
+ * No optional fields — everything has a sensible default.
+ */
+export interface IUserContext {
+    weightKg: number;
+    heightCm: number;
+    gender: TGender;
+    age: number;
+    fitnessLevel: TActivityLevel;
+    fitnessGoal: TFitnessGoal;
+    bodyFatPercentage: number;
+}

package/dist/utils/scoringWorkout/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Types & Interfaces
+ * ============================================================================
+ *
+ * Central type definitions for the scoring algorithm.
+ * This file defines the output shape and internal types used across all three
+ * scoring pillars (Calories, Muscle Fatigue, Quality).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dgpholdings/greatoak-shared",
-	"version": "1.2.54",
+	"version": "1.2.55",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -11,7 +11,9 @@
 		"build": "tsc",
 		"pub": "npm run build && npm version patch && npm publish",
 		"format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
-		"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\""
+		"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
+		"test": "vitest run src",
+		"test:watch": "vitest src"
 	},
 	"repository": {
 		"type": "git",
@@ -20,7 +22,8 @@
 	"author": "Siddhartha Chowdhury",
 	"license": "MIT",
 	"devDependencies": {
-		"typescript": "^5.8.2"
+		"typescript": "^5.8.2",
+		"vitest": "^4.1.3"
 	},
 	"dependencies": {
 		"react-native-uuid": "^2.0.3"