@aneuhold/core-ts-db-lib 4.0.3 → 4.1.0

package/lib/services/workout/Microcycle/WorkoutMicrocycleService.ts

@@ -0,0 +1,236 @@
+import { DateService } from '@aneuhold/core-ts-lib';
+import type { UUID } from 'crypto';
+import {
+  ExerciseRepRange,
+  type WorkoutExercise
+} from '../../../documents/workout/WorkoutExercise.js';
+import type {
+  CalibrationExercisePair,
+  WorkoutExerciseCalibration
+} from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import WorkoutExerciseService from '../Exercise/WorkoutExerciseService.js';
+import type WorkoutMesocyclePlanContext from '../Mesocycle/WorkoutMesocyclePlanContext.js';
+import WorkoutSessionService from '../Session/WorkoutSessionService.js';
+import WorkoutVolumePlanningService from '../util/VolumePlanning/WorkoutVolumePlanningService.js';
+
+/**
+ * A service for handling operations related to {@link WorkoutMicrocycle}s.
+ */
+export default class WorkoutMicrocycleService {
+  /**
+   * Generates sessions for a specific microcycle.
+   */
+  static generateSessionsForMicrocycle({
+    context,
+    microcycleIndex,
+    targetRir,
+    isDeloadMicrocycle
+  }: {
+    context: WorkoutMesocyclePlanContext;
+    microcycleIndex: number;
+    targetRir: number;
+    isDeloadMicrocycle: boolean;
+  }): void {
+    const mesocycle = context.mesocycle;
+    const microcycle = context.microcyclesInOrder[microcycleIndex];
+
+    if (!context.plannedSessionExercisePairs) {
+      throw new Error(
+        'WorkoutMesocyclePlanContext.plannedSessionExercisePairs is not initialized. This should be set during mesocycle planning.'
+      );
+    }
+    if (!context.muscleGroupToExercisePairsMap) {
+      throw new Error(
+        'WorkoutMesocyclePlanContext.muscleGroupToExercisePairsMap is not initialized. This should be derived when the planned session exercise pairs are set.'
+      );
+    }
+
+    const sessionsToExerciseSessionsArray = context.plannedSessionExercisePairs;
+
+    const setPlan = WorkoutVolumePlanningService.calculateSetPlanForMicrocycle(
+      context,
+      microcycleIndex,
+      isDeloadMicrocycle
+    );
+
+    let currentSessionDate = new Date(microcycle.startDate);
+    let sessionIndex = 0;
+
+    for (let day = 0; day < mesocycle.plannedMicrocycleLengthInDays; day++) {
+      // Skip rest days
+      if (mesocycle.plannedMicrocycleRestDays.includes(day)) {
+        currentSessionDate = DateService.addDays(currentSessionDate, 1);
+        continue;
+      }
+
+      // Stop if we've created all planned sessions
+      if (sessionIndex >= mesocycle.plannedSessionCountPerMicrocycle) {
+        break;
+      }
+
+      const sessionExerciseList = sessionsToExerciseSessionsArray[sessionIndex] || [];
+
+      WorkoutSessionService.generateSession({
+        context,
+        microcycleIndex,
+        sessionIndex,
+        sessionStartDate: currentSessionDate,
+        sessionExerciseList,
+        targetRir,
+        isDeloadMicrocycle,
+        setPlan
+      });
+
+      sessionIndex++;
+      currentSessionDate = DateService.addDays(currentSessionDate, 1);
+    }
+  }
+
+  /**
+   * Distributes exercises across sessions within a microcycle, by putting them into a consecutive
+   * array of arrays structure. The embedded array is the list of exercises for that session.
+   *
+   * @param sessionCount The number of sessions to distribute exercises across.
+   * @param calibrationMap The map of calibration documents.
+   * @param exerciseMap The map of exercise documents.
+   */
+  static distributeExercisesAcrossSessions(
+    sessionCount: number,
+    calibrationMap: Map<UUID, WorkoutExerciseCalibration>,
+    exerciseMap: Map<UUID, WorkoutExercise>
+  ): CalibrationExercisePair[][] {
+    // Build calibration-exercise pairs from the provided maps
+    const validExercises: CalibrationExercisePair[] = [];
+    for (const calibration of calibrationMap.values()) {
+      const exercise = exerciseMap.get(calibration.workoutExerciseId);
+      if (!exercise) {
+        throw new Error(
+          `Exercise ${calibration.workoutExerciseId} not found for calibration ${calibration._id}`
+        );
+      }
+      validExercises.push({ calibration, exercise });
+    }
+
+    // Group exercises by their primary muscle group (use first one as main identifier, this might
+    // need to be revisited later for multi-group exercises)
+    const muscleGroupsMap = new Map<UUID, CalibrationExercisePair[]>();
+    for (const exercisePair of validExercises) {
+      const muscleGroupId = exercisePair.exercise.primaryMuscleGroups[0];
+      const existingGroup = muscleGroupsMap.get(muscleGroupId);
+      if (existingGroup) {
+        existingGroup.push(exercisePair);
+      } else {
+        muscleGroupsMap.set(muscleGroupId, [exercisePair]);
+      }
+    }
+
+    // 1. Calculate max fatigue for each muscle group to sort them initially
+    const muscleGroupFatigueScores = new Map<UUID, number>();
+    for (const [muscleGroupId, muscleGroupExercises] of muscleGroupsMap.entries()) {
+      const fatigueScores = muscleGroupExercises.map((pair) =>
+        WorkoutExerciseService.getFatigueScore(pair.exercise)
+      );
+      const maxFatigue = Math.max(...fatigueScores);
+      muscleGroupFatigueScores.set(muscleGroupId, maxFatigue);
+    }
+
+    // 2. Sort muscle groups by their max fatigue (Desc) so hardest exercises for a group get assigned first
+    const sortedMuscleGroupIds = [...muscleGroupsMap.keys()].sort((a, b) => {
+      const fatigueA = muscleGroupFatigueScores.get(a) || 0;
+      const fatigueB = muscleGroupFatigueScores.get(b) || 0;
+      return fatigueB - fatigueA;
+    });
+
+    // Prepare sessions array (so we can push exercises into each empty array)
+    const sessions: CalibrationExercisePair[][] = Array.from({ length: sessionCount }, () => []);
+    const usedStarterGroups = new Set<UUID>();
+
+    // 3. Assign Headliners (Priority 1 & 2)
+    // Iterate sessions and pick a starter exercise
+    for (let sessionIndex = 0; sessionIndex < sessionCount; sessionIndex++) {
+      let candidateMuscleGroupId: UUID | undefined;
+
+      // Try to find a group that hasn't started a session yet (Priority 1)
+      for (const groupId of sortedMuscleGroupIds) {
+        if (!usedStarterGroups.has(groupId)) {
+          candidateMuscleGroupId = groupId;
+          break;
+        }
+      }
+
+      // If no unused group available/has exercises, pick any group with highest fatigue available (Priority 2 fallback)
+      if (!candidateMuscleGroupId) {
+        let maxFatigue = -1;
+        for (const groupId of sortedMuscleGroupIds) {
+          const exercisePairs = muscleGroupsMap.get(groupId);
+          if (exercisePairs && exercisePairs.length > 0) {
+            const fatigueScoresAmongExercises = exercisePairs.map((pair) =>
+              WorkoutExerciseService.getFatigueScore(pair.exercise)
+            );
+            const groupMax = Math.max(...fatigueScoresAmongExercises);
+            if (groupMax > maxFatigue) {
+              maxFatigue = groupMax;
+              candidateMuscleGroupId = groupId;
+            }
+          }
+        }
+      }
+
+      if (candidateMuscleGroupId) {
+        const group = muscleGroupsMap.get(candidateMuscleGroupId);
+        if (group && group.length > 0) {
+          // Pick highest fatigue exercise in this group to be the headliner
+          group.sort(
+            (a, b) =>
+              WorkoutExerciseService.getFatigueScore(b.exercise) -
+              WorkoutExerciseService.getFatigueScore(a.exercise)
+          );
+          const headliner = group.shift();
+          if (headliner) {
+            sessions[sessionIndex].push(headliner);
+            usedStarterGroups.add(candidateMuscleGroupId);
+          }
+        }
+      }
+    }
+
+    // 4. Distribute Remainder (Priority 2 continued)
+    const remainingExercises: CalibrationExercisePair[] = [];
+    for (const group of muscleGroupsMap.values()) {
+      remainingExercises.push(...group);
+    }
+
+    // Sort remaining by fatigue (High -> Low)
+    remainingExercises.sort(
+      (a, b) =>
+        WorkoutExerciseService.getFatigueScore(b.exercise) -
+        WorkoutExerciseService.getFatigueScore(a.exercise)
+    );
+
+    // Distribute round-robin
+    let currentSessionIndex = 0;
+    for (const pair of remainingExercises) {
+      sessions[currentSessionIndex].push(pair);
+      currentSessionIndex = (currentSessionIndex + 1) % sessionCount;
+    }
+
+    // 5. Sort within session (Priority 3)
+    // Headliner stays first (Index 0). Rest sorted by Rep Range (Heavy -> Med -> Light)
+    for (const session of sessions) {
+      if (session.length <= 1) continue;
+      const [headliner, ...rest] = session;
+      rest.sort((a, b) => {
+        const order = {
+          [ExerciseRepRange.Heavy]: 0,
+          [ExerciseRepRange.Medium]: 1,
+          [ExerciseRepRange.Light]: 2
+        };
+        return order[a.exercise.repRange] - order[b.exercise.repRange];
+      });
+      session.length = 0;
+      session.push(headliner, ...rest);
+    }
+
+    return sessions;
+  }
+}

