@dgpholdings/greatoak-shared 1.2.93 → 1.2.95

package/dist/__mocks__/user.mock.js

@@ -16,6 +16,7 @@ exports.mockUser = {
     bodyFatPercentage: 15,
     metricSystem: "EU",
     appLanguage: "en",
+    goalProfile: undefined,
     preferencesUpdatedAt: new Date("2023-01-01").toISOString(),
     femaleHealth: null, // Male user
     constellationLevel: 1,

package/dist/constants/goalJourney.d.ts

@@ -1,10 +1,11 @@
+import { TActivityLevel } from "../types";
 import { TAiFitnessGoal, TWorkoutIntent } from "./AiExerciseVocabulary";
 export declare const USER_FITNESS_GOALS: readonly ["lose_weight", "build_muscle", "lean_and_toned", "glutes_and_legs", "get_stronger", "boost_endurance", "athletic_performance", "general_fitness", "posture_and_back", "stress_relief", "rehabilitation", "core_strength", "mobility_flexibility"];
 export type TUserFitnessGoal = (typeof USER_FITNESS_GOALS)[number];
 export type TSessionIntent = TWorkoutIntent | "rest";
 export declare const GOAL_SESSION_INTENTS: Record<TUserFitnessGoal, TWeeklyIntentTemplate>;
 export declare const GOAL_TO_AI_FITNESS_GOAL: Record<TUserFitnessGoal, TAiFitnessGoal>;
-export declare const TRAINING_PHASES: readonly [1, 2, 3, 4];
+export declare const TRAINING_PHASES: readonly ["foundation", "momentum", "push", "peak"];
 export type TTrainingPhase = (typeof TRAINING_PHASES)[number];
 export type TPhaseDisplay = {
     /** i18n key for the phase name — e.g. "goalPhase.foundation.name" */
@@ -50,7 +51,7 @@ export type TIntentDisplay = {
      */
     emoji: string;
 };
-export declare const INTENT_DISPLAY: Partial<Record<TSessionIntent, TIntentDisplay>>;
+export declare const INTENT_DISPLAY: Record<Exclude<TSessionIntent, "arms" | "back" | "unstructured">, TIntentDisplay>;
 export type TGoalDisplay = {
     /** i18n key for the goal name — e.g. "userGoal.loseWeight.name" */
     nameKey: string;
@@ -82,17 +83,18 @@ export type TGoalCategoryDisplay = {
     labelEn: string;
 };
 export declare const GOAL_CATEGORY_DISPLAY: Record<TGoalCategory, TGoalCategoryDisplay>;
+export declare const PHASE_ENTRY_CREDIT: Record<TActivityLevel, number>;
+export declare const RECENCY_CREDIT: Record<TActivityLevel, number>;
 /**
- * Derive the current training phase from the week number since goal start.
- * Week is 1-indexed (week 1 = first week on the program).
+ * Derive training phase from time + volume + recency.
+ * All three must pass — week count alone is NOT sufficient.
+ * A user doing 12 sessions over one year has not built a training base.
  *
- * @example
- * derivePhase(1)  // → 1 (Foundation)
- * derivePhase(3)  // → 2 (Momentum)
- * derivePhase(7)  // → 3 (Push)
- * derivePhase(10) // → 4 (Peak)
+ * On goal start day (no sessions yet), pass:
+ *   totalSessions = PHASE_ENTRY_CREDIT[user.fitnessLevel]
+ *   sessionsInLast4Weeks = RECENCY_CREDIT[user.fitnessLevel]
  */
-export declare function derivePhase(weekNumber: number): TTrainingPhase;
+export declare function derivePhase(weekNumber: number, totalSessions: number, sessionsInLast4Weeks: number): TTrainingPhase;
 export declare const DAYS_PER_WEEK_OPTIONS: readonly [2, 3, 4, 5];
 export type TDaysPerWeek = (typeof DAYS_PER_WEEK_OPTIONS)[number];
 export type TDurationHint = "short" | "medium" | "long";
@@ -105,3 +107,5 @@ export type TWeeklyIntentTemplate = [
     TSessionIntent,
     TSessionIntent
 ];
+export type TGoalPhaseHints = Record<TTrainingPhase, string>;
+export declare const GOAL_PHASE_HINTS: Record<TUserFitnessGoal, TGoalPhaseHints>;

package/dist/constants/goalJourney.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DAYS_PER_WEEK_OPTIONS = exports.GOAL_CATEGORY_DISPLAY = exports.GOAL_DISPLAY = exports.INTENT_DISPLAY = exports.PHASE_DISPLAY = exports.TRAINING_PHASES = exports.GOAL_TO_AI_FITNESS_GOAL = exports.GOAL_SESSION_INTENTS = exports.USER_FITNESS_GOALS = void 0;
+exports.GOAL_PHASE_HINTS = exports.DAYS_PER_WEEK_OPTIONS = exports.RECENCY_CREDIT = exports.PHASE_ENTRY_CREDIT = exports.GOAL_CATEGORY_DISPLAY = exports.GOAL_DISPLAY = exports.INTENT_DISPLAY = exports.PHASE_DISPLAY = exports.TRAINING_PHASES = exports.GOAL_TO_AI_FITNESS_GOAL = exports.GOAL_SESSION_INTENTS = exports.USER_FITNESS_GOALS = void 0;
 exports.derivePhase = derivePhase;
 exports.USER_FITNESS_GOALS = [
     // Appearance
@@ -126,9 +126,15 @@ exports.GOAL_TO_AI_FITNESS_GOAL = {
     core_strength: "core_strength",
     mobility_flexibility: "mobility",
 };
-exports.TRAINING_PHASES = [1, 2, 3, 4];
+// Foundation → Momentum → Push → Peak
+exports.TRAINING_PHASES = [
+    "foundation",
+    "momentum",
+    "push",
+    "peak",
+];
 exports.PHASE_DISPLAY = {
-    1: {
+    foundation: {
         nameKey: "goalPhase.foundation.name",
         nameEn: "Foundation",
         subtitleKey: "goalPhase.foundation.subtitle",
@@ -140,7 +146,7 @@ exports.PHASE_DISPLAY = {
         weekRange: [1, 2],
         intensityPercent: 40,
     },
-    2: {
+    momentum: {
         nameKey: "goalPhase.momentum.name",
         nameEn: "Momentum",
         subtitleKey: "goalPhase.momentum.subtitle",
@@ -152,7 +158,7 @@ exports.PHASE_DISPLAY = {
         weekRange: [3, 5],
         intensityPercent: 60,
     },
-    3: {
+    push: {
         nameKey: "goalPhase.push.name",
         nameEn: "Push",
         subtitleKey: "goalPhase.push.subtitle",
@@ -164,7 +170,7 @@ exports.PHASE_DISPLAY = {
         weekRange: [6, 8],
         intensityPercent: 80,
     },
-    4: {
+    peak: {
         nameKey: "goalPhase.peak.name",
         nameEn: "Peak",
         subtitleKey: "goalPhase.peak.subtitle",
@@ -421,23 +427,169 @@ exports.GOAL_CATEGORY_DISPLAY = {
 // derivePhase — pure helper
 // Shared between Lambda and client — lives here so neither duplicates it
 // ---------------------------------------------------------------------------
+exports.PHASE_ENTRY_CREDIT = {
+    sedentary: 0,
+    "lightly-active": 0,
+    "moderately-active": 6, // enters Momentum directly
+    "very-active": 12, // enters Push directly
+};
+exports.RECENCY_CREDIT = {
+    sedentary: 0,
+    "lightly-active": 0,
+    "moderately-active": 4,
+    "very-active": 8,
+};
 /**
- * Derive the current training phase from the week number since goal start.
- * Week is 1-indexed (week 1 = first week on the program).
+ * Derive training phase from time + volume + recency.
+ * All three must pass — week count alone is NOT sufficient.
+ * A user doing 12 sessions over one year has not built a training base.
  *
- * @example
- * derivePhase(1)  // → 1 (Foundation)
- * derivePhase(3)  // → 2 (Momentum)
- * derivePhase(7)  // → 3 (Push)
- * derivePhase(10) // → 4 (Peak)
+ * On goal start day (no sessions yet), pass:
+ *   totalSessions = PHASE_ENTRY_CREDIT[user.fitnessLevel]
+ *   sessionsInLast4Weeks = RECENCY_CREDIT[user.fitnessLevel]
  */
-function derivePhase(weekNumber) {
-    if (weekNumber <= 2)
-        return 1;
-    if (weekNumber <= 5)
-        return 2;
-    if (weekNumber <= 8)
-        return 3;
-    return 4;
+function derivePhase(weekNumber, totalSessions, sessionsInLast4Weeks) {
+    // Foundation → needs minimum 2 weeks, 6 sessions, 1 session/week pace
+    if (weekNumber < 2 || totalSessions < 6 || sessionsInLast4Weeks < 4)
+        return "foundation";
+    // Momentum → needs 6 weeks, 12 sessions, ~1.5 sessions/week pace
+    if (weekNumber < 6 || totalSessions < 12 || sessionsInLast4Weeks < 6)
+        return "momentum";
+    // Push → needs 9 weeks, 20 sessions, ~2 sessions/week pace
+    if (weekNumber < 9 || totalSessions < 20 || sessionsInLast4Weeks < 8)
+        return "push";
+    return "peak";
 }
 exports.DAYS_PER_WEEK_OPTIONS = [2, 3, 4, 5];
+exports.GOAL_PHASE_HINTS = {
+    lose_weight: {
+        // "Build the cardio habit"
+        foundation: "goalPhaseHint.loseWeight.foundation.buildCardioHabit",
+        // "Intensity picks up"
+        momentum: "goalPhaseHint.loseWeight.momentum.intensityPicksUp",
+        // "Fat burning at its best"
+        push: "goalPhaseHint.loseWeight.push.fatBurningAtBest",
+        // "Final push to your goal"
+        peak: "goalPhaseHint.loseWeight.peak.finalPushToGoal",
+    },
+    build_muscle: {
+        // "Learn the fundamental movements"
+        foundation: "goalPhaseHint.buildMuscle.foundation.learnFundamentalMovements",
+        // "Volume increases, splits begin"
+        momentum: "goalPhaseHint.buildMuscle.momentum.volumeIncreaseSplitsBegin",
+        // "Real muscle growth happens here"
+        push: "goalPhaseHint.buildMuscle.push.realMuscleGrowthHappensHere",
+        // "Push to your peak output"
+        peak: "goalPhaseHint.buildMuscle.peak.pushToPeakOutput",
+    },
+    lean_and_toned: {
+        // "Start moving consistently"
+        foundation: "goalPhaseHint.leanAndToned.foundation.startMovingConsistently",
+        // "Splits begin, cardio added"
+        momentum: "goalPhaseHint.leanAndToned.momentum.splitsBeginCardioAdded",
+        // "Definition starts to show"
+        push: "goalPhaseHint.leanAndToned.push.definitionStartsToShow",
+        // "Your best shape yet"
+        peak: "goalPhaseHint.leanAndToned.peak.yourBestShapeYet",
+    },
+    glutes_and_legs: {
+        // "Learn hip-hinge and squat patterns"
+        foundation: "goalPhaseHint.glutesAndLegs.foundation.learnHipHingeSquatPatterns",
+        // "Volume builds in lower body"
+        momentum: "goalPhaseHint.glutesAndLegs.momentum.volumeBuildsLowerBody",
+        // "Legs up to 3 times per week"
+        push: "goalPhaseHint.glutesAndLegs.push.legsThreeTimesPerWeek",
+        // "Maximum lower body output"
+        peak: "goalPhaseHint.glutesAndLegs.peak.maximumLowerBodyOutput",
+    },
+    get_stronger: {
+        // "Master the big compound lifts"
+        foundation: "goalPhaseHint.getStronger.foundation.masterBigCompoundLifts",
+        // "Load increases week on week"
+        momentum: "goalPhaseHint.getStronger.momentum.loadIncreasesWeekOnWeek",
+        // "Heavy compound focus"
+        push: "goalPhaseHint.getStronger.push.heavyCompoundFocus",
+        // "Strength peak — test your limits"
+        peak: "goalPhaseHint.getStronger.peak.strengthPeakTestYourLimits",
+    },
+    boost_endurance: {
+        // "Build base aerobic fitness"
+        foundation: "goalPhaseHint.boostEndurance.foundation.buildBaseAerobicFitness",
+        // "Duration and distance increase"
+        momentum: "goalPhaseHint.boostEndurance.momentum.durationDistanceIncrease",
+        // "High volume cardio sessions"
+        push: "goalPhaseHint.boostEndurance.push.highVolumeCardioSessions",
+        // "Peak cardiovascular output"
+        peak: "goalPhaseHint.boostEndurance.peak.peakCardiovascularOutput",
+    },
+    athletic_performance: {
+        // "Movement quality comes first"
+        foundation: "goalPhaseHint.athleticPerformance.foundation.movementQualityFirst",
+        // "Power and speed sessions begin"
+        momentum: "goalPhaseHint.athleticPerformance.momentum.powerSpeedSessionsBegin",
+        // "Sport specific intensity"
+        push: "goalPhaseHint.athleticPerformance.push.sportSpecificIntensity",
+        // "Peak athletic output"
+        peak: "goalPhaseHint.athleticPerformance.peak.peakAthleticOutput",
+    },
+    general_fitness: {
+        // "Build the habit"
+        foundation: "goalPhaseHint.generalFitness.foundation.buildTheHabit",
+        // "Add more variety"
+        momentum: "goalPhaseHint.generalFitness.momentum.addMoreVariety",
+        // "Consistent challenge"
+        push: "goalPhaseHint.generalFitness.push.consistentChallenge",
+        // "Sustained healthy output"
+        peak: "goalPhaseHint.generalFitness.peak.sustainedHealthyOutput",
+    },
+    posture_and_back: {
+        // "Activate neglected muscles"
+        foundation: "goalPhaseHint.postureAndBack.foundation.activateNeglectedMuscles",
+        // "Posterior chain strengthens"
+        momentum: "goalPhaseHint.postureAndBack.momentum.posteriorChainStrengthens",
+        // "Pull heavy split begins"
+        push: "goalPhaseHint.postureAndBack.push.pullHeavySplitBegins",
+        // "Posture transformation complete"
+        peak: "goalPhaseHint.postureAndBack.peak.postureTransformationComplete",
+    },
+    stress_relief: {
+        // "Low pressure movement"
+        foundation: "goalPhaseHint.stressRelief.foundation.lowPressureMovement",
+        // "Rhythm and routine develop"
+        momentum: "goalPhaseHint.stressRelief.momentum.rhythmAndRoutineDevelop",
+        // "Endorphin peak"
+        push: "goalPhaseHint.stressRelief.push.endorphinPeak",
+        // "Sustained stress release"
+        peak: "goalPhaseHint.stressRelief.peak.sustainedStressRelease",
+    },
+    rehabilitation: {
+        // "Safe mobility work only"
+        foundation: "goalPhaseHint.rehabilitation.foundation.safeMobilityWorkOnly",
+        // "Strength carefully reintroduced"
+        momentum: "goalPhaseHint.rehabilitation.momentum.strengthCarefullyReintroduced",
+        // "Full movement patterns restored"
+        push: "goalPhaseHint.rehabilitation.push.fullMovementPatternsRestored",
+        // "Back to full function"
+        peak: "goalPhaseHint.rehabilitation.peak.backToFullFunction",
+    },
+    core_strength: {
+        // "Core activation patterns"
+        foundation: "goalPhaseHint.coreStrength.foundation.coreActivationPatterns",
+        // "Volume and difficulty rise"
+        momentum: "goalPhaseHint.coreStrength.momentum.volumeAndDifficultyRise",
+        // "Heavy compound core work"
+        push: "goalPhaseHint.coreStrength.push.heavyCompoundCoreWork",
+        // "Maximum core output"
+        peak: "goalPhaseHint.coreStrength.peak.maximumCoreOutput",
+    },
+    mobility_flexibility: {
+        // "Daily mobility habit"
+        foundation: "goalPhaseHint.mobilityFlexibility.foundation.dailyMobilityHabit",
+        // "Range of motion grows"
+        momentum: "goalPhaseHint.mobilityFlexibility.momentum.rangeOfMotionGrows",
+        // "Full body flexibility"
+        push: "goalPhaseHint.mobilityFlexibility.push.fullBodyFlexibility",
+        // "Elite movement quality"
+        peak: "goalPhaseHint.mobilityFlexibility.peak.eliteMovementQuality",
+    },
+};

package/dist/constants/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./BodyCategories";
 export * from "./AiExerciseVocabulary";
+export * from "./goalJourney";

package/dist/constants/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./BodyCategories"), exports);
 __exportStar(require("./AiExerciseVocabulary"), exports);
+__exportStar(require("./goalJourney"), exports);

package/dist/types/TApiAiQuickStartWorkout.d.ts

@@ -1,5 +1,5 @@
 import { TAiEnergyLevel, TAiUserInjury, TQuickStartEquipmentGroupExplicit } from "../constants/AiExerciseVocabulary";
-import { TTrainingPhase, TUserFitnessGoal } from "./goalFeature";
+import { TTrainingPhase, TUserFitnessGoal } from "../constants/goalJourney";
 import { TTemplate } from "./TApiTemplateData";
 export type TApiAiQuickStartWorkoutReq = {
     /**

package/dist/types/TApiGoalContextRes.d.ts

@@ -0,0 +1,64 @@
+import { TWorkoutIntent } from "../constants";
+import { TDaysPerWeek, TSessionIntent, TTrainingPhase, TUserFitnessGoal } from "../constants/goalJourney";
+export type TGoalProfile = {
+    activeGoal: TUserFitnessGoal;
+    goalStartDate: string;
+    daysPerWeek: TDaysPerWeek;
+    phaseCompletions: {
+        phase: TTrainingPhase;
+        completedAt: string;
+        celebrationShown: boolean;
+    }[];
+    previousGoals: {
+        goal: TUserFitnessGoal;
+        startDate: string;
+        endDate: string;
+        weeksCompleted: number;
+        reasonEnded: "completed" | "changed";
+    }[];
+};
+export type TGoalContext = {
+    goal: TUserFitnessGoal;
+    daysPerWeek: TDaysPerWeek;
+    currentPhase: TTrainingPhase;
+    currentWeek: number;
+    weeklyStructure: TSessionIntent[];
+    lastSessionDate: string;
+    lastSessionIntent: TSessionIntent;
+    sessionsCompletedThisWeek: number;
+    totalSessionsSinceGoalStart: number;
+    sessionsInLast4Weeks: number;
+};
+export type TIntentRecommendation = {
+    intent: TWorkoutIntent;
+    confidence: number;
+    rationale: string;
+    decisionPath: "global_recovery" | "returning_user" | "gap_bridge" | "structure_follow" | "muscle_override";
+    intentScores: Partial<Record<TWorkoutIntent, number>>;
+};
+export type TGoalSessionSummary = {
+    sessionId: string;
+    createdAt: string;
+    intentId: TWorkoutIntent | undefined;
+    exercises: {
+        exerciseId: string;
+        thumbnailUrl: string;
+        name: string;
+    }[];
+};
+export type TApiGoalContextRes = {
+    status: 200;
+    goalProfile: TGoalProfile;
+    goalContext: TGoalContext;
+    recommendation: TIntentRecommendation;
+    recentSessions: TGoalSessionSummary[];
+    weeklySessionCounts: {
+        weekNumber: number;
+        weekStartDate: string;
+        count: number;
+    }[];
+    newPhaseUnlocked?: TTrainingPhase;
+} | {
+    status: 400 | 401 | 404 | 500;
+    message: string;
+};

package/dist/types/TApiGoalContextRes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/TApiUser.d.ts

@@ -1,6 +1,7 @@
 import type { TAiFitnessGoal, TAiUserInjury } from "../constants/AiExerciseVocabulary";
 import { TConstellationUserLevel } from "../utils";
 import { TGdprData } from "./commonTypes";
+import { TGoalProfile } from "./TApiGoalContextRes";
 import { TUserPreferences } from "./TUserPreferences";
 export type TAuthType = "email" | "apple" | "anonymous" | "token";
 export type TGender = "male" | "female" | "unmentioned";
@@ -27,6 +28,7 @@ export type TUserMetric = TUserPreferences & {
     gender: TGender;
     weightKg: number;
     heightCm: number;
+    goalProfile: TGoalProfile | undefined;
     emailAddress?: string;
     injuryInfo?: TInjuryInfo;
     subscriptionStatus: TSubscriptionStatus;

package/dist/types/index.d.ts

@@ -16,4 +16,4 @@ export type * from "./TApiAiExerciseAnalysis";
 export type * from "./TApiAdminAiHelp";
 export type * from "./TApiAiQuickStartWorkout";
 export type * from "./TApiClientConstellation";
-export * from "./goalFeature";
+export type * from "./TApiGoalContextRes";

package/dist/types/index.js

@@ -1,18 +1,2 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-// Features
-__exportStar(require("./goalFeature"), exports);

package/dist/utils/goalFeature/utilGoal.d.ts

@@ -0,0 +1,22 @@
+import { TMuscleFatigueResult } from "..";
+import { TSessionIntent } from "../../constants/goalJourney";
+import { TGoalContext, TGoalProfile, TIntentRecommendation } from "../../types/TApiGoalContextRes";
+export declare function resolveGoalContext(goalProfile: TGoalProfile, recentSessions: {
+    intentId: TSessionIntent | undefined;
+    createdAt: string;
+}[], now?: Date): TGoalContext | null;
+/**
+ * Recommend the next session intent.
+ *
+ * Decision pipeline (strict priority):
+ *   1. GLOBAL RECOVERY   avgFatigue > 72              → "mobility"
+ *   2. RETURNING USER    gap >= 7 days                → first non-rest slot
+ *   3. GAP BRIDGE        gap 3-7 days                 → most overdue slot
+ *   4. STRUCTURE FOLLOW  gap < 3 days                 → next slot (circular)
+ *   5. MUSCLE OVERRIDE   cluster fatigue > 65         → highest-readiness alt
+ *
+ * Output is always a valid TWorkoutIntent.
+ * Never outputs: "rest", "arms", "back", "unstructured".
+ * rationale is an i18n key — resolve via t() on the FE.
+ */
+export declare function recommendNextIntent(fatigue: TMuscleFatigueResult, goalContext: TGoalContext): TIntentRecommendation;

package/dist/utils/goalFeature/utilGoal.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGoalContext = resolveGoalContext;
+exports.recommendNextIntent = recommendNextIntent;
+const goalJourney_1 = require("../../constants/goalJourney");
+function resolveGoalContext(goalProfile, recentSessions, now = new Date()) {
+    var _a, _b;
+    if (!(goalProfile === null || goalProfile === void 0 ? void 0 : goalProfile.activeGoal) || !(goalProfile === null || goalProfile === void 0 ? void 0 : goalProfile.goalStartDate))
+        return null;
+    const goalStart = new Date(goalProfile.goalStartDate);
+    const msPerDay = 86400000;
+    const daysSince = (now.getTime() - goalStart.getTime()) / msPerDay;
+    const currentWeek = Math.max(1, Math.ceil(daysSince / 7));
+    // Sessions this calendar week (Monday 00:00 UTC)
+    const monday = new Date(now);
+    monday.setUTCDate(now.getUTCDate() - ((now.getUTCDay() + 6) % 7));
+    monday.setUTCHours(0, 0, 0, 0);
+    const last4WeeksCutoff = new Date(now.getTime() - 28 * msPerDay);
+    const goalStartTime = goalStart.getTime();
+    const sessionsSinceGoalStart = recentSessions.filter((s) => new Date(s.createdAt).getTime() >= goalStartTime);
+    const totalSince = sessionsSinceGoalStart.length;
+    const sessionsIn4Weeks = sessionsSinceGoalStart.filter((s) => new Date(s.createdAt) >= last4WeeksCutoff).length;
+    const sessionsThisWeek = sessionsSinceGoalStart.filter((s) => new Date(s.createdAt) >= monday).length;
+    const currentPhase = (0, goalJourney_1.derivePhase)(currentWeek, totalSince, sessionsIn4Weeks);
+    const weeklyStructure = [...goalJourney_1.GOAL_SESSION_INTENTS[goalProfile.activeGoal]];
+    // Edge case: no sessions yet — use first non-rest slot as entry point
+    if (recentSessions.length === 0) {
+        const firstActive = (_a = weeklyStructure.find((s) => s !== "rest")) !== null && _a !== void 0 ? _a : "full-body";
+        return {
+            goal: goalProfile.activeGoal,
+            daysPerWeek: goalProfile.daysPerWeek,
+            currentPhase,
+            currentWeek,
+            weeklyStructure,
+            lastSessionDate: goalProfile.goalStartDate,
+            lastSessionIntent: firstActive,
+            sessionsCompletedThisWeek: 0,
+            totalSessionsSinceGoalStart: 0,
+            sessionsInLast4Weeks: 0,
+        };
+    }
+    const lastSession = recentSessions[0]; // sorted desc by createdAt
+    return {
+        goal: goalProfile.activeGoal,
+        daysPerWeek: goalProfile.daysPerWeek,
+        currentPhase,
+        currentWeek,
+        weeklyStructure,
+        lastSessionDate: lastSession.createdAt,
+        lastSessionIntent: (_b = lastSession.intentId) !== null && _b !== void 0 ? _b : "unstructured",
+        sessionsCompletedThisWeek: sessionsThisWeek,
+        totalSessionsSinceGoalStart: totalSince,
+        sessionsInLast4Weeks: sessionsIn4Weeks,
+    };
+}
+// ---------------------------------------------------------------------------
+// Muscle → intent cluster
+// Keyed by keyof typeof EBodyParts — TypeScript enforces valid muscle keys
+// ---------------------------------------------------------------------------
+const MUSCLE_TO_INTENTS = {
+    "serratus-anterior": ["push", "upper"],
+    "tricep-brachii-long": ["push", "upper"],
+    "tricep-brachii-lateral": ["push", "upper"],
+    "latissimus-dorsi": ["pull", "upper"],
+    rhomboids: ["pull", "upper"],
+    trapezius: ["pull", "upper"],
+    "bicep-long-outer": ["pull", "upper"],
+    "bicep-short-inner": ["pull", "upper"],
+    "deltoids-posterior": ["pull", "upper"],
+    "fore-arm-inner": ["pull", "upper"],
+    "fore-arm-outer": ["pull", "upper"],
+    "lower-back": ["core"],
+    quadriceps: ["legs", "lower", "cardio", "fatburn"],
+    hamstrings: ["legs", "lower", "cardio", "fatburn"],
+    "glutes-maximus": ["legs", "lower", "cardio", "fatburn"], // burpees, jump squats
+    "glutes-medius": ["legs", "lower", "cardio", "fatburn"],
+    "medius-upper": ["legs", "lower", "cardio", "fatburn"],
+    "maximus-lower": ["legs", "lower", "cardio", "fatburn"],
+    adductors: ["legs", "lower", "cardio", "fatburn"],
+    "calf-inner": ["legs", "lower", "cardio"],
+    "calf-outer": ["legs", "lower", "cardio"],
+    calves: ["legs", "lower", "cardio"],
+    "pectoralis-major": ["push", "upper", "fatburn"],
+    "deltoids-anterior": ["push", "upper", "fatburn"],
+    "deltoids-middle": ["push", "upper", "fatburn"],
+    "abs-upper": ["core", "fatburn"],
+    "abs-lower": ["core", "fatburn"],
+    obliques: ["core", "fatburn"],
+};
+const MUSCLE_SCORED_INTENTS = [
+    "push",
+    "pull",
+    "legs",
+    "lower",
+    "upper",
+    "core",
+    "cardio",
+    "fatburn",
+];
+// ---------------------------------------------------------------------------
+// Goal → intent readiness bias
+// Modest nudge — never overrides the structural decision in steps 1-3
+// ---------------------------------------------------------------------------
+const GOAL_INTENT_BIAS = {
+    strength: { push: 10, pull: 10, legs: 8 },
+    hypertrophy: { push: 10, pull: 10, legs: 10 },
+    fat_loss: { cardio: 20, fatburn: 18, "full-body": 10 },
+    endurance: { cardio: 25, lower: 8 },
+    mobility: { mobility: 30, core: 8 },
+    rehabilitation: { mobility: 25, core: 12 },
+    sport_performance: { legs: 12, core: 10, cardio: 8 },
+    general_fitness: { "full-body": 15, cardio: 8 },
+    core_strength: { core: 25, pull: 6, legs: 6 },
+};
+const INTENT_RATIONALE = {
+    push: "intentRationale.push",
+    pull: "intentRationale.pull",
+    legs: "intentRationale.legs",
+    lower: "intentRationale.lower",
+    upper: "intentRationale.upper",
+    core: "intentRationale.core",
+    cardio: "intentRationale.cardio",
+    strength: "intentRationale.strength",
+    fatburn: "intentRationale.fatburn",
+    mobility: "intentRationale.mobility",
+    "full-body": "intentRationale.fullBody",
+};
+const GLOBAL_RECOVERY_THRESHOLD = 72;
+const CLUSTER_FATIGUE_HARD_CAP = 65;
+const RETURNING_USER_GAP_DAYS = 7;
+const GAP_BRIDGE_THRESHOLD_DAYS = 3;
+const HIGH_CONFIDENCE_GAP = 15;
+function daysSince(isoDate, now = new Date()) {
+    return (now.getTime() - new Date(isoDate).getTime()) / 86400000;
+}
+function globalAvgFatigue(fatigue) {
+    const values = Object.values(fatigue).map((v) => v.fatigue);
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+function clusterAvgFatigue(intent, fatigue) {
+    const muscles = Object.entries(MUSCLE_TO_INTENTS)
+        .filter(([, intents]) => intents.includes(intent))
+        .map(([muscle]) => muscle);
+    if (muscles.length === 0)
+        return 0;
+    const scores = muscles.map((m) => { var _a, _b; return (_b = (_a = fatigue[m]) === null || _a === void 0 ? void 0 : _a.fatigue) !== null && _b !== void 0 ? _b : 0; });
+    return scores.reduce((a, b) => a + b, 0) / scores.length;
+}
+function buildReadinessScores(fatigue, goalContext) {
+    var _a, _b, _c, _d, _e, _f;
+    const bias = (_a = GOAL_INTENT_BIAS[goalJourney_1.GOAL_TO_AI_FITNESS_GOAL[goalContext.goal]]) !== null && _a !== void 0 ? _a : {};
+    const scores = {};
+    for (const intent of MUSCLE_SCORED_INTENTS) {
+        scores[intent] =
+            100 - clusterAvgFatigue(intent, fatigue) + ((_b = bias[intent]) !== null && _b !== void 0 ? _b : 0);
+    }
+    scores["full-body"] = 50 + ((_c = bias["full-body"]) !== null && _c !== void 0 ? _c : 0);
+    scores["strength"] = 50 + ((_d = bias["strength"]) !== null && _d !== void 0 ? _d : 0);
+    scores["fatburn"] = 50 + ((_e = bias["fatburn"]) !== null && _e !== void 0 ? _e : 0);
+    scores["mobility"] = 60 + ((_f = bias["mobility"]) !== null && _f !== void 0 ? _f : 0);
+    return scores;
+}
+function topByScore(scores) {
+    return Object.entries(scores).sort(([, a], [, b]) => b - a)[0][0];
+}
+function computeConfidence(scores) {
+    var _a;
+    const sorted = Object.values(scores).sort((a, b) => b - a);
+    const gap = sorted[0] - ((_a = sorted[1]) !== null && _a !== void 0 ? _a : 0);
+    if (gap >= HIGH_CONFIDENCE_GAP)
+        return Math.min(0.95, 0.7 + gap / 100);
+    return Math.max(0.4, 0.5 + gap / 100);
+}
+function validateOrFallback(desired, scores, fatigue) {
+    if (desired === "rest") {
+        return { intent: topByScore(scores), wasOverridden: true };
+    }
+    const desiredRec = desired;
+    if (MUSCLE_SCORED_INTENTS.includes(desiredRec)) {
+        if (clusterAvgFatigue(desiredRec, fatigue) <= CLUSTER_FATIGUE_HARD_CAP) {
+            return { intent: desiredRec, wasOverridden: false };
+        }
+        return { intent: topByScore(scores), wasOverridden: true };
+    }
+    return { intent: desiredRec, wasOverridden: false };
+}
+/**
+ * Find the next non-rest slot in weeklyStructure after afterIntent.
+ * Circular — wraps around. Used by both gap bridge and structure follow.
+ * Returns "full-body" if structure is entirely rest days (defensive).
+ */
+function nextNonRestSlot(weeklyStructure, afterIntent) {
+    const lastIdx = weeklyStructure.findIndex((s) => s === afterIntent && s !== "rest");
+    const start = lastIdx === -1 ? 0 : (lastIdx + 1) % weeklyStructure.length;
+    for (let i = 0; i < weeklyStructure.length; i++) {
+        const slot = weeklyStructure[(start + i) % weeklyStructure.length];
+        if (slot !== "rest")
+            return slot;
+    }
+    return "full-body";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Recommend the next session intent.
+ *
+ * Decision pipeline (strict priority):
+ *   1. GLOBAL RECOVERY   avgFatigue > 72              → "mobility"
+ *   2. RETURNING USER    gap >= 7 days                → first non-rest slot
+ *   3. GAP BRIDGE        gap 3-7 days                 → most overdue slot
+ *   4. STRUCTURE FOLLOW  gap < 3 days                 → next slot (circular)
+ *   5. MUSCLE OVERRIDE   cluster fatigue > 65         → highest-readiness alt
+ *
+ * Output is always a valid TWorkoutIntent.
+ * Never outputs: "rest", "arms", "back", "unstructured".
+ * rationale is an i18n key — resolve via t() on the FE.
+ */
+function recommendNextIntent(fatigue, goalContext) {
+    var _a;
+    const { weeklyStructure, lastSessionDate, lastSessionIntent } = goalContext;
+    const gap = daysSince(lastSessionDate);
+    const avgFat = globalAvgFatigue(fatigue);
+    const scores = buildReadinessScores(fatigue, goalContext);
+    // ── 1. GLOBAL RECOVERY ───────────────────────────────────────────────────
+    if (avgFat >= GLOBAL_RECOVERY_THRESHOLD) {
+        return {
+            intent: "mobility",
+            confidence: 0.92,
+            rationale: INTENT_RATIONALE["mobility"],
+            decisionPath: "global_recovery",
+            intentScores: scores,
+        };
+    }
+    // ── 2. RETURNING USER ────────────────────────────────────────────────────
+    if (gap >= RETURNING_USER_GAP_DAYS) {
+        const reEntry = (_a = weeklyStructure.find((s) => s !== "rest")) !== null && _a !== void 0 ? _a : "full-body";
+        const { intent } = validateOrFallback(reEntry, scores, fatigue);
+        return {
+            intent,
+            confidence: 0.82,
+            rationale: INTENT_RATIONALE[intent],
+            decisionPath: "returning_user",
+            intentScores: scores,
+        };
+    }
+    // ── 3. GAP BRIDGE ────────────────────────────────────────────────────────
+    if (gap >= GAP_BRIDGE_THRESHOLD_DAYS) {
+        const missed = nextNonRestSlot(weeklyStructure, lastSessionIntent);
+        const { intent, wasOverridden } = validateOrFallback(missed, scores, fatigue);
+        return {
+            intent,
+            confidence: computeConfidence(scores),
+            rationale: INTENT_RATIONALE[intent],
+            decisionPath: wasOverridden ? "muscle_override" : "gap_bridge",
+            intentScores: scores,
+        };
+    }
+    // ── 4. STRUCTURE FOLLOW + 5. MUSCLE OVERRIDE ─────────────────────────────
+    const next = nextNonRestSlot(weeklyStructure, lastSessionIntent);
+    const { intent, wasOverridden } = validateOrFallback(next, scores, fatigue);
+    return {
+        intent,
+        confidence: computeConfidence(scores),
+        rationale: INTENT_RATIONALE[intent],
+        decisionPath: wasOverridden ? "muscle_override" : "structure_follow",
+        intentScores: scores,
+    };
+}

package/dist/utils/index.d.ts

@@ -14,4 +14,5 @@ export * from "./exerciseRecord/workoutMath";
 export * from "./exerciseRecord/recordValidator";
 export * from "./metricConversions";
 export * from "./constellation";
+export * from "./goalFeature/utilGoal";
 export type * from "./constellation/types";

package/dist/utils/index.js

@@ -52,3 +52,4 @@ __exportStar(require("./exerciseRecord/workoutMath"), exports);
 __exportStar(require("./exerciseRecord/recordValidator"), exports);
 __exportStar(require("./metricConversions"), exports);
 __exportStar(require("./constellation"), exports);
+__exportStar(require("./goalFeature/utilGoal"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dgpholdings/greatoak-shared",
-	"version": "1.2.93",
+	"version": "1.2.95",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",