@dgpholdings/greatoak-shared 1.2.86 → 1.2.87

package/README.md

@@ -1,149 +1,149 @@
-# @dgpholdings/greatoak-shared
-
-The shared library for the Fitfrix ecosystem. Contains all types, utilities, and the scoring engine used across:
-
-- `v2/fitfrix` — the mobile app (React Native / Expo)
-- `backend/api-service` — the NestJS backend
-- `fitfrix.com` — the web/landing (Vite + React)
-
-Any type, constant, or utility that is used by more than one package lives here. If you're about to define a type locally in a consuming app — check here first.
-
----
-
-## Install / Import
-
-```ts
-// Types
-import type { TExercise, TRecord, TUserMetric } from '@dgpholdings/greatoak-shared';
-
-// Utils
-import { calculateExerciseScoreV2, calculateTotalVolume, isDefined, toError } from '@dgpholdings/greatoak-shared';
-```
-
----
-
-## What's Inside
-
-| Category | Location | Doc |
-|---|---|---|
-| **Types** | `src/types/` | [docs/types.md](docs/types.md) |
-| **Utils** | `src/utils/` | [docs/utils.md](docs/utils.md) |
-| **Scoring Engine** | `src/utils/scoring/` | [docs/scoring.md](docs/scoring.md) |
-
----
-
-## Types — Quick Reference
-
-| File | What it defines |
-|---|---|
-| `commonTypes.ts` | `TRecord`, `TExerciseConfig`, `TTemplateExercise`, `TGdprData`, `TDayKey` |
-| `TApiExercise.ts` | `TExercise`, `TBodyPart`, `EBodyParts`, `TTrainingType`, `TTimingGuardrails` |
-| `TApiUser.ts` | `TUserMetric`, `TFitnessGoal`, `TUserType`, `TSubscriptionStatus`, `TGender` |
-| `TApiAuth.ts` | Signup/signin request & response types (`TApiSignupAnonymousReq`, `TSignInRes`, etc.) |
-| `TApiExerciseRecord.ts` | Record save/fetch request & response types |
-| `TApiTemplateData.ts` | `TTemplate`, `TTemplateDb`, `TTemplateData`, `TExerciseLatestRecord` |
-| `TApiProPlan.ts` | `TProPlan`, pro plan CRUD request & response types |
-| `TApiTemplateShop.ts` | `TTemplateShopDb`, shop CRUD & shared plan types |
-| `TApiBillingPlan.ts` | `TBillingPlan`, `TBillingCountries`, billing API types |
-| `TApiRevenueCat.ts` | `TApiRevenueCatWebhookReq`, RevenueCat event types |
-| `TApiClientProgress.ts` | `TClientWorkoutHistory`, trainer dashboard types |
-
----
-
-## Utils — Quick Reference
-
-| Export | What it does |
-|---|---|
-| `calculateExerciseScoreV2` | Full exercise scoring → `{ score, muscleScores }` |
-| `calculateTotalVolume` | Total workout volume for charts |
-| `isDefined` / `isDefinedNumber` | Null/undefined type guards |
-| `toError` | Converts unknown catch values to `Error` |
-| `toNumber` | Safe string/number → `number \| undefined` |
-| `mmssToSecs` | `"MM:SS"` → seconds |
-| `getDaysAndHoursDifference` | Date diff → `{ days, hours }` |
-| `isUserAllowedToUpdate` | Profile update rate-limit guard |
-| `countryToCurrencyCode` | Country code → ISO currency string |
-| `slugifyText` | Text → URL-safe slug |
-| `generatePlanCode` | Generates a unique 9-char Crockford Base32 plan code |
-| `maskEmail` / `isEmail` / `isAnonymousEmail` | Email utilities |
-| `NOOP` | Empty function `() => {}` |
-
----
-
-## Source Structure
-
-```
-shared/
-├── src/
-│   ├── types/
-│   │   ├── index.ts               # Re-exports all types
-│   │   ├── commonTypes.ts         # TRecord, TExerciseConfig, TTemplateExercise, TGdprData, TDayKey
-│   │   ├── TApiExercise.ts        # TExercise and related
-│   │   ├── TApiUser.ts            # TUserMetric and related
-│   │   ├── TApiAuth.ts            # Auth flows
-│   │   ├── TApiExerciseRecord.ts  # Workout record save/fetch
-│   │   ├── TApiTemplateData.ts    # User workout templates
-│   │   ├── TApiProPlan.ts         # Pro/trainer plans
-│   │   ├── TApiTemplateShop.ts    # Template shop (legacy, see TApiProPlan)
-│   │   ├── TApiBillingPlan.ts     # Billing plans
-│   │   ├── TApiRevenueCat.ts      # In-app purchase webhooks
-│   │   └── TApiClientProgress.ts  # Trainer client tracking
-│   └── utils/
-│       ├── index.ts               # Re-exports all utils
-│       ├── billing.utils.ts
-│       ├── email.utils.ts
-│       ├── isDefined.utils.ts
-│       ├── noop.utils.ts
-│       ├── number.util.ts
-│       ├── planCode.util.ts
-│       ├── slugify.util.ts
-│       ├── time.util.ts
-│       ├── toError.util.ts
-│       └── scoring/               # Exercise scoring engine
-│           └── README.md          # Full scoring documentation
-├── docs/
-│   ├── types.md                   # All types documented in detail
-│   ├── utils.md                   # All utils documented with examples
-│   └── scoring.md                 # Scoring system overview
-└── README.md                      # This file
-```
-
----
-
-## Key Design Rules
-
-- **No local duplication** — if a type or utility is needed by ≥2 packages, it belongs here
-- **No framework code** — this package must stay framework-agnostic (no React, no NestJS decorators)
-- **Strict types** — no `any`. Use generics, discriminated unions, or `unknown`
-- **Scoring is the business core** — the scoring engine drives the muscle fatigue diagram and progress charts. Read [docs/scoring.md](docs/scoring.md) before touching it
-
-
-## Renewing token 
-
-1. Login using the token (recommended way)
-
-In your Git Bash, run:
-
-`npm login`
-
-It will prompt:
-
-Username:
-Password:
-Email:
-
-Use this:
-
-Username → your npm username
-
-Password → paste the granular token (NOT your npm password)
-
-Email → your npm email
-
-After that, npm stores the token in:
-
-`shared\.npmrc`
-
-Then publishing works normally:
-
+# @dgpholdings/greatoak-shared
+
+The shared library for the Fitfrix ecosystem. Contains all types, utilities, and the scoring engine used across:
+
+- `v2/fitfrix` — the mobile app (React Native / Expo)
+- `backend/api-service` — the NestJS backend
+- `fitfrix.com` — the web/landing (Vite + React)
+
+Any type, constant, or utility that is used by more than one package lives here. If you're about to define a type locally in a consuming app — check here first.
+
+---
+
+## Install / Import
+
+```ts
+// Types
+import type { TExercise, TRecord, TUserMetric } from '@dgpholdings/greatoak-shared';
+
+// Utils
+import { calculateExerciseScoreV2, calculateTotalVolume, isDefined, toError } from '@dgpholdings/greatoak-shared';
+```
+
+---
+
+## What's Inside
+
+| Category | Location | Doc |
+|---|---|---|
+| **Types** | `src/types/` | [docs/types.md](docs/types.md) |
+| **Utils** | `src/utils/` | [docs/utils.md](docs/utils.md) |
+| **Scoring Engine** | `src/utils/scoring/` | [docs/scoring.md](docs/scoring.md) |
+
+---
+
+## Types — Quick Reference
+
+| File | What it defines |
+|---|---|
+| `commonTypes.ts` | `TRecord`, `TExerciseConfig`, `TTemplateExercise`, `TGdprData`, `TDayKey` |
+| `TApiExercise.ts` | `TExercise`, `TBodyPart`, `EBodyParts`, `TTrainingType`, `TTimingGuardrails` |
+| `TApiUser.ts` | `TUserMetric`, `TFitnessGoal`, `TUserType`, `TSubscriptionStatus`, `TGender` |
+| `TApiAuth.ts` | Signup/signin request & response types (`TApiSignupAnonymousReq`, `TSignInRes`, etc.) |
+| `TApiExerciseRecord.ts` | Record save/fetch request & response types |
+| `TApiTemplateData.ts` | `TTemplate`, `TTemplateDb`, `TTemplateData`, `TExerciseLatestRecord` |
+| `TApiProPlan.ts` | `TProPlan`, pro plan CRUD request & response types |
+| `TApiTemplateShop.ts` | `TTemplateShopDb`, shop CRUD & shared plan types |
+| `TApiBillingPlan.ts` | `TBillingPlan`, `TBillingCountries`, billing API types |
+| `TApiRevenueCat.ts` | `TApiRevenueCatWebhookReq`, RevenueCat event types |
+| `TApiClientProgress.ts` | `TClientWorkoutHistory`, trainer dashboard types |
+
+---
+
+## Utils — Quick Reference
+
+| Export | What it does |
+|---|---|
+| `calculateExerciseScoreV2` | Full exercise scoring → `{ score, muscleScores }` |
+| `calculateTotalVolume` | Total workout volume for charts |
+| `isDefined` / `isDefinedNumber` | Null/undefined type guards |
+| `toError` | Converts unknown catch values to `Error` |
+| `toNumber` | Safe string/number → `number \| undefined` |
+| `mmssToSecs` | `"MM:SS"` → seconds |
+| `getDaysAndHoursDifference` | Date diff → `{ days, hours }` |
+| `isUserAllowedToUpdate` | Profile update rate-limit guard |
+| `countryToCurrencyCode` | Country code → ISO currency string |
+| `slugifyText` | Text → URL-safe slug |
+| `generatePlanCode` | Generates a unique 9-char Crockford Base32 plan code |
+| `maskEmail` / `isEmail` / `isAnonymousEmail` | Email utilities |
+| `NOOP` | Empty function `() => {}` |
+
+---
+
+## Source Structure
+
+```
+shared/
+├── src/
+│   ├── types/
+│   │   ├── index.ts               # Re-exports all types
+│   │   ├── commonTypes.ts         # TRecord, TExerciseConfig, TTemplateExercise, TGdprData, TDayKey
+│   │   ├── TApiExercise.ts        # TExercise and related
+│   │   ├── TApiUser.ts            # TUserMetric and related
+│   │   ├── TApiAuth.ts            # Auth flows
+│   │   ├── TApiExerciseRecord.ts  # Workout record save/fetch
+│   │   ├── TApiTemplateData.ts    # User workout templates
+│   │   ├── TApiProPlan.ts         # Pro/trainer plans
+│   │   ├── TApiTemplateShop.ts    # Template shop (legacy, see TApiProPlan)
+│   │   ├── TApiBillingPlan.ts     # Billing plans
+│   │   ├── TApiRevenueCat.ts      # In-app purchase webhooks
+│   │   └── TApiClientProgress.ts  # Trainer client tracking
+│   └── utils/
+│       ├── index.ts               # Re-exports all utils
+│       ├── billing.utils.ts
+│       ├── email.utils.ts
+│       ├── isDefined.utils.ts
+│       ├── noop.utils.ts
+│       ├── number.util.ts
+│       ├── planCode.util.ts
+│       ├── slugify.util.ts
+│       ├── time.util.ts
+│       ├── toError.util.ts
+│       └── scoring/               # Exercise scoring engine
+│           └── README.md          # Full scoring documentation
+├── docs/
+│   ├── types.md                   # All types documented in detail
+│   ├── utils.md                   # All utils documented with examples
+│   └── scoring.md                 # Scoring system overview
+└── README.md                      # This file
+```
+
+---
+
+## Key Design Rules
+
+- **No local duplication** — if a type or utility is needed by ≥2 packages, it belongs here
+- **No framework code** — this package must stay framework-agnostic (no React, no NestJS decorators)
+- **Strict types** — no `any`. Use generics, discriminated unions, or `unknown`
+- **Scoring is the business core** — the scoring engine drives the muscle fatigue diagram and progress charts. Read [docs/scoring.md](docs/scoring.md) before touching it
+
+
+## Renewing token 
+
+1. Login using the token (recommended way)
+
+In your Git Bash, run:
+
+`npm login`
+
+It will prompt:
+
+Username:
+Password:
+Email:
+
+Use this:
+
+Username → your npm username
+
+Password → paste the granular token (NOT your npm password)
+
+Email → your npm email
+
+After that, npm stores the token in:
+
+`shared\.npmrc`
+
+Then publishing works normally:
+
 `npm publish`