package/lib/services/workout/Session/WorkoutSessionService.d.ts

@@ -0,0 +1,49 @@
+import type { UUID } from 'crypto';
+import type { CalibrationExercisePair } from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
+import type WorkoutMesocyclePlanContext from '../Mesocycle/WorkoutMesocyclePlanContext.js';
+/**
+ * A service for handling operations related to {@link WorkoutSession}s.
+ *
+ * SCOPE: Session-level operations (calculating totals, managing session generation)
+ *
+ * RESPONSIBILITIES:
+ * - Calculate session-level RSM/Fatigue totals
+ * - Generate workout sessions with exercises and sets
+ *
+ * RELATED SERVICES:
+ * - {@link WorkoutVolumePlanningService} - Provides set count plans for session generation
+ * - {@link WorkoutSetService} - Generates individual sets within sessions
+ * - {@link WorkoutSFRService} - Underlying calculations for RSM/Fatigue
+ */
+export default class WorkoutSessionService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude for a session.
+     */
+    static getRsmTotal(session: WorkoutSession): number | null;
+    /**
+     * Calculates the total fatigue score for a session.
+     */
+    static getFatigueTotal(session: WorkoutSession): number | null;
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR) for a session.
+     */
+    static getSFR(session: WorkoutSession): number | null;
+    /**
+     * Generates a session and its associated exercises and sets.
+     */
+    static generateSession({ context, microcycleIndex, sessionIndex, sessionStartDate, sessionExerciseList, targetRir, isDeloadMicrocycle, setPlan }: {
+        context: WorkoutMesocyclePlanContext;
+        microcycleIndex: number;
+        sessionIndex: number;
+        sessionStartDate: Date;
+        sessionExerciseList: CalibrationExercisePair[];
+        targetRir: number;
+        isDeloadMicrocycle: boolean;
+        setPlan: {
+            exerciseIdToSetCount: Map<UUID, number>;
+            recoveryExerciseIds: Set<UUID>;
+        };
+    }): void;
+}
+//# sourceMappingURL=WorkoutSessionService.d.ts.map

