@dgpholdings/greatoak-shared 1.2.54 → 1.2.55

package/dist/utils/exerciseRecord/__mocks__/exercises.mock.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockExercisesDictionary = exports.mockExerciseCardioFree = exports.mockExerciseCardioMachine = exports.mockExerciseDuration = exports.mockExerciseRepsOnly = exports.mockExerciseWeightReps = void 0;
+/**
+ * MOCK EXERCISE: Weight-Reps
+ * Simulates a standard compound lift (e.g., Barbell Squat).
+ */
+exports.mockExerciseWeightReps = {
+    exerciseId: "mock-exercise-weight-reps-123",
+    name: "Generic Barbell Squat",
+    bodyPart: ["Legs"],
+    recordType: "weight-reps",
+    primaryMuscles: ["quadriceps"],
+    secondaryMuscles: ["glutes-maximus"],
+    trainingTypes: ["weight"],
+    difficultyLevel: 2,
+    hypertrophyLevel: 4,
+    strengthGainLevel: 4,
+    flexibilityLevel: 1,
+    calorieBurnLevel: 3,
+    stabilityLevel: 2,
+    enduranceLevel: 1,
+    metabolicData: {
+        baseMET: 6.0,
+        metRange: [4.0, 8.0],
+        compoundMultiplier: 1.5,
+        muscleGroupFactor: 2.0,
+        intensityScaling: "exponential",
+        epocFactor: 0.15,
+    },
+    timingGuardrails: {
+        type: "weight-reps",
+        stressRestBonus: 5,
+        fatigueMultiplier: 1.2,
+        setupTypicalSecs: 10,
+        restPeriods: {
+            minimum: 60,
+            typical: 120,
+            maximum: 300,
+            optimalRange: [90, 180],
+        },
+        singleRep: {
+            min: 2.0,
+            max: 5.0,
+            typical: 3.5,
+        },
+    },
+    youtubeVideoUrl: ["https://youtube.com/watch?v=mock1"],
+    modelVideoUrl: "https://example.com/mock-video.mp4",
+    thumbnailUrl: "https://example.com/mock-thumb.png",
+    instructionsHtml: "<ul><li>Mock instruction 1</li></ul>",
+    importantTipsHtml: "<ul><li>Mock tip 1</li></ul>",
+    popularityIndex: 90,
+};
+/**
+ * MOCK EXERCISE: Reps-Only
+ * Simulates a bodyweight movement (e.g., Push-up).
+ */
+exports.mockExerciseRepsOnly = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-reps-only-456", name: "Generic Push-Up", bodyPart: ["Chest", "Core"], recordType: "reps-only", primaryMuscles: ["pectoralis-major"], secondaryMuscles: ["tricep-brachii-lateral", "abs-lower"], trainingTypes: ["body-weight"], timingGuardrails: {
+        type: "reps-only",
+        stressRestBonus: 2,
+        fatigueMultiplier: 1.05,
+        setupTypicalSecs: 5,
+        restPeriods: {
+            minimum: 30,
+            typical: 60,
+            maximum: 180,
+            optimalRange: [45, 90],
+        },
+        singleRep: {
+            min: 1.0,
+            max: 3.0,
+            typical: 1.8,
+        },
+    } });
+/**
+ * MOCK EXERCISE: Duration
+ * Simulates an isometric hold (e.g., Plank).
+ */
+exports.mockExerciseDuration = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-duration-789", name: "Generic Forearm Plank", bodyPart: ["Core"], recordType: "duration", primaryMuscles: ["abs-lower", "abs-upper"], secondaryMuscles: ["lower-back"], trainingTypes: ["body-weight", "isometric"], timingGuardrails: {
+        type: "duration",
+        stressRestBonus: 3,
+        fatigueMultiplier: 1.1,
+        setupTypicalSecs: 5,
+        restPeriods: {
+            minimum: 30,
+            typical: 60,
+            maximum: 120,
+            optimalRange: [45, 60],
+        },
+        setDuration: {
+            min: 15,
+            max: 300,
+            typical: 60,
+        },
+    } });
+/**
+ * MOCK EXERCISE: Cardio-Machine
+ * Simulates a machine cardio session (e.g., Treadmill).
+ */
+exports.mockExerciseCardioMachine = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-machine-101", name: "Generic Treadmill Run", bodyPart: ["Legs"], recordType: "cardio-machine", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
+        type: "cardio-machine",
+        stressRestBonus: 0,
+        fatigueMultiplier: 1.0,
+        setupTypicalSecs: 15,
+        restPeriods: {
+            minimum: 0,
+            typical: 0,
+            maximum: 300,
+            optimalRange: [0, 60],
+        },
+    } });
+/**
+ * MOCK EXERCISE: Cardio-Free
+ * Simulates an outdoor/untracked cardio session (e.g., Outdoor Run).
+ */
+exports.mockExerciseCardioFree = Object.assign(Object.assign({}, exports.mockExerciseWeightReps), { exerciseId: "mock-exercise-cardio-free-202", name: "Generic Outdoor Jog", bodyPart: ["Legs"], recordType: "cardio-free", primaryMuscles: ["quadriceps", "hamstrings", "calves"], secondaryMuscles: ["glutes-maximus"], trainingTypes: ["cardio"], timingGuardrails: {
+        type: "cardio-free",
+        stressRestBonus: 0,
+        fatigueMultiplier: 1.0,
+        setupTypicalSecs: 0,
+        restPeriods: {
+            minimum: 0,
+            typical: 0,
+            maximum: 300,
+            optimalRange: [0, 0],
+        },
+    } });
+/**
+ * Helper dictionary containing all mock exercises mapped by their ID.
+ */
+exports.mockExercisesDictionary = {
+    [exports.mockExerciseWeightReps.exerciseId]: exports.mockExerciseWeightReps,
+    [exports.mockExerciseRepsOnly.exerciseId]: exports.mockExerciseRepsOnly,
+    [exports.mockExerciseDuration.exerciseId]: exports.mockExerciseDuration,
+    [exports.mockExerciseCardioMachine.exerciseId]: exports.mockExerciseCardioMachine,
+    [exports.mockExerciseCardioFree.exerciseId]: exports.mockExerciseCardioFree,
+};

