@dgpholdings/greatoak-shared 1.2.86 → 1.2.88

package/dist/utils/adoptionEngine/scaleProPlan.util.js

@@ -40,7 +40,7 @@ const getAdjustedBMIThreshold = (baseThreshold, activityLevel) => {
  * Reduces volume or duration by roughly 30%.
  */
 const applyFallbackScalingToRecord = (record) => {
-    const scaledRecord = Object.assign({}, record);
+    const scaledRecord = { ...record };
     const SCALE_FACTOR = 0.7;
     // Scale reps
     if (scaledRecord.type === "reps-only" || scaledRecord.type === "weight-reps") {
@@ -119,7 +119,7 @@ const scaleProPlan = (masterPlan, userMetric, exercisesDictionary) => {
                         newRecords = newRecords.map((record) => {
                             if (record.type === "weight-reps") {
                                 isModified = true;
-                                return Object.assign(Object.assign({}, record), { kg: suggestedLoadKg.toString() });
+                                return { ...record, kg: suggestedLoadKg.toString() };
                             }
                             // Guard against applying load to a falsy "0" aux weight
                             if (record.type === "reps-only" ||
@@ -128,7 +128,7 @@ const scaleProPlan = (masterPlan, userMetric, exercisesDictionary) => {
                                 const currentAux = parseFloat(record.auxWeightKg || "0");
                                 if (!isNaN(currentAux) && currentAux > 0) {
                                     isModified = true;
-                                    return Object.assign(Object.assign({}, record), { auxWeightKg: suggestedLoadKg.toString() });
+                                    return { ...record, auxWeightKg: suggestedLoadKg.toString() };
                                 }
                             }
                             return record;
@@ -136,7 +136,12 @@ const scaleProPlan = (masterPlan, userMetric, exercisesDictionary) => {
                     }
                 }
                 // Return the tailored template exercise
-                return Object.assign(Object.assign({}, templateExercise), { exerciseId: newExerciseId, initialRecords: newRecords, isAutoScaled: isModified || undefined });
+                return {
+                    ...templateExercise,
+                    exerciseId: newExerciseId,
+                    initialRecords: newRecords,
+                    isAutoScaled: isModified || undefined,
+                };
             });
         });
     });

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/computeNormalisedLoad.test.d.ts

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