package/lib/services/workout/Session/WorkoutSessionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSessionService.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/Session/WorkoutSessionService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AACxG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AAGnF,OAAO,KAAK,2BAA2B,MAAM,6CAA6C,CAAC;AAI3F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,qBAAqB;IACxC;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAI1D;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAI9D;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAIrD;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,EACrB,OAAO,EACP,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,OAAO,EACR,EAAE;QACD,OAAO,EAAE,2BAA2B,CAAC;QACrC,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,IAAI,CAAC;QACvB,mBAAmB,EAAE,uBAAuB,EAAE,CAAC;QAC/C,SAAS,EAAE,MAAM,CAAC;QAClB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,OAAO,EAAE;YAAE,oBAAoB,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAAC,mBAAmB,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;KACtF,GAAG,IAAI;CAqET"}

package/lib/services/workout/Session/WorkoutSessionService.js

@@ -0,0 +1,95 @@
+import { WorkoutSessionSchema } from '../../../documents/workout/WorkoutSession.js';
+import { WorkoutSessionExerciseSchema } from '../../../documents/workout/WorkoutSessionExercise.js';
+import WorkoutSetService from '../Set/WorkoutSetService.js';
+import WorkoutSFRService from '../util/SFR/WorkoutSFRService.js';
+/**
+ * A service for handling operations related to {@link WorkoutSession}s.
+ *
+ * SCOPE: Session-level operations (calculating totals, managing session generation)
+ *
+ * RESPONSIBILITIES:
+ * - Calculate session-level RSM/Fatigue totals
+ * - Generate workout sessions with exercises and sets
+ *
+ * RELATED SERVICES:
+ * - {@link WorkoutVolumePlanningService} - Provides set count plans for session generation
+ * - {@link WorkoutSetService} - Generates individual sets within sessions
+ * - {@link WorkoutSFRService} - Underlying calculations for RSM/Fatigue
+ */
+export default class WorkoutSessionService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude for a session.
+     */
+    static getRsmTotal(session) {
+        return WorkoutSFRService.getRsmTotal(session.rsm);
+    }
+    /**
+     * Calculates the total fatigue score for a session.
+     */
+    static getFatigueTotal(session) {
+        return WorkoutSFRService.getFatigueTotal(session.fatigue);
+    }
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR) for a session.
+     */
+    static getSFR(session) {
+        return WorkoutSFRService.getSFR(session.rsm, session.fatigue);
+    }
+    /**
+     * Generates a session and its associated exercises and sets.
+     */
+    static generateSession({ context, microcycleIndex, sessionIndex, sessionStartDate, sessionExerciseList, targetRir, isDeloadMicrocycle, setPlan }) {
+        const mesocycle = context.mesocycle;
+        const microcycle = context.microcyclesInOrder[microcycleIndex];
+        const resolvedSetPlan = setPlan;
+        // Create session
+        const session = WorkoutSessionSchema.parse({
+            userId: mesocycle.userId,
+            workoutMicrocycleId: microcycle._id,
+            title: `Microcycle ${microcycleIndex + 1} - Session ${sessionIndex + 1}`,
+            startTime: sessionStartDate
+        });
+        // Create session exercise groupings and associated sets
+        for (let exerciseIndex = 0; exerciseIndex < sessionExerciseList.length; exerciseIndex++) {
+            const { calibration, exercise } = sessionExerciseList[exerciseIndex];
+            const setCountFromPlan = resolvedSetPlan.exerciseIdToSetCount.get(exercise._id);
+            if (setCountFromPlan == null) {
+                throw new Error(`No set plan found for exercise ${exercise._id}, ${exercise.exerciseName} in microcycle ${microcycleIndex}`);
+            }
+            // Get equipment for weight calculations
+            const equipment = context.equipmentMap.get(exercise.workoutEquipmentTypeId);
+            if (!equipment) {
+                throw new Error(`Equipment type not found for exercise ${exercise._id}, ${exercise.exerciseName}`);
+            }
+            if (!equipment.weightOptions || equipment.weightOptions.length === 0) {
+                throw new Error(`No weight options defined for equipment type ${equipment._id}, ${equipment.title}`);
+            }
+            const sessionExercise = WorkoutSessionExerciseSchema.parse({
+                userId: mesocycle.userId,
+                workoutSessionId: session._id,
+                workoutExerciseId: exercise._id,
+                isRecoveryExercise: resolvedSetPlan.recoveryExerciseIds.has(exercise._id)
+            });
+            WorkoutSetService.generateSetsForSessionExercise({
+                context,
+                exercise,
+                calibration,
+                session,
+                sessionExercise,
+                microcycleIndex,
+                sessionIndex,
+                setCount: setCountFromPlan,
+                targetRir,
+                isDeloadMicrocycle
+            });
+            const setsForThisExercise = context.setsToCreate.slice(-setCountFromPlan);
+            sessionExercise.setOrder.push(...setsForThisExercise.map((s) => s._id));
+            session.sessionExerciseOrder.push(sessionExercise._id);
+            context.addSessionExercise(sessionExercise);
+        }
+        // Add session to microcycle's session order and context
+        microcycle.sessionOrder.push(session._id);
+        context.addSession(session);
+    }
+}
+//# sourceMappingURL=WorkoutSessionService.js.map