package/dist/utils/exerciseRecord/recordValidator.d.ts

@@ -0,0 +1,12 @@
+import { TRecord, TExerciseConfig, TExercise } from "../../types";
+type TValidationResult = {
+    isValid: boolean;
+    sanitizedRecord: TRecord | null;
+    errors: string[];
+};
+/**
+ * Validates a record against the base exercise type and the plan's specific configuration.
+ * Also performs sanitization by stripping out fields that are disabled in the config.
+ */
+export declare const validateAndSanitizeRecord: (record: TRecord, baseExercise: TExercise, config: TExerciseConfig) => TValidationResult;
+export {};

package/dist/utils/exerciseRecord/recordValidator.integration.test.d.ts

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

package/dist/utils/exerciseRecord/recordValidator.integration.test.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const recordValidator_1 = require("./recordValidator");
+const templateExercises_mock_1 = require("../../__mocks__/templateExercises.mock");
+const exercises_mock_1 = require("../../__mocks__/exercises.mock");
+(0, vitest_1.describe)('recordValidator - Scenario Integration (End-to-End)', () => {
+    (0, vitest_1.it)('Scenario: "Dirty payload" -> strips disabled features (RPE, RIR, setNote)', () => {
+        // The dirty payload mock has a config where everything is disabled, 
+        // but the record payload contains rpe, rir, and setNote.
+        const mockTemplate = templateExercises_mock_1.mockTemplateExercisesDictionary.dirtyPayload;
+        const baseExercise = exercises_mock_1.mockExercisesDictionary[mockTemplate.exerciseId];
+        // We pass the first (and only) record through the gatekeeper
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(mockTemplate.initialRecords[0], baseExercise, mockTemplate.config);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.errors).toHaveLength(0);
+        // Core payload must survive
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('kg', '100');
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('reps', '10');
+        // Disabled properties MUST be stripped
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('rpe');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('rir');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('setNote');
+    });
+    (0, vitest_1.it)('Scenario: "Non-sequential" -> successfully passes validation across a realistic partial array', () => {
+        var _a;
+        const mockTemplate = templateExercises_mock_1.mockTemplateExercisesDictionary.nonSequential;
+        const baseExercise = exercises_mock_1.mockExercisesDictionary[mockTemplate.exerciseId];
+        const results = mockTemplate.initialRecords.map(record => (0, recordValidator_1.validateAndSanitizeRecord)(record, baseExercise, mockTemplate.config));
+        // Set 1 (Done)
+        (0, vitest_1.expect)(results[0].isValid).toBe(true);
+        (0, vitest_1.expect)(results[0].sanitizedRecord).toHaveProperty('reps', '10');
+        // Set 2 (Undone) - Should pass through trivially
+        (0, vitest_1.expect)(results[1].isValid).toBe(true);
+        (0, vitest_1.expect)((_a = results[1].sanitizedRecord) === null || _a === void 0 ? void 0 : _a.isDone).toBe(false);
+        // Set 3 (Done)
+        (0, vitest_1.expect)(results[2].isValid).toBe(true);
+        (0, vitest_1.expect)(results[2].sanitizedRecord).toHaveProperty('reps', '10');
+    });
+    (0, vitest_1.it)('Scenario: cardio-free -> distance NOT stripped even if config.enableDistance is missing/false', () => {
+        const mockTemplate = templateExercises_mock_1.mockTemplateExercisesDictionary.cardioFree;
+        const baseExercise = exercises_mock_1.mockExercisesDictionary[mockTemplate.exerciseId];
+        // Artificially disable enableDistance to prove regression safety
+        const hostileConfig = Object.assign(Object.assign({}, mockTemplate.config), { enableDistance: false });
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(mockTemplate.initialRecords[0], baseExercise, hostileConfig);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        // Distance is structurally required for cardio-free, the config cannot turn it off.
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('distance', '5.0');
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('durationMmSs', '25:30');
+    });
+});