package/dist/utils/constellation/computeNormalisedLoad.test.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/computeNormalisedLoad.test.ts
+const computeNormalisedLoad_1 = require("./computeNormalisedLoad");
+const vitest_1 = require("vitest");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+const wr = (kg, reps, isDone = true) => ({ type: "weight-reps", kg, reps, isDone, isStrictMode: false });
+const ro = (reps, auxWeightKg = "0", isDone = true) => ({
+    type: "reps-only",
+    reps,
+    auxWeightKg,
+    isDone,
+    isStrictMode: false,
+});
+const ex = (over) => ({
+    exerciseId: "e",
+    name: "E",
+    primaryMuscles: [],
+    secondaryMuscles: [],
+    difficultyLevel: 3,
+    movementPattern: "push_horizontal",
+    status: "active",
+    ...over,
+});
+(0, vitest_1.describe)("estimateOneRepMax — Epley with rep cap", () => {
+    (0, vitest_1.it)("60kg x5 ≈ 70kg", () => (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(60, 5)).toBeCloseTo(70, 1));
+    (0, vitest_1.it)("70kg x1 ≈ 72.33kg", () => (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(70, 1)).toBeCloseTo(72.33, 1));
+    (0, vitest_1.it)("reps capped at 12: 50x30 == 50x12", () => (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(50, 30)).toBe((0, computeNormalisedLoad_1.estimateOneRepMax)(50, computeNormalisedLoad_1.EPLEY_REP_CAP)));
+    (0, vitest_1.it)("zero or negative weight → 0", () => {
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(0, 5)).toBe(0);
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(-10, 5)).toBe(0);
+    });
+    (0, vitest_1.it)("zero reps → 0", () => (0, vitest_1.expect)((0, computeNormalisedLoad_1.estimateOneRepMax)(60, 0)).toBe(0));
+});
+(0, vitest_1.describe)("computeNormalisedLoad — weighted sets", () => {
+    const catalog = { bench: ex({ exerciseId: "bench" }) };
+    const ids = new Set(["bench"]);
+    const sessions = [
+        {
+            date: day(2),
+            exercises: [{ exerciseId: "bench", records: [wr("60", "5")] }],
+        },
+    ];
+    (0, vitest_1.it)("best 1RM as bodyweight ratio (60x5 @80kg → ~0.875)", () => {
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBeCloseTo(0.875, 2);
+        (0, vitest_1.expect)(r.bestExerciseId).toBe("bench");
+    });
+    (0, vitest_1.it)("picks the best set across sessions", () => {
+        const multi = [
+            {
+                date: day(10),
+                exercises: [{ exerciseId: "bench", records: [wr("60", "5")] }],
+            },
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("80", "5")] }],
+            },
+        ];
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, multi, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.bestOneRepMaxKg).toBeCloseTo(93.33, 1);
+    });
+    (0, vitest_1.it)("ignores sessions outside the window", () => {
+        const old = [
+            {
+                date: day(70),
+                exercises: [{ exerciseId: "bench", records: [wr("100", "5")] }],
+            },
+        ];
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, old, catalog, 80, "male", day(56), NOW).ratio).toBe(0);
+    });
+    (0, vitest_1.it)("ignores non-matching exercise ids", () => {
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["other"]), sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBe(0);
+    });
+    (0, vitest_1.it)("ignores incomplete sets (isDone false)", () => {
+        const undone = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("100", "5", false)] }],
+            },
+        ];
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, undone, catalog, 80, "male", day(56), NOW)
+            .ratio).toBe(0);
+    });
+});
+(0, vitest_1.describe)("computeNormalisedLoad — unilateral doubling", () => {
+    (0, vitest_1.it)("unilateral weight is doubled for total load", () => {
+        const catalog = { uni: ex({ exerciseId: "uni", isUnilateral: true }) };
+        const sessions = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "uni", records: [wr("30", "5")] }],
+            },
+        ];
+        // 30*2=60 → 1RM 70 → /80 = 0.875
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["uni"]), sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBeCloseTo(0.875, 2);
+    });
+});
+(0, vitest_1.describe)("computeNormalisedLoad — bodyweight loading", () => {
+    (0, vitest_1.it)("uses weightMultiplier (male) for reps-only", () => {
+        const catalog = {
+            pull: ex({
+                exerciseId: "pull",
+                weightMultiplier: { male: 1.0, female: 0.95, default: 0.97 },
+            }),
+        };
+        const sessions = [
+            { date: day(2), exercises: [{ exerciseId: "pull", records: [ro("8")] }] },
+        ];
+        // load = 1.0*80 = 80; 1RM = 80*(1+8/30)=101.3; /80 = 1.27
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["pull"]), sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBeCloseTo(1.27, 1);
+    });
+    (0, vitest_1.it)("falls back to bodyweightDependency when no weightMultiplier", () => {
+        const catalog = {
+            dip: ex({ exerciseId: "dip", bodyweightDependency: "high" }),
+        };
+        const sessions = [
+            { date: day(2), exercises: [{ exerciseId: "dip", records: [ro("8")] }] },
+        ];
+        // high → 0.9*80=72; 1RM=72*(1+8/30)=91.2; /80=1.14
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["dip"]), sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBeCloseTo(1.14, 1);
+    });
+    (0, vitest_1.it)("added aux weight stacks on bodyweight load", () => {
+        const catalog = {
+            pull: ex({
+                exerciseId: "pull",
+                weightMultiplier: { male: 1.0, female: 0.95, default: 0.97 },
+            }),
+        };
+        const sessions = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "pull", records: [ro("5", "20")] }],
+            },
+        ];
+        // load = 80 + 20 = 100; 1RM=100*(1+5/30)=116.7; /80=1.46
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["pull"]), sessions, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(r.ratio).toBeCloseTo(1.46, 1);
+    });
+    (0, vitest_1.it)("female weightMultiplier column is used for female users", () => {
+        const catalog = {
+            pull: ex({
+                exerciseId: "pull",
+                weightMultiplier: { male: 1.0, female: 0.5, default: 0.97 },
+            }),
+        };
+        const sessions = [
+            { date: day(2), exercises: [{ exerciseId: "pull", records: [ro("8")] }] },
+        ];
+        const male = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["pull"]), sessions, catalog, 80, "male", day(56), NOW);
+        const female = (0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["pull"]), sessions, catalog, 80, "female", day(56), NOW);
+        (0, vitest_1.expect)(female.ratio).toBeLessThan(male.ratio);
+    });
+});
+(0, vitest_1.describe)("computeNormalisedLoad — safeParseFloat guards", () => {
+    const catalog = { bench: ex({ exerciseId: "bench" }) };
+    const ids = new Set(["bench"]);
+    (0, vitest_1.it)("malformed kg → 0 load, finite ratio", () => {
+        const s = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("abc", "5")] }],
+            },
+        ];
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, s, catalog, 80, "male", day(56), NOW);
+        (0, vitest_1.expect)(Number.isFinite(r.ratio)).toBe(true);
+        (0, vitest_1.expect)(r.ratio).toBe(0);
+    });
+    (0, vitest_1.it)("negative reps → 0 load", () => {
+        const s = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("60", "-5")] }],
+            },
+        ];
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, s, catalog, 80, "male", day(56), NOW).ratio).toBe(0);
+    });
+    (0, vitest_1.it)("zero bodyweight falls back to default (no divide-by-zero)", () => {
+        const s = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("60", "5")] }],
+            },
+        ];
+        const r = (0, computeNormalisedLoad_1.computeNormalisedLoad)(ids, s, catalog, 0, "male", day(56), NOW);
+        (0, vitest_1.expect)(Number.isFinite(r.ratio)).toBe(true);
+    });
+});
+(0, vitest_1.describe)("computeNormalisedLoad — non-strength record types contribute 0", () => {
+    (0, vitest_1.it)("duration set → 0", () => {
+        const catalog = { plank: ex({ exerciseId: "plank" }) };
+        const s = [
+            {
+                date: day(2),
+                exercises: [
+                    {
+                        exerciseId: "plank",
+                        records: [
+                            {
+                                type: "duration",
+                                durationMmSs: "01:00",
+                                auxWeightKg: "0",
+                                isDone: true,
+                                isStrictMode: false,
+                            },
+                        ],
+                    },
+                ],
+            },
+        ];
+        (0, vitest_1.expect)((0, computeNormalisedLoad_1.computeNormalisedLoad)(new Set(["plank"]), s, catalog, 80, "male", day(56), NOW).ratio).toBe(0);
+    });
+});

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;