package/lib/services/workout/Session/WorkoutSessionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSessionService.js","sourceRoot":"","sources":["../../../../src/services/workout/Session/WorkoutSessionService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAAE,4BAA4B,EAAE,MAAM,sDAAsD,CAAC;AAEpG,OAAO,iBAAiB,MAAM,6BAA6B,CAAC;AAC5D,OAAO,iBAAiB,MAAM,kCAAkC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,qBAAqB;IACxC;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,iBAAiB,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,OAAuB;QAC5C,OAAO,iBAAiB,CAAC,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,OAAuB;QACnC,OAAO,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,EACrB,OAAO,EACP,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,OAAO,EAUR;QACC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;QAE/D,MAAM,eAAe,GAAG,OAAO,CAAC;QAEhC,iBAAiB;QACjB,MAAM,OAAO,GAAG,oBAAoB,CAAC,KAAK,CAAC;YACzC,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,mBAAmB,EAAE,UAAU,CAAC,GAAG;YACnC,KAAK,EAAE,cAAc,eAAe,GAAG,CAAC,cAAc,YAAY,GAAG,CAAC,EAAE;YACxE,SAAS,EAAE,gBAAgB;SAC5B,CAAC,CAAC;QAEH,wDAAwD;QACxD,KAAK,IAAI,aAAa,GAAG,CAAC,EAAE,aAAa,GAAG,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,CAAC;YACxF,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAAC,aAAa,CAAC,CAAC;YAErE,MAAM,gBAAgB,GAAG,eAAe,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAChF,IAAI,gBAAgB,IAAI,IAAI,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,YAAY,kBAAkB,eAAe,EAAE,CAC5G,CAAC;YACJ,CAAC;YAED,wCAAwC;YACxC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;YAC5E,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,yCAAyC,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,YAAY,EAAE,CAClF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,aAAa,IAAI,SAAS,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrE,MAAM,IAAI,KAAK,CACb,gDAAgD,SAAS,CAAC,GAAG,KAAK,SAAS,CAAC,KAAK,EAAE,CACpF,CAAC;YACJ,CAAC;YAED,MAAM,eAAe,GAAG,4BAA4B,CAAC,KAAK,CAAC;gBACzD,MAAM,EAAE,SAAS,CAAC,MAAM;gBACxB,gBAAgB,EAAE,OAAO,CAAC,GAAG;gBAC7B,iBAAiB,EAAE,QAAQ,CAAC,GAAG;gBAC/B,kBAAkB,EAAE,eAAe,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;aAC1E,CAAC,CAAC;YAEH,iBAAiB,CAAC,8BAA8B,CAAC;gBAC/C,OAAO;gBACP,QAAQ;gBACR,WAAW;gBACX,OAAO;gBACP,eAAe;gBACf,eAAe;gBACf,YAAY;gBACZ,QAAQ,EAAE,gBAAgB;gBAC1B,SAAS;gBACT,kBAAkB;aACnB,CAAC,CAAC;YAEH,MAAM,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,gBAAgB,CAAC,CAAC;YAE1E,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxE,OAAO,CAAC,oBAAoB,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YACvD,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;QAC9C,CAAC;QAED,wDAAwD;QACxD,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/lib/services/workout/Session/WorkoutSessionService.ts