package/dist/utils/exerciseRecord/recordValidator.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndSanitizeRecord = void 0;
+/**
+ * Validates a record against the base exercise type and the plan's specific configuration.
+ * Also performs sanitization by stripping out fields that are disabled in the config.
+ */
+const validateAndSanitizeRecord = (record, baseExercise, config) => {
+    const errors = [];
+    // 1. Completion check
+    if (!record.isDone) {
+        return { isValid: true, sanitizedRecord: record, errors: [] };
+    }
+    // 2. Structural Type Check
+    // The record type MUST match the master recordType of the exercise in the DB.
+    if (record.type !== baseExercise.recordType) {
+        errors.push(`Record type mismatch. Expected "${baseExercise.recordType}", but received "${record.type}".`);
+        return { isValid: false, sanitizedRecord: null, errors };
+    }
+    // 3. Create a clean clone for sanitization
+    const sanitized = Object.assign({}, record);
+    // 4. Config-Driven Sanitization
+    // If a field is disabled in the TExerciseConfig, we remove it from the payload.
+    if (!config.enableRpe) {
+        delete sanitized.rpe;
+    }
+    if (!config.enableSetNote) {
+        delete sanitized.setNote;
+    }
+    if (record.type === "weight-reps" || record.type === "reps-only") {
+        if (!config.enableRir) {
+            delete sanitized.rir;
+        }
+    }
+    if (record.type === "reps-only" ||
+        record.type === "duration" ||
+        record.type === "cardio-free") {
+        if (!config.enableAuxWeight) {
+            // auxWeightKg is required in the TRecord union — zero it out rather than deleting
+            sanitized.auxWeightKg = "";
+        }
+    }
+    if (record.type === "cardio-machine") {
+        if (!config.enableInclinePercentage)
+            delete sanitized.inclinePercentage;
+        if (!config.enableResistanceLevel)
+            delete sanitized.resistanceLevel;
+        if (!config.enableSpeed)
+            delete sanitized.speed;
+        if (!config.enableDistance)
+            delete sanitized.distance;
+    }
+    // 5. Value Integrity Checks
+    if (record.type === "weight-reps") {
+        if (isNaN(parseFloat(record.kg || ""))) {
+            errors.push("Weight (kg) must be a parseable number.");
+        }
+        if (isNaN(parseFloat(record.reps || ""))) {
+            errors.push("Reps must be a parseable number.");
+        }
+    }
+    if (record.type === "reps-only") {
+        if (isNaN(parseFloat(record.reps || ""))) {
+            errors.push("Reps must be a parseable number.");
+        }
+    }
+    if (record.type === "duration" ||
+        record.type === "cardio-free" ||
+        record.type === "cardio-machine") {
+        if (!record.durationMmSs || record.durationMmSs === "00:00") {
+            errors.push("Duration (MM:SS) must be present and non-zero.");
+        }
+    }
+    if (record.type === "cardio-free") {
+        if (isNaN(parseFloat(record.distance || ""))) {
+            errors.push("Distance must be a parseable number.");
+        }
+    }
+    return {
+        isValid: errors.length === 0,
+        sanitizedRecord: errors.length === 0 ? sanitized : null,
+        errors,
+    };
+};
+exports.validateAndSanitizeRecord = validateAndSanitizeRecord;