package/dist/utils/constellation/evaluateConstellation.js

@@ -0,0 +1,135 @@
+"use strict";
+// utils/constellation/evaluateConstellation.ts — Orchestrator
+/**
+ * ============================================================================
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateConstellation = evaluateConstellation;
+const scoringWorkout_1 = require("../scoringWorkout");
+const starFoundation_1 = require("./starFoundation");
+const levelThresholds_1 = require("./levelThresholds");
+const consistency_1 = require("./stars/consistency");
+const quality_1 = require("./stars/quality");
+const push_1 = require("./stars/push");
+const pull_1 = require("./stars/pull");
+const lowerBody_1 = require("./stars/lowerBody");
+const recovery_1 = require("./stars/recovery");
+/**
+ * The six stars, in figure reading order: heart (consistency) and core
+ * (quality) first, then the limbs (push/pull/lowerBody), then the crown
+ * (recovery). Appending a level/goal star later = adding to this list.
+ */
+const STAR_DEFINITIONS = [
+    consistency_1.consistencyStar,
+    quality_1.qualityStar,
+    push_1.pushStar,
+    pull_1.pullStar,
+    lowerBody_1.lowerBodyStar,
+    recovery_1.recoveryStar,
+];
+/**
+ * Score every (session, exercise) exactly once. Shared by quality (uses
+ * `score`) and recovery (uses `muscleScores`). An exercise missing from the
+ * catalog, or one the engine cannot score, yields score=null + empty muscles
+ * and is skipped downstream.
+ */
+function scoreAllSessions(input) {
+    var _a;
+    const { sessions, exerciseCatalog, user, now } = input;
+    const scored = [];
+    for (const session of sessions) {
+        if (session.date > now)
+            continue; // ignore future-dated sessions
+        const exercises = [];
+        for (const ex of session.exercises) {
+            const exercise = exerciseCatalog[ex.exerciseId];
+            if (!exercise) {
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: null,
+                    muscleScores: {},
+                });
+                continue;
+            }
+            try {
+                const result = (0, scoringWorkout_1.calculateExerciseScoreV2)({
+                    exercise,
+                    record: ex.records,
+                    user: user,
+                });
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: typeof result.score === "number" ? result.score : null,
+                    muscleScores: (_a = result.muscleScores) !== null && _a !== void 0 ? _a : {},
+                });
+            }
+            catch {
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: null,
+                    muscleScores: {},
+                });
+            }
+        }
+        scored.push({ date: session.date, exercises });
+    }
+    return scored;
+}
+/** Build the figure aggregate from the resolved stars. */
+function computeFigure(stars) {
+    if (stars.length === 0) {
+        return { auraIntensity: 0, fullStarCount: 0 };
+    }
+    const totalBrightness = stars.reduce((sum, s) => sum + s.brightness, 0);
+    const auraIntensity = totalBrightness / stars.length;
+    const fullStarCount = stars.filter((s) => s.tier === 3).length;
+    return {
+        auraIntensity: Math.round(auraIntensity * 10) / 10,
+        fullStarCount,
+    };
+}
+/**
+ * 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
+ */
+function evaluateConstellation(input) {
+    if (!Number.isFinite(input.now)) {
+        throw new Error("evaluateConstellation: `now` must be a finite UNIX ms timestamp");
+    }
+    const level = (0, levelThresholds_1.clampLevel)(input.currentLevel);
+    const scoredSessions = scoreAllSessions(input);
+    const ctx = {
+        sessions: input.sessions,
+        scoredSessions,
+        exerciseCatalog: input.exerciseCatalog,
+        user: input.user,
+        now: input.now,
+        level,
+    };
+    const stars = STAR_DEFINITIONS.map((def) => (0, starFoundation_1.resolveStar)(def, ctx));
+    const figure = computeFigure(stars);
+    return {
+        stars,
+        figure,
+        currentLevel: level,
+        evaluatedAt: new Date(input.now).toISOString(),
+    };
+}

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

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