@@ -0,0 +1,136 @@
+import type { UUID } from 'crypto';
+import type { CalibrationExercisePair } from '../../../documents/workout/WorkoutExerciseCalibration.js';
+import type { WorkoutSession } from '../../../documents/workout/WorkoutSession.js';
+import { WorkoutSessionSchema } from '../../../documents/workout/WorkoutSession.js';
+import { WorkoutSessionExerciseSchema } from '../../../documents/workout/WorkoutSessionExercise.js';
+import type WorkoutMesocyclePlanContext from '../Mesocycle/WorkoutMesocyclePlanContext.js';
+import WorkoutSetService from '../Set/WorkoutSetService.js';
+import WorkoutSFRService from '../util/SFR/WorkoutSFRService.js';
+
+/**
+ * A service for handling operations related to {@link WorkoutSession}s.
+ *
+ * SCOPE: Session-level operations (calculating totals, managing session generation)
+ *
+ * RESPONSIBILITIES:
+ * - Calculate session-level RSM/Fatigue totals
+ * - Generate workout sessions with exercises and sets
+ *
+ * RELATED SERVICES:
+ * - {@link WorkoutVolumePlanningService} - Provides set count plans for session generation
+ * - {@link WorkoutSetService} - Generates individual sets within sessions
+ * - {@link WorkoutSFRService} - Underlying calculations for RSM/Fatigue
+ */
+export default class WorkoutSessionService {
+  /**
+   * Calculates the total Raw Stimulus Magnitude for a session.
+   */
+  static getRsmTotal(session: WorkoutSession): number | null {
+    return WorkoutSFRService.getRsmTotal(session.rsm);
+  }
+
+  /**
+   * Calculates the total fatigue score for a session.
+   */
+  static getFatigueTotal(session: WorkoutSession): number | null {
+    return WorkoutSFRService.getFatigueTotal(session.fatigue);
+  }
+
+  /**
+   * Calculates the Stimulus to Fatigue Ratio (SFR) for a session.
+   */
+  static getSFR(session: WorkoutSession): number | null {
+    return WorkoutSFRService.getSFR(session.rsm, session.fatigue);
+  }
+
+  /**
+   * Generates a session and its associated exercises and sets.
+   */
+  static generateSession({
+    context,
+    microcycleIndex,
+    sessionIndex,
+    sessionStartDate,
+    sessionExerciseList,
+    targetRir,
+    isDeloadMicrocycle,
+    setPlan
+  }: {
+    context: WorkoutMesocyclePlanContext;
+    microcycleIndex: number;
+    sessionIndex: number;
+    sessionStartDate: Date;
+    sessionExerciseList: CalibrationExercisePair[];
+    targetRir: number;
+    isDeloadMicrocycle: boolean;
+    setPlan: { exerciseIdToSetCount: Map<UUID, number>; recoveryExerciseIds: Set<UUID> };
+  }): void {
+    const mesocycle = context.mesocycle;
+    const microcycle = context.microcyclesInOrder[microcycleIndex];
+
+    const resolvedSetPlan = setPlan;
+
+    // Create session
+    const session = WorkoutSessionSchema.parse({
+      userId: mesocycle.userId,
+      workoutMicrocycleId: microcycle._id,
+      title: `Microcycle ${microcycleIndex + 1} - Session ${sessionIndex + 1}`,
+      startTime: sessionStartDate
+    });
+
+    // Create session exercise groupings and associated sets
+    for (let exerciseIndex = 0; exerciseIndex < sessionExerciseList.length; exerciseIndex++) {
+      const { calibration, exercise } = sessionExerciseList[exerciseIndex];
+
+      const setCountFromPlan = resolvedSetPlan.exerciseIdToSetCount.get(exercise._id);
+      if (setCountFromPlan == null) {
+        throw new Error(
+          `No set plan found for exercise ${exercise._id}, ${exercise.exerciseName} in microcycle ${microcycleIndex}`
+        );
+      }
+
+      // Get equipment for weight calculations
+      const equipment = context.equipmentMap.get(exercise.workoutEquipmentTypeId);
+      if (!equipment) {
+        throw new Error(
+          `Equipment type not found for exercise ${exercise._id}, ${exercise.exerciseName}`
+        );
+      }
+      if (!equipment.weightOptions || equipment.weightOptions.length === 0) {
+        throw new Error(
+          `No weight options defined for equipment type ${equipment._id}, ${equipment.title}`
+        );
+      }
+
+      const sessionExercise = WorkoutSessionExerciseSchema.parse({
+        userId: mesocycle.userId,
+        workoutSessionId: session._id,
+        workoutExerciseId: exercise._id,
+        isRecoveryExercise: resolvedSetPlan.recoveryExerciseIds.has(exercise._id)
+      });
+
+      WorkoutSetService.generateSetsForSessionExercise({
+        context,
+        exercise,
+        calibration,
+        session,
+        sessionExercise,
+        microcycleIndex,
+        sessionIndex,
+        setCount: setCountFromPlan,
+        targetRir,
+        isDeloadMicrocycle
+      });
+
+      const setsForThisExercise = context.setsToCreate.slice(-setCountFromPlan);
+
+      sessionExercise.setOrder.push(...setsForThisExercise.map((s) => s._id));
+      session.sessionExerciseOrder.push(sessionExercise._id);
+      context.addSessionExercise(sessionExercise);
+    }
+
+    // Add session to microcycle's session order and context
+    microcycle.sessionOrder.push(session._id);
+    context.addSession(session);
+  }
+}

