@dgpholdings/greatoak-shared 1.2.92 → 1.2.93

package/dist/__mocks__/user.mock.js

@@ -5,7 +5,6 @@ const testIds_1 = require("./testIds");
 exports.mockUser = {
     // TUserPreferences fields (flat in TUserMetric)
     preferredDurationMinutes: 45,
-    fitnessGoals: ["hypertrophy"],
     preferredEquipment: ["dumbbell", "barbell"],
     preferCompoundMovements: true,
     includeWarmup: "ai_decide",

package/dist/constants/index.d.ts

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

package/dist/constants/index.js

@@ -16,4 +16,3 @@ 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,4 +1,5 @@
 import { TAiEnergyLevel, TAiUserInjury, TQuickStartEquipmentGroupExplicit } from "../constants/AiExerciseVocabulary";
+import { TTrainingPhase, TUserFitnessGoal } from "./goalFeature";
 import { TTemplate } from "./TApiTemplateData";
 export type TApiAiQuickStartWorkoutReq = {
     /**
@@ -62,6 +63,12 @@ export type TApiAiQuickStartWorkoutReq = {
      * backend treats it as "no equipment filter" — i.e. all candidates eligible.
      */
     equipmentSelectionOverride: TQuickStartEquipmentSelection;
+    goalContext?: {
+        activeGoal: TUserFitnessGoal;
+        currentPhase: TTrainingPhase;
+        currentWeek: number;
+        phaseName: string;
+    };
 };
 export type TQuickStartEquipmentSelection = {
     type: "preferences";

package/dist/types/TApiAuth.d.ts

@@ -1,5 +1,4 @@
-import type { TAiFitnessGoal } from "../constants/AiExerciseVocabulary";
-import { TAuthType, TGender, TProfessionalCategory, TUserMetric, TUserType, TInjuryInfo } from "./TApiUser";
+import { TAuthType, TGender, TInjuryInfo, TProfessionalCategory, TUserMetric, TUserType } from "./TApiUser";
 import { TActivityLevel } from "./TUserPreferences";
 /**
  * Anonymous signup request.
@@ -25,7 +24,6 @@ export type TApiSignupAnonymousReq = {
     gender: TGender;
     bodyFatPercentage: number;
     metricSystem: "US" | "EU";
-    fitnessGoals: TAiFitnessGoal[];
     fitnessLevel: TActivityLevel;
     injuryInfo?: TInjuryInfo;
     gdprAnalytics: boolean;

package/dist/types/TApiUser.d.ts

@@ -25,8 +25,8 @@ export type TUserMetric = TUserPreferences & {
     userType: TUserType;
     professionType?: TProfessionalCategory;
     gender: TGender;
-    weightKg?: number;
-    heightCm?: number;
+    weightKg: number;
+    heightCm: number;
     emailAddress?: string;
     injuryInfo?: TInjuryInfo;
     subscriptionStatus: TSubscriptionStatus;

package/dist/types/TUserPreferences.d.ts

@@ -1,11 +1,10 @@
-import { TAiEquipmentType, TAiFitnessGoal } from "../constants";
+import { TAiEquipmentType } from "../constants";
 import { TBodyPart } from "./TApiExercise";
 export type TPreferredDuration = 20 | 30 | 45 | 60 | 90 | 120;
 export type TAIDecision = "yes" | "no" | "ai_decide";
 export type TWarmupStyle = "dynamic_stretching" | "light_cardio";
 export type TStablePreferences = {
     preferredDurationMinutes: TPreferredDuration;
-    fitnessGoals: TAiFitnessGoal[];
     preferredEquipment: TAiEquipmentType[];
     preferCompoundMovements: boolean;
     includeWarmup: TAIDecision;
@@ -13,7 +12,7 @@ export type TStablePreferences = {
     warmupStyle: TWarmupStyle | null;
     favouriteMuscleGroups: TBodyPart[];
     blacklistedExerciseIds: string[];
-    fitnessLevel?: TActivityLevel;
+    fitnessLevel: TActivityLevel;
     bodyFatPercentage?: number;
     metricSystem: "US" | "EU";
     appLanguage: string;

package/dist/types/goalFeature/TApiGoalContextRes.d.ts

@@ -0,0 +1,64 @@
+import { TWorkoutIntent } from "../../constants";
+import { TDaysPerWeek, TSessionIntent, TTrainingPhase, TUserFitnessGoal } from "./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/goalFeature/TApiGoalContextRes.js

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

package/dist/types/goalFeature/goalJourney.d.ts

@@ -0,0 +1,111 @@
+import { TActivityLevel } from "..";
+import { TAiFitnessGoal, TWorkoutIntent } from "../../constants/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 ["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" */
+    nameKey: string;
+    /** English fallback for nameKey */
+    nameEn: string;
+    /** i18n key for the short subtitle — e.g. "goalPhase.foundation.subtitle" */
+    subtitleKey: string;
+    /** English fallback for subtitleKey */
+    subtitleEn: string;
+    /** i18n key for the longer purpose description shown in phase detail */
+    purposeKey: string;
+    /** English fallback for purposeKey */
+    purposeEn: string;
+    /** i18n key for the week range label — e.g. "goalPhase.foundation.duration" */
+    durationKey: string;
+    /** English fallback for durationKey */
+    durationEn: string;
+    /** Inclusive week range [startWeek, endWeek]. Phase 4 end is open (99). */
+    weekRange: [number, number];
+    /**
+     * Reference intensity as a percentage (0–100).
+     * For UI progress bars / intensity indicators only — not used in algorithm.
+     */
+    intensityPercent: number;
+};
+export declare const PHASE_DISPLAY: Record<TTrainingPhase, TPhaseDisplay>;
+export type TIntentDisplay = {
+    /** i18n key for the full label — e.g. "sessionIntent.push.label" */
+    labelKey: string;
+    /** English fallback for labelKey */
+    labelEn: string;
+    /**
+     * i18n key for the short label used in compact journey nodes.
+     * e.g. "sessionIntent.push.shortLabel"
+     */
+    shortLabelKey: string;
+    /** English fallback for shortLabelKey */
+    shortLabelEn: string;
+    /**
+     * Emoji for the session node icon.
+     * Not translated — emoji is universal.
+     */
+    emoji: string;
+};
+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;
+    /** English fallback for nameKey */
+    nameEn: string;
+    /** i18n key for the short description shown on goal selection screen */
+    descriptionKey: string;
+    /** English fallback for descriptionKey */
+    descriptionEn: string;
+    /**
+     * i18n key for the motivational tagline shown on the goal journey screen.
+     * e.g. "userGoal.loseWeight.tagline"
+     */
+    taglineKey: string;
+    /** English fallback for taglineKey */
+    taglineEn: string;
+    /** Emoji representing the goal — universal, not translated */
+    emoji: string;
+    /**
+     * Goal category — used to group goals on the selection screen.
+     * Category label itself is also translated via categoryKey.
+     */
+    category: "appearance" | "performance" | "health" | "focused";
+};
+export declare const GOAL_DISPLAY: Record<TUserFitnessGoal, TGoalDisplay>;
+export type TGoalCategory = TGoalDisplay["category"];
+export type TGoalCategoryDisplay = {
+    labelKey: string;
+    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 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.
+ *
+ * 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, 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";
+export type TWeeklyIntentTemplate = [
+    TSessionIntent,
+    TSessionIntent,
+    TSessionIntent,
+    TSessionIntent,
+    TSessionIntent,
+    TSessionIntent,
+    TSessionIntent
+];
+export type TGoalPhaseHints = Record<TTrainingPhase, string>;
+export declare const GOAL_PHASE_HINTS: Record<TUserFitnessGoal, TGoalPhaseHints>;

package/dist/types/goalFeature/goalJourney.js

@@ -0,0 +1,595 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+    "lose_weight",
+    "build_muscle",
+    "lean_and_toned",
+    "glutes_and_legs",
+    // Performance
+    "get_stronger",
+    "boost_endurance",
+    "athletic_performance",
+    // Health
+    "general_fitness",
+    "posture_and_back",
+    "stress_relief",
+    "rehabilitation",
+    // Focused
+    "core_strength",
+    "mobility_flexibility",
+];
+// The canonical weekly template per goal (7 slots, Mon→Sun)
+// Phase-aware structures live in the app layer, not shared
+// This is the "default" / Phase 2-3 reference structure
+exports.GOAL_SESSION_INTENTS = {
+    lose_weight: [
+        "cardio",
+        "full-body",
+        "rest",
+        "cardio",
+        "full-body",
+        "cardio",
+        "rest",
+    ],
+    build_muscle: ["push", "pull", "legs", "rest", "upper", "lower", "rest"],
+    lean_and_toned: [
+        "full-body",
+        "cardio",
+        "full-body",
+        "rest",
+        "full-body",
+        "cardio",
+        "rest",
+    ],
+    glutes_and_legs: ["legs", "upper", "legs", "rest", "legs", "cardio", "rest"],
+    get_stronger: ["push", "pull", "legs", "rest", "push", "pull", "rest"],
+    boost_endurance: [
+        "cardio",
+        "legs",
+        "cardio",
+        "upper",
+        "cardio",
+        "full-body",
+        "rest",
+    ],
+    athletic_performance: [
+        "legs",
+        "upper",
+        "cardio",
+        "core",
+        "full-body",
+        "rest",
+        "rest",
+    ],
+    general_fitness: [
+        "full-body",
+        "rest",
+        "full-body",
+        "cardio",
+        "full-body",
+        "rest",
+        "rest",
+    ],
+    posture_and_back: [
+        "pull",
+        "core",
+        "mobility",
+        "pull",
+        "core",
+        "mobility",
+        "rest",
+    ],
+    stress_relief: [
+        "cardio",
+        "mobility",
+        "full-body",
+        "rest",
+        "cardio",
+        "mobility",
+        "rest",
+    ],
+    rehabilitation: [
+        "mobility",
+        "core",
+        "mobility",
+        "rest",
+        "mobility",
+        "core",
+        "rest",
+    ],
+    core_strength: ["core", "pull", "legs", "core", "push", "rest", "rest"],
+    mobility_flexibility: [
+        "mobility",
+        "full-body",
+        "mobility",
+        "rest",
+        "mobility",
+        "full-body",
+        "rest",
+    ],
+};
+exports.GOAL_TO_AI_FITNESS_GOAL = {
+    lose_weight: "fat_loss",
+    build_muscle: "hypertrophy",
+    lean_and_toned: "fat_loss",
+    glutes_and_legs: "hypertrophy",
+    get_stronger: "strength",
+    boost_endurance: "endurance",
+    athletic_performance: "sport_performance",
+    general_fitness: "general_fitness",
+    posture_and_back: "strength",
+    stress_relief: "general_fitness",
+    rehabilitation: "rehabilitation",
+    core_strength: "core_strength",
+    mobility_flexibility: "mobility",
+};
+// Foundation → Momentum → Push → Peak
+exports.TRAINING_PHASES = [
+    "foundation",
+    "momentum",
+    "push",
+    "peak",
+];
+exports.PHASE_DISPLAY = {
+    foundation: {
+        nameKey: "goalPhase.foundation.name",
+        nameEn: "Foundation",
+        subtitleKey: "goalPhase.foundation.subtitle",
+        subtitleEn: "Build the base",
+        purposeKey: "goalPhase.foundation.purpose",
+        purposeEn: "Preparing your joints, learning movement patterns, and building the work capacity for what's ahead. Every great physique starts here — don't skip it.",
+        durationKey: "goalPhase.foundation.duration",
+        durationEn: "Weeks 1–2",
+        weekRange: [1, 2],
+        intensityPercent: 40,
+    },
+    momentum: {
+        nameKey: "goalPhase.momentum.name",
+        nameEn: "Momentum",
+        subtitleKey: "goalPhase.momentum.subtitle",
+        subtitleEn: "Volume builds here",
+        purposeKey: "goalPhase.momentum.purpose",
+        purposeEn: "Your body has adapted. Now we increase the work. Splits begin, sessions get more specific. This is where the habit locks in.",
+        durationKey: "goalPhase.momentum.duration",
+        durationEn: "Weeks 3–5",
+        weekRange: [3, 5],
+        intensityPercent: 60,
+    },
+    push: {
+        nameKey: "goalPhase.push.name",
+        nameEn: "Push",
+        subtitleKey: "goalPhase.push.subtitle",
+        subtitleEn: "This is where change happens",
+        purposeKey: "goalPhase.push.purpose",
+        purposeEn: "Goal-specific intensity. Your muscles are conditioned — now we challenge them. Expect to feel this one.",
+        durationKey: "goalPhase.push.duration",
+        durationEn: "Weeks 6–8",
+        weekRange: [6, 8],
+        intensityPercent: 80,
+    },
+    peak: {
+        nameKey: "goalPhase.peak.name",
+        nameEn: "Peak",
+        subtitleKey: "goalPhase.peak.subtitle",
+        subtitleEn: "Maximum output",
+        purposeKey: "goalPhase.peak.purpose",
+        purposeEn: "Highest specificity to your goal. You have earned this — now execute. A deload is built into the final week.",
+        durationKey: "goalPhase.peak.duration",
+        durationEn: "Weeks 9+",
+        weekRange: [9, 99],
+        intensityPercent: 95,
+    },
+};
+exports.INTENT_DISPLAY = {
+    push: {
+        labelKey: "sessionIntent.push.label",
+        labelEn: "Push Day",
+        shortLabelKey: "sessionIntent.push.shortLabel",
+        shortLabelEn: "Push",
+        emoji: "💪",
+    },
+    pull: {
+        labelKey: "sessionIntent.pull.label",
+        labelEn: "Pull Day",
+        shortLabelKey: "sessionIntent.pull.shortLabel",
+        shortLabelEn: "Pull",
+        emoji: "🔗",
+    },
+    legs: {
+        labelKey: "sessionIntent.legs.label",
+        labelEn: "Leg Day",
+        shortLabelKey: "sessionIntent.legs.shortLabel",
+        shortLabelEn: "Legs",
+        emoji: "🦵",
+    },
+    lower: {
+        labelKey: "sessionIntent.lower.label",
+        labelEn: "Lower Body",
+        shortLabelKey: "sessionIntent.lower.shortLabel",
+        shortLabelEn: "Lower",
+        emoji: "🦵",
+    },
+    upper: {
+        labelKey: "sessionIntent.upper.label",
+        labelEn: "Upper Body",
+        shortLabelKey: "sessionIntent.upper.shortLabel",
+        shortLabelEn: "Upper",
+        emoji: "💪",
+    },
+    core: {
+        labelKey: "sessionIntent.core.label",
+        labelEn: "Core & Abs",
+        shortLabelKey: "sessionIntent.core.shortLabel",
+        shortLabelEn: "Core",
+        emoji: "⚡",
+    },
+    cardio: {
+        labelKey: "sessionIntent.cardio.label",
+        labelEn: "Cardio",
+        shortLabelKey: "sessionIntent.cardio.shortLabel",
+        shortLabelEn: "Cardio",
+        emoji: "🏃",
+    },
+    strength: {
+        labelKey: "sessionIntent.strength.label",
+        labelEn: "Strength",
+        shortLabelKey: "sessionIntent.strength.shortLabel",
+        shortLabelEn: "Strength",
+        emoji: "🏋️",
+    },
+    fatburn: {
+        labelKey: "sessionIntent.fatburn.label",
+        labelEn: "Fat Burn",
+        shortLabelKey: "sessionIntent.fatburn.shortLabel",
+        shortLabelEn: "Burn",
+        emoji: "🔥",
+    },
+    mobility: {
+        labelKey: "sessionIntent.mobility.label",
+        labelEn: "Mobility",
+        shortLabelKey: "sessionIntent.mobility.shortLabel",
+        shortLabelEn: "Mobility",
+        emoji: "🧘",
+    },
+    "full-body": {
+        labelKey: "sessionIntent.fullBody.label",
+        labelEn: "Full Body",
+        shortLabelKey: "sessionIntent.fullBody.shortLabel",
+        shortLabelEn: "Full",
+        emoji: "⭐",
+    },
+    rest: {
+        labelKey: "sessionIntent.rest.label",
+        labelEn: "Rest Day",
+        shortLabelKey: "sessionIntent.rest.shortLabel",
+        shortLabelEn: "Rest",
+        emoji: "😴",
+    },
+};
+exports.GOAL_DISPLAY = {
+    // ── Appearance ────────────────────────────────────────────────────────────
+    lose_weight: {
+        nameKey: "userGoal.loseWeight.name",
+        nameEn: "Lose Weight",
+        descriptionKey: "userGoal.loseWeight.description",
+        descriptionEn: "Burn fat and drop weight through cardio and full-body training.",
+        taglineKey: "userGoal.loseWeight.tagline",
+        taglineEn: "Every session burns, every week counts.",
+        emoji: "🔥",
+        category: "appearance",
+    },
+    build_muscle: {
+        nameKey: "userGoal.buildMuscle.name",
+        nameEn: "Build Muscle",
+        descriptionKey: "userGoal.buildMuscle.description",
+        descriptionEn: "Add size and strength with structured push, pull, and leg splits.",
+        taglineKey: "userGoal.buildMuscle.tagline",
+        taglineEn: "Progressive overload. Every rep builds the next.",
+        emoji: "💪",
+        category: "appearance",
+    },
+    lean_and_toned: {
+        nameKey: "userGoal.leanAndToned.name",
+        nameEn: "Get Lean & Toned",
+        descriptionKey: "userGoal.leanAndToned.description",
+        descriptionEn: "Burn fat while preserving muscle for a lean, defined look.",
+        taglineKey: "userGoal.leanAndToned.tagline",
+        taglineEn: "Defined. Lean. Confident.",
+        emoji: "✨",
+        category: "appearance",
+    },
+    glutes_and_legs: {
+        nameKey: "userGoal.glutesAndLegs.name",
+        nameEn: "Grow Glutes & Legs",
+        descriptionKey: "userGoal.glutesAndLegs.description",
+        descriptionEn: "Build powerful glutes and legs with targeted lower-body training.",
+        taglineKey: "userGoal.glutesAndLegs.tagline",
+        taglineEn: "Strong legs carry everything.",
+        emoji: "🦵",
+        category: "appearance",
+    },
+    // ── Performance ───────────────────────────────────────────────────────────
+    get_stronger: {
+        nameKey: "userGoal.getStronger.name",
+        nameEn: "Get Stronger",
+        descriptionKey: "userGoal.getStronger.description",
+        descriptionEn: "Build real-world strength through compound lifts and progressive overload.",
+        taglineKey: "userGoal.getStronger.tagline",
+        taglineEn: "Lift more. Be more.",
+        emoji: "🏋️",
+        category: "performance",
+    },
+    boost_endurance: {
+        nameKey: "userGoal.boostEndurance.name",
+        nameEn: "Build Endurance",
+        descriptionKey: "userGoal.boostEndurance.description",
+        descriptionEn: "Increase stamina and cardiovascular capacity through progressive cardio and leg work.",
+        taglineKey: "userGoal.boostEndurance.tagline",
+        taglineEn: "Go further. Last longer.",
+        emoji: "🏃",
+        category: "performance",
+    },
+    athletic_performance: {
+        nameKey: "userGoal.athleticPerformance.name",
+        nameEn: "Athletic Performance",
+        descriptionKey: "userGoal.athleticPerformance.description",
+        descriptionEn: "Train like an athlete — explosive power, speed, agility, and conditioning.",
+        taglineKey: "userGoal.athleticPerformance.tagline",
+        taglineEn: "Train hard. Perform harder.",
+        emoji: "⚡",
+        category: "performance",
+    },
+    // ── Health ────────────────────────────────────────────────────────────────
+    general_fitness: {
+        nameKey: "userGoal.generalFitness.name",
+        nameEn: "Stay Active & Healthy",
+        descriptionKey: "userGoal.generalFitness.description",
+        descriptionEn: "A balanced mix of strength, cardio, and mobility for a healthy, active lifestyle.",
+        taglineKey: "userGoal.generalFitness.tagline",
+        taglineEn: "Move well. Feel well. Live well.",
+        emoji: "🌟",
+        category: "health",
+    },
+    posture_and_back: {
+        nameKey: "userGoal.postureAndBack.name",
+        nameEn: "Fix Posture & Back",
+        descriptionKey: "userGoal.postureAndBack.description",
+        descriptionEn: "Strengthen the posterior chain and core to fix posture and eliminate back pain.",
+        taglineKey: "userGoal.postureAndBack.tagline",
+        taglineEn: "Stand tall. Move pain-free.",
+        emoji: "🧍",
+        category: "health",
+    },
+    stress_relief: {
+        nameKey: "userGoal.stressRelief.name",
+        nameEn: "Reduce Stress",
+        descriptionKey: "userGoal.stressRelief.description",
+        descriptionEn: "Use movement to reset your mind — cardio endorphins and mobility to decompress.",
+        taglineKey: "userGoal.stressRelief.tagline",
+        taglineEn: "Move it out. Breathe it out.",
+        emoji: "🧘",
+        category: "health",
+    },
+    rehabilitation: {
+        nameKey: "userGoal.rehabilitation.name",
+        nameEn: "Recover from Injury",
+        descriptionKey: "userGoal.rehabilitation.description",
+        descriptionEn: "Gentle, progressive sessions to rebuild strength and movement after injury.",
+        taglineKey: "userGoal.rehabilitation.tagline",
+        taglineEn: "Slow and steady. Built to last.",
+        emoji: "🩹",
+        category: "health",
+    },
+    // ── Focused ───────────────────────────────────────────────────────────────
+    core_strength: {
+        nameKey: "userGoal.coreStrength.name",
+        nameEn: "Build a Strong Core",
+        descriptionKey: "userGoal.coreStrength.description",
+        descriptionEn: "Develop deep core stability and strength — the foundation of every movement.",
+        taglineKey: "userGoal.coreStrength.tagline",
+        taglineEn: "Strong core. Strong everything.",
+        emoji: "🎯",
+        category: "focused",
+    },
+    mobility_flexibility: {
+        nameKey: "userGoal.mobilityFlexibility.name",
+        nameEn: "Improve Flexibility",
+        descriptionKey: "userGoal.mobilityFlexibility.description",
+        descriptionEn: "Increase range of motion and joint health through consistent mobility work.",
+        taglineKey: "userGoal.mobilityFlexibility.tagline",
+        taglineEn: "Move freely. Age well.",
+        emoji: "🌀",
+        category: "focused",
+    },
+};
+exports.GOAL_CATEGORY_DISPLAY = {
+    appearance: {
+        labelKey: "goalCategory.appearance.label",
+        labelEn: "Appearance",
+    },
+    performance: {
+        labelKey: "goalCategory.performance.label",
+        labelEn: "Performance",
+    },
+    health: {
+        labelKey: "goalCategory.health.label",
+        labelEn: "Health & Wellbeing",
+    },
+    focused: {
+        labelKey: "goalCategory.focused.label",
+        labelEn: "Focused Training",
+    },
+};
+// ---------------------------------------------------------------------------
+// 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 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.
+ *
+ * On goal start day (no sessions yet), pass:
+ *   totalSessions = PHASE_ENTRY_CREDIT[user.fitnessLevel]
+ *   sessionsInLast4Weeks = RECENCY_CREDIT[user.fitnessLevel]
+ */
+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/types/goalFeature/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./goalJourney";
+export type * from "./TApiGoalContextRes";
+export * from "./utilGoal";