package/dist/__mocks__/exercises.mock.js

@@ -5,6 +5,7 @@ exports.mockExercisesDictionary = exports.mockExerciseNoGuardrails = exports.moc
  * MOCK EXERCISE: Weight-Reps
  * Simulates a standard compound lift (e.g., Barbell Squat).
  */
+// @ts-ignore
 exports.mockExerciseWeightReps = {
     exerciseId: "mock-exercise-weight-reps-123",
     name: "Generic Barbell Squat",

package/dist/types/TApiAiExerciseAnalysis.d.ts

@@ -1,3 +1,4 @@
+import { TAiMovementPattern } from "../constants";
 export type TConfidence = "high" | "medium" | null;
 export type TNameReviewStatus = "pending" | "approved";
 export type TQdrantSyncStatus = "pending" | "synced" | "failed";
@@ -66,7 +67,7 @@ export type TApiAiExerciseAnalysis = {
     exercise_name: string;
     alternative_names: string[];
     movement_description: string;
-    movement_pattern: string;
+    movement_pattern: TAiMovementPattern;
     exercise_type: string;
     contraction_type: string;
     plane_of_motion: string[];

package/dist/types/TApiClientConstellation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ============================================================================
+ * API CONTRACT — Client Constellation
+ * ============================================================================
+ *
+ * Request/response types for GET /api/constellation. The response is the
+ * render-ready TConstellationState produced by the constellation util; these
+ * types are re-exported here so the backend (and app) consume one stable
+ * contract from the published package.
+ */
+import type { TConstellationState } from "../utils/constellation/types";
+export type { TConstellationState };
+/**
+ * Request: no body. The user is resolved from the JWT. `level` is optional and
+ * may be supplied as a query param to preview a specific level; it defaults to
+ * the user's current level (1) and is clamped to a valid level server-side.
+ */
+export type TApiClientConstellationReq = {
+    level?: number;
+};
+/**
+ * Response envelope, matching the shape your other controllers return
+ * (status + state + message) with the constellation payload under `data`.
+ */
+export type TApiClientConstellationRes = {
+    status: 200;
+    state: "success";
+    data: TConstellationState;
+} | {
+    status: 401 | 500;
+    state: "failed";
+    message: string;
+};

package/dist/types/TApiClientConstellation.js

@@ -0,0 +1,13 @@
+"use strict";
+// shared/src/types/TApiClientConstellation.ts
+/**
+ * ============================================================================
+ * API CONTRACT — Client Constellation
+ * ============================================================================
+ *
+ * Request/response types for GET /api/constellation. The response is the
+ * render-ready TConstellationState produced by the constellation util; these
+ * types are re-exported here so the backend (and app) consume one stable
+ * contract from the published package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/TApiExercise.d.ts

@@ -1,3 +1,4 @@
+import { TAiMovementPattern } from "../constants";
 import { TRecord } from "./commonTypes";
 export type TBodyPart = "Chest" | "Core" | "Shoulders" | "Back" | "Biceps" | "Triceps" | "Forearms" | "Legs" | "Glutes" | "Calves" | "Hamstrings" | "Quadriceps" | "Lower Back" | "Trapezius";
 export declare enum EBodyParts {
@@ -141,9 +142,10 @@ export type TExercise = {
         female: number;
         default: number;
     };
-    movementPattern?: "push" | "pull" | "hinge" | "squat" | "lunge" | "rotation" | "carry" | "isolation";
-    stabilityDemand?: "low" | "moderate" | "high";
-    progressionTier?: "beginner" | "intermediate" | "advanced" | "elite";
+    movementPattern: TAiMovementPattern;
+    exerciseType: "isolation" | "compound" | "bodyweight" | "mobility" | "plyometric" | "isometric" | "cardio";
+    stabilityDemand: "low" | "moderate" | "high";
+    progressionTier: "beginner" | "intermediate" | "advanced" | "elite";
 };
 export type TBodyPartExercises = Record<TBodyPart, TExercise[]>;
 export type TApiCreateOrUpdateExerciseReq = {

package/dist/types/index.d.ts

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

package/dist/utils/constellation/computeNormalisedLoad.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Normalised Load (strength-star helper)
+ * ============================================================================
+ *
+ * Turns a user's sessions into a single strength number for a movement pattern:
+ * the best estimated-1RM achieved on any matching exercise in the rolling
+ * window, expressed as a ratio of bodyweight.
+ *
+ * Estimated-1RM (Epley, rep-capped at 12) is used instead of raw top weight so
+ * that 60kg x5 ~ 70kg x1 — it rewards productive training over ego-lifting.
+ *
+ * Bodyweight loading (the home-user path): a bodyweight exercise's effective
+ * load is the REAL fraction of bodyweight it moves, taken from the exercise's
+ * own `weightMultiplier` (per-sex), falling back to a coarse map keyed off
+ * `bodyweightDependency`. This is what lets a home user honestly reach a
+ * strength threshold with pull-ups / pistol squats etc., instead of being
+ * capped by a flat guess.
+ *
+ * Returns a bodyweight ratio (e.g. 0.78 = "0.78x bodyweight"). 0 = no data.
+ */
+import type { TExercise } from "../../types";
+import type { TSessionRecord } from "./types";
+/** Epley reps cap: reps beyond this don't increase the 1RM estimate. */
+export declare const EPLEY_REP_CAP = 12;
+/** Estimated 1RM via Epley, with reps capped to avoid endurance-range inflation. */
+export declare function estimateOneRepMax(weightKg: number, reps: number): number;
+export interface INormalisedLoadResult {
+    /** Best estimated-1RM in the window as a ratio of bodyweight. 0 if none. */
+    ratio: number;
+    /** The raw best estimated-1RM in kg (pre-normalisation), for detail display. */
+    bestOneRepMaxKg: number;
+    /** Exercise id that produced the best load (for "your best: Bench Press"). */
+    bestExerciseId?: string;
+}
+/**
+ * Compute the best normalised load for a set of matching exercises within the
+ * window.
+ *
+ * @param matchingExerciseIds  Exercise ids belonging to the target pattern.
+ * @param sessions             All sessions.
+ * @param exerciseCatalog      Full catalog (unfiltered).
+ * @param bodyweightKg         User bodyweight (falls back to default).
+ * @param gender               User sex (selects the weightMultiplier column).
+ * @param windowStartMs        Only sessions on/after this count.
+ * @param now                  Upper bound (sessions after `now` ignored).
+ */
+export declare function computeNormalisedLoad(matchingExerciseIds: Set<string>, sessions: TSessionRecord[], exerciseCatalog: Record<string, TExercise>, bodyweightKg: number, gender: string | undefined, windowStartMs: number, now: number): INormalisedLoadResult;

package/dist/utils/constellation/computeNormalisedLoad.js

@@ -0,0 +1,150 @@
+"use strict";
+// utils/constellation/computeNormalisedLoad.ts — Normalised Load (strength-star helper)
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Normalised Load (strength-star helper)
+ * ============================================================================
+ *
+ * Turns a user's sessions into a single strength number for a movement pattern:
+ * the best estimated-1RM achieved on any matching exercise in the rolling
+ * window, expressed as a ratio of bodyweight.
+ *
+ * Estimated-1RM (Epley, rep-capped at 12) is used instead of raw top weight so
+ * that 60kg x5 ~ 70kg x1 — it rewards productive training over ego-lifting.
+ *
+ * Bodyweight loading (the home-user path): a bodyweight exercise's effective
+ * load is the REAL fraction of bodyweight it moves, taken from the exercise's
+ * own `weightMultiplier` (per-sex), falling back to a coarse map keyed off
+ * `bodyweightDependency`. This is what lets a home user honestly reach a
+ * strength threshold with pull-ups / pistol squats etc., instead of being
+ * capped by a flat guess.
+ *
+ * Returns a bodyweight ratio (e.g. 0.78 = "0.78x bodyweight"). 0 = no data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EPLEY_REP_CAP = void 0;
+exports.estimateOneRepMax = estimateOneRepMax;
+exports.computeNormalisedLoad = computeNormalisedLoad;
+// --- Tunables -------------------------------------------------------------
+/** Epley reps cap: reps beyond this don't increase the 1RM estimate. */
+exports.EPLEY_REP_CAP = 12;
+/** Default bodyweight when the user profile lacks one. */
+const DEFAULT_BODYWEIGHT_KG = 70;
+/**
+ * Fallback bodyweight-load fractions when an exercise has no `weightMultiplier`.
+ * Keyed off `bodyweightDependency`: how much of your own body the move loads.
+ *   high   ~ pull-ups, dips, pistols   (most of bodyweight)
+ *   medium ~ lunges, inverted rows      (about half)
+ *   low    ~ braced cable work          (little)
+ *   none   ~ machine/bar carries the load — bodyweight isn't the resistance
+ */
+const BW_DEPENDENCY_FRACTION = {
+    high: 0.9,
+    medium: 0.6,
+    low: 0.3,
+    none: 0,
+};
+// --- Epley -----------------------------------------------------------------
+/**
+ * Parse a numeric string from a record, guarding against NaN and negatives.
+ * parseFloat("abc") is NaN; a logged weight/reps should never be negative.
+ */
+function safeParseFloat(value, fallback = 0) {
+    const parsed = parseFloat(value !== null && value !== void 0 ? value : "");
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+/** Estimated 1RM via Epley, with reps capped to avoid endurance-range inflation. */
+function estimateOneRepMax(weightKg, reps) {
+    if (weightKg <= 0 || reps <= 0)
+        return 0;
+    const cappedReps = Math.min(reps, exports.EPLEY_REP_CAP);
+    return weightKg * (1 + cappedReps / 30);
+}
+// --- Bodyweight load fraction ----------------------------------------------
+/**
+ * The fraction of bodyweight a bodyweight/reps-only exercise loads onto the
+ * target muscles. Prefers the exercise's own per-sex `weightMultiplier`; falls
+ * back to the `bodyweightDependency` map; final fallback is a mild 0.5.
+ */
+function bodyweightLoadFraction(exercise, gender) {
+    const wm = exercise.weightMultiplier;
+    if (wm) {
+        if (gender === "female")
+            return wm.female;
+        if (gender === "male")
+            return wm.male;
+        return wm.default;
+    }
+    const dep = exercise.bodyweightDependency;
+    if (dep && dep in BW_DEPENDENCY_FRACTION)
+        return BW_DEPENDENCY_FRACTION[dep];
+    return 0.5;
+}
+// --- Per-set effective load ------------------------------------------------
+/**
+ * Best estimated-1RM contribution of a single completed set, in kg.
+ * Switches on the TRecord discriminated union (no casts). Non-strength record
+ * types (duration, cardio) contribute 0.
+ */
+function setEstimatedLoadKg(set, exercise, bodyweightKg, gender) {
+    if (!set.isDone)
+        return 0;
+    if (set.type === "weight-reps") {
+        const kg = safeParseFloat(set.kg);
+        const reps = safeParseFloat(set.reps);
+        // Unilateral: weight is logged per side -> double for total mechanical load.
+        const totalKg = kg * (exercise.isUnilateral ? 2 : 1);
+        return estimateOneRepMax(totalKg, reps);
+    }
+    if (set.type === "reps-only") {
+        const reps = safeParseFloat(set.reps);
+        const auxKg = safeParseFloat(set.auxWeightKg);
+        const fraction = bodyweightLoadFraction(exercise, gender);
+        const bodyweightLoad = fraction * bodyweightKg;
+        // Added weight (weighted pull-ups/dips) stacks on the bodyweight load.
+        const effectiveWeight = bodyweightLoad + auxKg;
+        return estimateOneRepMax(effectiveWeight, reps);
+    }
+    // duration / cardio-machine / cardio-free are not strength loads.
+    return 0;
+}
+/**
+ * Compute the best normalised load for a set of matching exercises within the
+ * window.
+ *
+ * @param matchingExerciseIds  Exercise ids belonging to the target pattern.
+ * @param sessions             All sessions.
+ * @param exerciseCatalog      Full catalog (unfiltered).
+ * @param bodyweightKg         User bodyweight (falls back to default).
+ * @param gender               User sex (selects the weightMultiplier column).
+ * @param windowStartMs        Only sessions on/after this count.
+ * @param now                  Upper bound (sessions after `now` ignored).
+ */
+function computeNormalisedLoad(matchingExerciseIds, sessions, exerciseCatalog, bodyweightKg, gender, windowStartMs, now) {
+    const bw = bodyweightKg > 0 ? bodyweightKg : DEFAULT_BODYWEIGHT_KG;
+    let bestKg = 0;
+    let bestExerciseId;
+    for (const session of sessions) {
+        if (session.date < windowStartMs || session.date > now)
+            continue;
+        for (const ex of session.exercises) {
+            if (!matchingExerciseIds.has(ex.exerciseId))
+                continue;
+            const exercise = exerciseCatalog[ex.exerciseId];
+            if (!exercise)
+                continue;
+            for (const set of ex.records) {
+                const loadKg = setEstimatedLoadKg(set, exercise, bw, gender);
+                if (loadKg > bestKg) {
+                    bestKg = loadKg;
+                    bestExerciseId = ex.exerciseId;
+                }
+            }
+        }
+    }
+    return {
+        ratio: bestKg / bw,
+        bestOneRepMaxKg: bestKg,
+        bestExerciseId,
+    };
+}

package/dist/utils/constellation/evaluateConstellation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Orchestrator
+ * ============================================================================
+ *
+ * The single entry point. Takes raw input (sessions, catalog, user, now) and
+ * returns a render-ready TConstellationState: six resolved stars plus the
+ * figure aggregate that drives the silhouette's aura.
+ *
+ * Purely live — everything is recomputed from raw records on every call.
+ * Nothing is persisted; the same input always yields the same output.
+ *
+ * Scoring happens ONCE here: every (session, exercise) is scored a single time
+ * into scoredSessions, which both quality and recovery read — no double work.
+ *
+ * Runs server-side (Lambda) so the evaluation logic can evolve independently of
+ * app releases.
+ */
+import type { TConstellationInput, TConstellationState } from "./types";
+/**
+ * Evaluate the full constellation from raw input.
+ *
+ * @param input  sessions + exercise catalog (UNFILTERED) + user + now + level
+ * @returns      render-ready state: six stars + figure aggregate
+ * @throws       if `now` is not a finite timestamp
+ */
+export declare function evaluateConstellation(input: TConstellationInput): TConstellationState;