package/lib/services/workout/SessionExercise/WorkoutSessionExerciseService.d.ts

@@ -0,0 +1,45 @@
+import type { WorkoutSessionExercise } from '../../../documents/workout/WorkoutSessionExercise.js';
+/**
+ * A service for handling operations related to {@link WorkoutSessionExercise}s.
+ */
+export default class WorkoutSessionExerciseService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude for a specific exercise within a session.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getRsmTotal(sessionExercise: WorkoutSessionExercise): number | null;
+    /**
+     * Calculates the total fatigue score for a specific exercise within a session.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getFatigueTotal(sessionExercise: WorkoutSessionExercise): number | null;
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR) for a specific exercise.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getSFR(sessionExercise: WorkoutSessionExercise): number | null;
+    /**
+     * Uses the soreness/performance table from the workout model notes to recommend whether to add
+     * sets next microcycle or employ recovery sessions.
+     *
+     * Interpretation:
+     * - Returns `-1` when recovery sessions should be employed.
+     * - Returns `0` when no sets should be added.
+     * - Returns a non-negative integer when sets should be added.
+     * - Returns `null` when insufficient data is available.
+     *
+     * The table is:
+     *
+     * | Soreness Score ↓ \ Performance Score → | 0 | 1 | 2 | 3 |
+       |---|---|---|---|---|
+       | **0** | Add 1–3 sets | Add 0–2 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **1** | Add 1–2 sets | Add 0–1 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **2** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **3** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+     */
+    static getRecommendedSetAdditionsOrRecovery(workoutSessionExercise: WorkoutSessionExercise): number | null;
+}
+//# sourceMappingURL=WorkoutSessionExerciseService.d.ts.map