package/dist/types/goalFeature/index.js

@@ -0,0 +1,19 @@
+"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 });
+// shared/src/types/goalFeature/index.ts
+__exportStar(require("./goalJourney"), exports);
+__exportStar(require("./utilGoal"), exports);

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

@@ -0,0 +1,22 @@
+import { TMuscleFatigueResult } from "../../utils";
+import { TSessionIntent } from "./goalJourney";
+import { TGoalContext, TGoalProfile, TIntentRecommendation } from "./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/types/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("./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/types/index.d.ts

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

package/dist/types/index.js

@@ -1,2 +1,18 @@
 "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/scoringWorkout/helpers.d.ts

@@ -1,18 +1,4 @@
-/**
- * ============================================================================
- * FITFRIX EXERCISE SCORING SYSTEM — Helpers
- * ============================================================================
- *
- * Pure utility functions with no business logic. These handle:
- * - Safe parsing of string values from TRecord
- * - Duration parsing ("MM:SS" → seconds)
- * - Clamping and validation
- * - Effort fraction conversion (RPE/RIR → 0–1)
- * - User context extraction with fallbacks
- *
- * All functions are deterministic and side-effect free.
- */
-import { TGender } from "../../types";
+import { TActivityLevel, TGender } from "../../types";
 import type { IUserContext } from "./types";
 /**
  * Safely parse a string to a float.
@@ -112,12 +98,11 @@ export declare function getEffortFraction(record: {
  * @param user - The raw TUserMetric object
  */
 export declare function extractUserContext(user: {
-    weightKg?: number;
-    heightCm?: number;
-    gender?: TGender;
-    dob?: Date | string;
-    fitnessLevel?: import("../../types").TActivityLevel;
-    fitnessGoals?: import("../../constants/AiExerciseVocabulary").TAiFitnessGoal[];
+    weightKg: number;
+    heightCm: number;
+    gender: TGender;
+    dob: Date | string;
+    fitnessLevel: TActivityLevel;
     bodyFatPercentage?: number;
 }): IUserContext;
 /**

package/dist/utils/scoringWorkout/helpers.js

@@ -199,7 +199,7 @@ function getEffortFraction(record) {
  * @param user - The raw TUserMetric object
  */
 function extractUserContext(user) {
-    var _a, _b, _c;
+    var _a, _b;
     const weightKg = user.weightKg && user.weightKg > 20 && user.weightKg < 300
         ? user.weightKg
         : constants_1.DEFAULT_USER_WEIGHT_KG;
@@ -213,8 +213,7 @@ function extractUserContext(user) {
         gender: user.gender || "unmentioned",
         age,
         fitnessLevel: (_a = user.fitnessLevel) !== null && _a !== void 0 ? _a : "moderately-active",
-        fitnessGoals: (_b = user.fitnessGoals) !== null && _b !== void 0 ? _b : ["general_fitness"],
-        bodyFatPercentage: (_c = user.bodyFatPercentage) !== null && _c !== void 0 ? _c : 20,
+        bodyFatPercentage: (_b = user.bodyFatPercentage) !== null && _b !== void 0 ? _b : 20,
     };
 }
 /**

package/dist/utils/scoringWorkout/index.js

@@ -39,7 +39,6 @@ const calculateExerciseScoreV2 = (param) => {
     const { exercise, record, user, historicalContext } = param;
     const userContext = (0, helpers_1.extractUserContext)(user);
     const parsedSets = (0, parseRecords_1.parseRecords)(record, exercise.timingGuardrails, historicalContext);
-    // ── Pillar 2: Muscle Fatigue ─────────────────────────────────────────────
     const muscleScores = (0, calculateMuscleFatigue_1.calculateMuscleFatigue)(parsedSets, {
         primaryMuscles: exercise.primaryMuscles,
         secondaryMuscles: exercise.secondaryMuscles,
@@ -51,11 +50,9 @@ const calculateExerciseScoreV2 = (param) => {
         scoringSpecialHandling: exercise.scoringSpecialHandling,
         isUnilateral: exercise.isUnilateral,
     }, userContext, exercise.timingGuardrails, historicalContext);
-    // ── Pillar 3: Quality Score ──────────────────────────────────────────────
     // userContext is intentionally not passed — quality scoring is goal-agnostic.
     // Goal-specific logic lives in the gate system and quick plan generator.
     const { score, qualityBreakdown, restDisciplineActive } = (0, calculateQualityScore_1.calculateQualityScore)(parsedSets, record, exercise.timingGuardrails, historicalContext);
-    // ── Result (Option A flat shape) ─────────────────────────────────────────
     return {
         score,
         qualityBreakdown,

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

@@ -8,7 +8,6 @@
  * scoring pillars (Calories, Muscle Fatigue, Quality).
  */
 import { TActivityLevel, TGender, TRecord } from "../../types";
-import type { TAiFitnessGoal } from "../../constants/AiExerciseVocabulary";
 /**
  * A single scored session with real per-muscle fatigue values.
  * muscleScores = {} for pre-P3-1 sessions (backward compat fallback).
@@ -141,6 +140,5 @@ export interface IUserContext {
     gender: TGender;
     age: number;
     fitnessLevel: TActivityLevel;
-    fitnessGoals: TAiFitnessGoal[];
     bodyFatPercentage: number;
 }

package/package.json

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