package/dist/utils/exerciseRecord/recordValidator.test.d.ts

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

package/dist/utils/exerciseRecord/recordValidator.test.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const recordValidator_1 = require("./recordValidator");
+(0, vitest_1.describe)('recordValidator - Gatekeeper', () => {
+    const mockBaseExercise = {
+        exerciseId: 'test-id',
+        recordType: 'weight-reps',
+    };
+    const mockConfigAllEnabled = {
+        enableRpe: true,
+        enableRir: true,
+        enableSetNote: true,
+        enableAuxWeight: true,
+        enableDistance: true,
+        enableInclinePercentage: true,
+        enableResistanceLevel: true,
+        enableSpeed: true,
+    };
+    const mockConfigAllDisabled = {};
+    (0, vitest_1.it)('passes through undone records without validation errors', () => {
+        const record = { type: 'weight-reps', isDone: false, isStrictMode: false, kg: 'invalid', reps: 'invalid' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.errors).toHaveLength(0);
+    });
+    (0, vitest_1.it)('rejects records with a mismatched type and asserts sanitizedRecord is null', () => {
+        const record = { type: 'duration', isDone: true, isStrictMode: false, durationMmSs: '05:00', auxWeightKg: '0' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors[0]).toContain('Record type mismatch');
+    });
+    (0, vitest_1.it)('strips disabled fields for weight-reps', () => {
+        const record = {
+            type: 'weight-reps',
+            isDone: true,
+            isStrictMode: false,
+            kg: '100',
+            reps: '10',
+            rpe: '8',
+            rir: '2',
+            setNote: 'Felt heavy',
+        };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllDisabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        // Values should be stripped
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('rpe');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('rir');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('setNote');
+        // Core values must remain
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('kg', '100');
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('reps', '10');
+    });
+    (0, vitest_1.it)('retains fields when enabled in config', () => {
+        const record = {
+            type: 'weight-reps',
+            isDone: true,
+            isStrictMode: false,
+            kg: '100',
+            reps: '10',
+            rpe: '8',
+            rir: '2',
+            setNote: 'Felt heavy',
+        };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('rpe', '8');
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('rir', '2');
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('setNote', 'Felt heavy');
+    });
+    (0, vitest_1.it)('validates numeric integrity of weight-reps and collects multiple errors', () => {
+        const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: 'invalid', reps: 'invalid' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors).toHaveLength(2);
+        (0, vitest_1.expect)(result.errors[0]).toContain('Weight (kg) must be a parseable number');
+        (0, vitest_1.expect)(result.errors[1]).toContain('Reps must be a parseable number');
+    });
+    (0, vitest_1.it)('treats 0 as a valid number for weight-reps (Failed Set scenario)', () => {
+        const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '0' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, mockBaseExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('reps', '0');
+    });
+    (0, vitest_1.it)('validates numeric integrity of reps-only and collects error', () => {
+        const baseRepExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'reps-only' });
+        const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: 'abc', auxWeightKg: '20' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseRepExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors).toHaveLength(1);
+        (0, vitest_1.expect)(result.errors[0]).toContain('Reps must be a parseable number');
+    });
+    (0, vitest_1.it)('zeroes out required auxWeightKg instead of deleting it on reps-only when disabled', () => {
+        const baseRepExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'reps-only' });
+        const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: '10', auxWeightKg: '20' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseRepExercise, mockConfigAllDisabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        // auxWeightKg should be present but empty, to satisfy union requirements
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('auxWeightKg', '');
+    });
+    (0, vitest_1.it)('validates duration type successfully (Happy Path)', () => {
+        const baseDurationExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'duration' });
+        const record = { type: 'duration', isDone: true, isStrictMode: false, durationMmSs: '05:00', auxWeightKg: '0' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseDurationExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('durationMmSs', '05:00');
+    });
+    (0, vitest_1.it)('rejects cardio-machine records with zero duration', () => {
+        const baseMachineExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'cardio-machine' });
+        const record = { type: 'cardio-machine', isDone: true, isStrictMode: false, durationMmSs: '00:00' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseMachineExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors[0]).toContain('Duration (MM:SS) must be present and non-zero');
+    });
+    (0, vitest_1.it)('strips optional fields from cardio-machine when disabled', () => {
+        const baseMachineExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'cardio-machine' });
+        const record = {
+            type: 'cardio-machine',
+            isDone: true,
+            isStrictMode: false,
+            durationMmSs: '15:00',
+            distance: '5',
+            speed: '12',
+            inclinePercentage: '2',
+            resistanceLevel: '5'
+        };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseMachineExercise, mockConfigAllDisabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        // Fields should be stripped
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('distance');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('speed');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('inclinePercentage');
+        (0, vitest_1.expect)(result.sanitizedRecord).not.toHaveProperty('resistanceLevel');
+        // Core duration must remain
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('durationMmSs', '15:00');
+    });
+    (0, vitest_1.it)('validates duration format for cardio-free', () => {
+        const baseCardioExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'cardio-free' });
+        // Missing durationMmSs
+        const record = { type: 'cardio-free', isDone: true, isStrictMode: false, distance: '5', durationMmSs: '00:00' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseCardioExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors[0]).toContain('Duration (MM:SS) must be present and non-zero');
+    });
+    (0, vitest_1.it)('validates distance format for cardio-free', () => {
+        const baseCardioExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'cardio-free' });
+        const record = { type: 'cardio-free', isDone: true, isStrictMode: false, distance: 'invalid', durationMmSs: '15:00' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseCardioExercise, mockConfigAllEnabled);
+        (0, vitest_1.expect)(result.isValid).toBe(false);
+        (0, vitest_1.expect)(result.sanitizedRecord).toBeNull();
+        (0, vitest_1.expect)(result.errors[0]).toContain('Distance must be a parseable number');
+    });
+    (0, vitest_1.it)('retains required distance on cardio-free even if enableDistance is false (Regression)', () => {
+        const baseCardioExercise = Object.assign(Object.assign({}, mockBaseExercise), { recordType: 'cardio-free' });
+        const record = { type: 'cardio-free', isDone: true, isStrictMode: false, distance: '5', durationMmSs: '15:00' };
+        const result = (0, recordValidator_1.validateAndSanitizeRecord)(record, baseCardioExercise, mockConfigAllDisabled);
+        (0, vitest_1.expect)(result.isValid).toBe(true);
+        (0, vitest_1.expect)(result.sanitizedRecord).toHaveProperty('distance', '5'); // Must NOT be stripped
+    });
+});