package/lib/services/workout/SessionExercise/WorkoutSessionExerciseService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSessionExerciseService.d.ts","sourceRoot":"","sources":["../../../../src/services/workout/SessionExercise/WorkoutSessionExerciseService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAGnG;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,6BAA6B;IAChD;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,eAAe,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI;IAI1E;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,eAAe,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI;IAI9E;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI;IAIrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,oCAAoC,CACzC,sBAAsB,EAAE,sBAAsB,GAC7C,MAAM,GAAG,IAAI;CAqBjB"}

package/lib/services/workout/SessionExercise/WorkoutSessionExerciseService.js

@@ -0,0 +1,69 @@
+import WorkoutSFRService from '../util/SFR/WorkoutSFRService.js';
+/**
+ * A service for handling operations related to {@link WorkoutSessionExercise}s.
+ */
+export default class WorkoutSessionExerciseService {
+    /**
+     * Calculates the total Raw Stimulus Magnitude for a specific exercise within a session.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getRsmTotal(sessionExercise) {
+        return WorkoutSFRService.getRsmTotal(sessionExercise.rsm);
+    }
+    /**
+     * Calculates the total fatigue score for a specific exercise within a session.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getFatigueTotal(sessionExercise) {
+        return WorkoutSFRService.getFatigueTotal(sessionExercise.fatigue);
+    }
+    /**
+     * Calculates the Stimulus to Fatigue Ratio (SFR) for a specific exercise.
+     *
+     * @param sessionExercise The workout session exercise.
+     */
+    static getSFR(sessionExercise) {
+        return WorkoutSFRService.getSFR(sessionExercise.rsm, sessionExercise.fatigue);
+    }
+    /**
+     * Uses the soreness/performance table from the workout model notes to recommend whether to add
+     * sets next microcycle or employ recovery sessions.
+     *
+     * Interpretation:
+     * - Returns `-1` when recovery sessions should be employed.
+     * - Returns `0` when no sets should be added.
+     * - Returns a non-negative integer when sets should be added.
+     * - Returns `null` when insufficient data is available.
+     *
+     * The table is:
+     *
+     * | Soreness Score ↓ \ Performance Score → | 0 | 1 | 2 | 3 |
+       |---|---|---|---|---|
+       | **0** | Add 1–3 sets | Add 0–2 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **1** | Add 1–2 sets | Add 0–1 sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **2** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+       | **3** | Do not add sets | Do not add sets | Do not add sets | Employ recovery sessions (see Fatigue Management) |
+     */
+    static getRecommendedSetAdditionsOrRecovery(workoutSessionExercise) {
+        const { performanceScore, sorenessScore } = workoutSessionExercise;
+        if (sorenessScore == null || performanceScore == null) {
+            return null;
+        }
+        // Table mapping (sorenessScore rows, performanceScore columns).
+        // Values are representative set additions (midpoint of table ranges), or -1 for recovery.
+        const table = [
+            // Soreness 0: [Add 1-3, Add 0-2, Do not add, Recovery]
+            [2, 1, 0, -1],
+            // Soreness 1: [Add 1-2, Add 0-1, Do not add, Recovery]
+            [1, 0, 0, -1],
+            // Soreness 2: [Do not add, Do not add, Do not add, Recovery]
+            [0, 0, 0, -1],
+            // Soreness 3: [Do not add, Do not add, Do not add, Recovery]
+            [0, 0, 0, -1]
+        ];
+        return table[sorenessScore]?.[performanceScore] ?? null;
+    }
+}
+//# sourceMappingURL=WorkoutSessionExerciseService.js.map

package/lib/services/workout/SessionExercise/WorkoutSessionExerciseService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkoutSessionExerciseService.js","sourceRoot":"","sources":["../../../../src/services/workout/SessionExercise/WorkoutSessionExerciseService.ts"],"names":[],"mappings":"AACA,OAAO,iBAAiB,MAAM,kCAAkC,CAAC;AAEjE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,6BAA6B;IAChD;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,eAAuC;QACxD,OAAO,iBAAiB,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,eAAuC;QAC5D,OAAO,iBAAiB,CAAC,eAAe,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,eAAuC;QACnD,OAAO,iBAAiB,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,oCAAoC,CACzC,sBAA8C;QAE9C,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAAG,sBAAsB,CAAC;QACnE,IAAI,aAAa,IAAI,IAAI,IAAI,gBAAgB,IAAI,IAAI,EAAE,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,gEAAgE;QAChE,0FAA0F;QAC1F,MAAM,KAAK,GAAe;YACxB,uDAAuD;YACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACb,uDAAuD;YACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACb,6DAA6D;YAC7D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACb,6DAA6D;YAC7D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;SACd,CAAC;QAEF,OAAO,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC;IAC1D,CAAC;CACF"}