package/dist/utils/exerciseRecord/workoutMath.d.ts

@@ -0,0 +1,28 @@
+import { TRecord, TTimingGuardrails } from "../../types";
+/**
+ * Parses a time string (MM:SS or HH:MM:SS) into total seconds.
+ */
+export declare const parseMmSsToSecs: (mmss?: string) => number;
+/**
+ * Estimates the "Time Under Tension" for a set using Claude's "Derive, Don't Measure" strategy.
+ * For cardio/duration, it uses the explicit input.
+ * For reps-based exercises, it uses timingGuardrails.
+ */
+export declare const estimateWorkDuration: (record: TRecord, guardrails?: TTimingGuardrails) => number;
+/**
+ * Determines the rest period duration.
+ * Prioritizes actual recorded rest if available, otherwise falls back to typical rest periods.
+ */
+export declare const estimateRestDuration: (record: TRecord, guardrails?: TTimingGuardrails) => number;
+/**
+ * Calculates total exercise duration.
+ * Formula: Sum(Work) + Sum(Rest) - Rest[LastSet]
+ */
+export declare const calculateTotalExerciseDuration: (records: TRecord[], guardrails?: TTimingGuardrails) => number;
+/**
+ * Calculates volume for a single set.
+ * CRITICAL: This math assumes the weight is stored in KILOGRAMS.
+ * If the weight string looks like LBS (e.g. > 200kg on a lateral raise),
+ * it is a sign of a conversion error in the frontend.
+ */
+export declare const calculateSetVolume: (record: TRecord) => number;

package/dist/utils/exerciseRecord/workoutMath.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateSetVolume = exports.calculateTotalExerciseDuration = exports.estimateRestDuration = exports.estimateWorkDuration = exports.parseMmSsToSecs = void 0;
+/**
+ * Parses a time string (MM:SS or HH:MM:SS) into total seconds.
+ */
+const parseMmSsToSecs = (mmss) => {
+    if (!mmss)
+        return 0;
+    const parts = mmss.split(':');
+    if (parts.length === 2) {
+        return (parseInt(parts[0], 10) || 0) * 60 + (parseInt(parts[1], 10) || 0);
+    }
+    if (parts.length === 3) {
+        return ((parseInt(parts[0], 10) || 0) * 3600 +
+            (parseInt(parts[1], 10) || 0) * 60 +
+            (parseInt(parts[2], 10) || 0));
+    }
+    return 0;
+};
+exports.parseMmSsToSecs = parseMmSsToSecs;
+/**
+ * Estimates the "Time Under Tension" for a set using Claude's "Derive, Don't Measure" strategy.
+ * For cardio/duration, it uses the explicit input.
+ * For reps-based exercises, it uses timingGuardrails.
+ */
+const estimateWorkDuration = (record, guardrails) => {
+    var _a;
+    if (!record.isDone)
+        return 0;
+    if (record.type === "duration" ||
+        record.type === "cardio-machine" ||
+        record.type === "cardio-free") {
+        return (0, exports.parseMmSsToSecs)(record.durationMmSs);
+    }
+    if (record.type === "weight-reps" || record.type === "reps-only") {
+        const reps = parseFloat(record.reps || "0");
+        const parsedReps = Math.max(0, isNaN(reps) ? 0 : reps);
+        // Use guardrails if they match the type
+        if (guardrails &&
+            (guardrails.type === "weight-reps" || guardrails.type === "reps-only")) {
+            const singleRep = ((_a = guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) || 2.5;
+            const setup = guardrails.setupTypicalSecs || 3;
+            return Math.round(parsedReps * singleRep + setup);
+        }
+        // Fallback defaults
+        return Math.round(parsedReps * 2.5 + 3);
+    }
+    return 0;
+};
+exports.estimateWorkDuration = estimateWorkDuration;
+/**
+ * Determines the rest period duration.
+ * Prioritizes actual recorded rest if available, otherwise falls back to typical rest periods.
+ */
+const estimateRestDuration = (record, guardrails) => {
+    var _a, _b;
+    if (!record.isDone)
+        return 0;
+    const typicalRest = ((_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _a === void 0 ? void 0 : _a.typical) || 60;
+    const maxRest = ((_b = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _b === void 0 ? void 0 : _b.maximum) || 300;
+    if (record.restDurationSecs !== undefined && !isNaN(record.restDurationSecs) && record.restDurationSecs > 0) {
+        // We clamp the rest duration to avoid "Distracted Logger" outliers (e.g. 20 min rest)
+        return Math.min(record.restDurationSecs, maxRest);
+    }
+    return typicalRest;
+};
+exports.estimateRestDuration = estimateRestDuration;
+/**
+ * Calculates total exercise duration.
+ * Formula: Sum(Work) + Sum(Rest) - Rest[LastSet]
+ */
+const calculateTotalExerciseDuration = (records, guardrails) => {
+    const doneRecords = records.filter((r) => r.isDone);
+    if (doneRecords.length === 0)
+        return 0;
+    let totalSecs = 0;
+    for (let i = 0; i < doneRecords.length; i++) {
+        totalSecs += (0, exports.estimateWorkDuration)(doneRecords[i], guardrails);
+        // Only add rest if it's not the final completed set
+        if (i < doneRecords.length - 1) {
+            totalSecs += (0, exports.estimateRestDuration)(doneRecords[i], guardrails);
+        }
+    }
+    return totalSecs;
+};
+exports.calculateTotalExerciseDuration = calculateTotalExerciseDuration;
+/**
+ * Calculates volume for a single set.
+ * CRITICAL: This math assumes the weight is stored in KILOGRAMS.
+ * If the weight string looks like LBS (e.g. > 200kg on a lateral raise),
+ * it is a sign of a conversion error in the frontend.
+ */
+const calculateSetVolume = (record) => {
+    if (!record.isDone)
+        return 0;
+    if (record.type === "weight-reps") {
+        const kg = parseFloat(record.kg || "0");
+        const reps = parseFloat(record.reps || "0");
+        if (isNaN(kg) || isNaN(reps))
+            return 0;
+        return kg * reps;
+    }
+    if (record.type === "reps-only") {
+        const aux = parseFloat(record.auxWeightKg || "0");
+        const reps = parseFloat(record.reps || "0");
+        if (isNaN(reps))
+            return 0;
+        // Bodyweight volume = reps (1 unit per rep). Aux weight adds on top.
+        // Callers needing absolute volume (e.g. calorie burn) must inject user bodyweight externally.
+        const effectiveWeight = isNaN(aux) || aux <= 0 ? 1 : 1 + aux;
+        return effectiveWeight * reps;
+    }
+    return 0;
+};
+exports.calculateSetVolume = calculateSetVolume;

package/dist/utils/exerciseRecord/workoutMath.test.d.ts

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