@dgpholdings/greatoak-shared 1.2.86 → 1.2.88

package/dist/utils/constellation/stars/consistency.js

@@ -0,0 +1,142 @@
+"use strict";
+// utils/constellation/stars/consistency.ts — Consistency Star (the heart)
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Consistency Star (the heart)
+ * ============================================================================
+ *
+ * The live "showing up" star. Brightness reflects the user's CURRENT training
+ * habit, recomputed every call from recent session dates. The one star meant to
+ * be maintained, not achieved — it brightens with a steady habit and dims when
+ * the user goes quiet.
+ *
+ * Full brightness requires BOTH:
+ *   - requiredSessions training days within the trailing window, AND
+ *   - the trailing idle gap (last session -> now) within maxGapDays.
+ *
+ * Brightness is graded below full so progress is always visible:
+ *   - countComponent — progress toward the required session count
+ *   - gapComponent   — a live penalty as the TRAILING gap exceeds maxGapDays
+ *
+ * Note: brightness uses the TRAILING gap, not interior gaps. An old gap the user
+ * has since recovered from should not permanently dim a live habit signal.
+ * Interior gaps still inform the gap MESSAGE for context.
+ *
+ * Counting rule: a session counts as a training day only if it has >=1 completed
+ * set. Multiple sessions on one calendar day = one training day.
+ *
+ * Thresholds come from CONSISTENCY_THRESHOLDS[level].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consistencyStar = void 0;
+const levelThresholds_1 = require("../levelThresholds");
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// --- Helpers ----------------------------------------------------------------
+/** Does a session have at least one completed set? (isDone is a guaranteed bool on TRecord) */
+function hasCompletedSet(session) {
+    for (const ex of session.exercises) {
+        for (const set of ex.records) {
+            if (set.isDone)
+                return true;
+        }
+    }
+    return false;
+}
+function countMeasure(sessions, required) {
+    return {
+        value: sessions,
+        unit: "sessions",
+        display: {
+            translationKey: "constellation.consistency.measure.sessions",
+            params: [Math.min(sessions, required), required],
+        },
+    };
+}
+function buildGap(sessionsInWindow, longestGapDays, trailingGapDays, required, maxGapDays, warningAtIdleDays) {
+    // Brand-new user (no training days in window): invite, don't scold. Without
+    // this, a zero-session user trips the "broken" branch (trailingGap = window).
+    if (sessionsInWindow === 0) {
+        return { translationKey: "constellation.consistency.gap.getStarted" };
+    }
+    // Cooling warning: trailing gap is creeping toward the max.
+    if (trailingGapDays >= warningAtIdleDays && trailingGapDays <= maxGapDays) {
+        const daysRemaining = maxGapDays - trailingGapDays + 1;
+        return {
+            translationKey: "constellation.consistency.gap.cooling",
+            params: [daysRemaining],
+        };
+    }
+    if (longestGapDays > maxGapDays) {
+        return { translationKey: "constellation.consistency.gap.broken" };
+    }
+    const remaining = Math.max(0, required - sessionsInWindow);
+    if (remaining > 0) {
+        return {
+            translationKey: "constellation.consistency.gap.moreSessions",
+            params: [remaining],
+        };
+    }
+    return { translationKey: "constellation.consistency.gap.full" };
+}
+// --- Evaluator --------------------------------------------------------------
+function evaluateConsistency(ctx) {
+    const { requiredSessions, windowDays, maxGapDays, warningAtIdleDays } = levelThresholds_1.CONSISTENCY_THRESHOLDS[ctx.level];
+    const { now } = ctx;
+    const windowStart = now - windowDays * MS_PER_DAY;
+    const nowDay = Math.floor(now / MS_PER_DAY);
+    // Training days = sessions with >=1 completed set, deduped to calendar day,
+    // within the trailing window, sorted ascending. Upper bound is by CALENDAR
+    // DAY (<= today) so a session logged later today than `now` still counts.
+    const dayIndices = Array.from(new Set(ctx.sessions
+        .filter((s) => {
+        if (!hasCompletedSet(s))
+            return false;
+        const d = Math.floor(s.date / MS_PER_DAY);
+        return s.date > windowStart && d <= nowDay;
+    })
+        .map((s) => Math.floor(s.date / MS_PER_DAY)))).sort((a, b) => a - b);
+    const sessionsInWindow = dayIndices.length;
+    // Longest interior gap (for the message only).
+    let longestGapDays = 0;
+    for (let i = 1; i < dayIndices.length; i++) {
+        const gap = dayIndices[i] - dayIndices[i - 1];
+        if (gap > longestGapDays)
+            longestGapDays = gap;
+    }
+    // Trailing gap: last training day -> today. No sessions -> maximally idle.
+    const trailingGap = dayIndices.length > 0
+        ? nowDay - dayIndices[dayIndices.length - 1]
+        : windowDays;
+    if (trailingGap > longestGapDays)
+        longestGapDays = trailingGap;
+    // Brightness: two multiplicative components, both 0..1.
+    const countComponent = Math.min(1, sessionsInWindow / requiredSessions);
+    let gapComponent;
+    if (trailingGap <= maxGapDays) {
+        gapComponent = 1; // within allowed idle window — no penalty
+    }
+    else {
+        const over = trailingGap - maxGapDays;
+        const decayRange = Math.max(1, windowDays - maxGapDays);
+        gapComponent = Math.max(0, 1 - over / decayRange);
+    }
+    const brightness = Math.min(100, countComponent * gapComponent * 100);
+    return {
+        brightness,
+        detail: {
+            currentState: countMeasure(sessionsInWindow, requiredSessions),
+            target: countMeasure(requiredSessions, requiredSessions),
+            gap: buildGap(sessionsInWindow, longestGapDays, trailingGap, requiredSessions, maxGapDays, warningAtIdleDays),
+        },
+    };
+}
+// --- Definition -------------------------------------------------------------
+exports.consistencyStar = {
+    id: "consistency",
+    displayName: { translationKey: "constellation.consistency.name" },
+    color: "#ff8c00", // amber-gold — the spark of the flame, the heart
+    figurePosition: "heart",
+    objective: { translationKey: "constellation.consistency.objective" },
+    rationale: { translationKey: "constellation.consistency.rationale" },
+    evaluate: evaluateConsistency,
+};

package/dist/utils/constellation/stars/consistency.test.d.ts

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

package/dist/utils/constellation/stars/consistency.test.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/stars/consistency.test.ts
+const vitest_1 = require("vitest");
+const starFoundation_1 = require("../starFoundation");
+const consistency_1 = require("../stars/consistency");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+const set = (isDone = true) => ({
+    type: "weight-reps",
+    kg: "20",
+    reps: "5",
+    isDone,
+    isStrictMode: false,
+});
+const sess = (d, isDone = true) => ({
+    date: day(d),
+    exercises: [{ exerciseId: "x", records: [set(isDone)] }],
+});
+const ctx = (sessions, level = 1) => ({
+    sessions,
+    scoredSessions: [],
+    exerciseCatalog: {},
+    user: { weightKg: 80 },
+    now: NOW,
+    level,
+});
+(0, vitest_1.describe)("consistency — new vs lapsed user", () => {
+    (0, vitest_1.it)("no sessions → getStarted, brightness 0", () => {
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx([]));
+        (0, vitest_1.expect)(r.brightness).toBe(0);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.getStarted");
+    });
+    (0, vitest_1.it)("one old session (20d ago), none since → broken", () => {
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx([sess(20)]));
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.broken");
+    });
+});
+(0, vitest_1.describe)("consistency — full habit", () => {
+    (0, vitest_1.it)("8 well-spaced sessions in 28d, recent → full", () => {
+        const days = [1, 4, 8, 11, 15, 18, 22, 25];
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(days.map((d) => sess(d))));
+        (0, vitest_1.expect)(r.brightness).toBe(100);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.full");
+    });
+    (0, vitest_1.it)("fewer than required → partial + moreSessions gap", () => {
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx([sess(1), sess(4), sess(8), sess(11)]));
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+        (0, vitest_1.expect)(r.brightness).toBeLessThan(100);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.moreSessions");
+    });
+});
+(0, vitest_1.describe)("consistency — counting rules", () => {
+    (0, vitest_1.it)("sessions with no completed set don't count", () => {
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx([sess(1, false), sess(4, false)]));
+        (0, vitest_1.expect)(r.brightness).toBe(0);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.getStarted");
+    });
+    (0, vitest_1.it)("two sessions same calendar day count once", () => {
+        const twoSameDay = [
+            { date: day(2), exercises: [{ exerciseId: "x", records: [set()] }] },
+            {
+                date: day(2) + 3600000,
+                exercises: [{ exerciseId: "y", records: [set()] }],
+            },
+        ];
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(twoSameDay));
+        // 1 unique day toward 8 → 12.5% * gap (trailing 2d ok) → ~13
+        (0, vitest_1.expect)(r.currentState.value).toBe(1);
+    });
+});
+(0, vitest_1.describe)("consistency — trailing gap behaviour", () => {
+    (0, vitest_1.it)("cooling warning as trailing gap approaches max", () => {
+        // 8 sessions but last was 4 days ago (warningAtIdleDays=4, maxGap=5)
+        const days = [4, 7, 10, 13, 16, 19, 22, 25];
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(days.map((d) => sess(d))));
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.consistency.gap.cooling");
+    });
+    (0, vitest_1.it)("trailing gap beyond max decays brightness below count-only", () => {
+        // enough sessions for full count, but last 10 days ago → gap penalty
+        const days = [10, 12, 14, 16, 18, 20, 22, 24];
+        const r = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(days.map((d) => sess(d))));
+        (0, vitest_1.expect)(r.brightness).toBeLessThan(100);
+    });
+});
+(0, vitest_1.describe)("consistency — level scaling", () => {
+    (0, vitest_1.it)("8 sessions fills L1 but not L2 (needs 12)", () => {
+        const days = [1, 4, 8, 11, 15, 18, 22, 25];
+        const l1 = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(days.map((d) => sess(d)), 1));
+        const l2 = (0, starFoundation_1.resolveStar)(consistency_1.consistencyStar, ctx(days.map((d) => sess(d)), 2));
+        (0, vitest_1.expect)(l1.brightness).toBe(100);
+        (0, vitest_1.expect)(l2.brightness).toBeLessThan(100);
+    });
+});

package/dist/utils/constellation/stars/lowerBody.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Lower Body Star
+ * ============================================================================
+ *
+ * Lower-body strength across squat, lunge, and hinge patterns combined, any
+ * equipment. Squats, goblet squats, leg press, lunges, deadlifts, RDLs, hip
+ * thrusts, kettlebell swings — all count. Best load across all three lights it.
+ * (Knee-vs-hip balance nuance deferred to the future goal layer.)
+ *
+ * Threshold per level from STRENGTH_THRESHOLDS.lowerBody, resolved by sex.
+ * Leg press is NOT special-cased — it is simply a squat-pattern exercise.
+ * Bodyweight lower-body work loads via the exercise's weightMultiplier, so home
+ * users can reach the threshold honestly.
+ */
+import type { TStarDefinition } from "../types";
+export declare const lowerBodyStar: TStarDefinition;

package/dist/utils/constellation/stars/lowerBody.js

@@ -0,0 +1,30 @@
+"use strict";
+// utils/constellation/stars/lowerBody.ts — Lower Body Star
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Lower Body Star
+ * ============================================================================
+ *
+ * Lower-body strength across squat, lunge, and hinge patterns combined, any
+ * equipment. Squats, goblet squats, leg press, lunges, deadlifts, RDLs, hip
+ * thrusts, kettlebell swings — all count. Best load across all three lights it.
+ * (Knee-vs-hip balance nuance deferred to the future goal layer.)
+ *
+ * Threshold per level from STRENGTH_THRESHOLDS.lowerBody, resolved by sex.
+ * Leg press is NOT special-cased — it is simply a squat-pattern exercise.
+ * Bodyweight lower-body work loads via the exercise's weightMultiplier, so home
+ * users can reach the threshold honestly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lowerBodyStar = void 0;
+const strengthStarHelpers_1 = require("../strengthStarHelpers");
+const LOWER_BODY_PATTERNS = ["squat", "lunge", "hinge"];
+exports.lowerBodyStar = {
+    id: "lowerBody",
+    displayName: { translationKey: "constellation.lowerBody.name" },
+    color: "#40b060", // earth green — the foundation everything sits on
+    figurePosition: "base",
+    objective: { translationKey: "constellation.lowerBody.objective" },
+    rationale: { translationKey: "constellation.lowerBody.rationale" },
+    evaluate: (ctx) => (0, strengthStarHelpers_1.evaluateStrengthStar)(ctx, "lowerBody", LOWER_BODY_PATTERNS, "constellation.lowerBody"),
+};

package/dist/utils/constellation/stars/pull.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Pull Star
+ * ============================================================================
+ *
+ * Pulling strength across all pull-pattern exercises (horizontal + vertical),
+ * any equipment. Rows, cable rows, lat pulldowns, pull-ups, chin-ups — all count.
+ * Threshold per level from STRENGTH_THRESHOLDS.pull, resolved by sex.
+ */
+import type { TStarDefinition } from "../types";
+export declare const pullStar: TStarDefinition;

package/dist/utils/constellation/stars/pull.js

@@ -0,0 +1,24 @@
+"use strict";
+// utils/constellation/stars/pull.ts — Pull Star
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Pull Star
+ * ============================================================================
+ *
+ * Pulling strength across all pull-pattern exercises (horizontal + vertical),
+ * any equipment. Rows, cable rows, lat pulldowns, pull-ups, chin-ups — all count.
+ * Threshold per level from STRENGTH_THRESHOLDS.pull, resolved by sex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pullStar = void 0;
+const strengthStarHelpers_1 = require("../strengthStarHelpers");
+const PULL_PATTERNS = ["pull_horizontal", "pull_vertical"];
+exports.pullStar = {
+    id: "pull",
+    displayName: { translationKey: "constellation.pull.name" },
+    color: "#2060ff", // cool blue — drawing resistance in
+    figurePosition: "rightArm",
+    objective: { translationKey: "constellation.pull.objective" },
+    rationale: { translationKey: "constellation.pull.rationale" },
+    evaluate: (ctx) => (0, strengthStarHelpers_1.evaluateStrengthStar)(ctx, "pull", PULL_PATTERNS, "constellation.pull"),
+};

package/dist/utils/constellation/stars/push.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Push Star
+ * ============================================================================
+ *
+ * Pushing strength across all push-pattern exercises (horizontal + vertical),
+ * any equipment. Bench, machine press, push-ups, overhead press — all count.
+ * Threshold per level from STRENGTH_THRESHOLDS.push, resolved by sex.
+ */
+import type { TStarDefinition } from "../types";
+export declare const pushStar: TStarDefinition;

package/dist/utils/constellation/stars/push.js

@@ -0,0 +1,24 @@
+"use strict";
+// utils/constellation/stars/push.ts — Push Star
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Push Star
+ * ============================================================================
+ *
+ * Pushing strength across all push-pattern exercises (horizontal + vertical),
+ * any equipment. Bench, machine press, push-ups, overhead press — all count.
+ * Threshold per level from STRENGTH_THRESHOLDS.push, resolved by sex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushStar = void 0;
+const strengthStarHelpers_1 = require("../strengthStarHelpers");
+const PUSH_PATTERNS = ["push_horizontal", "push_vertical"];
+exports.pushStar = {
+    id: "push",
+    displayName: { translationKey: "constellation.push.name" },
+    color: "#ff4820", // warm red — forward force
+    figurePosition: "leftArm",
+    objective: { translationKey: "constellation.push.objective" },
+    rationale: { translationKey: "constellation.push.rationale" },
+    evaluate: (ctx) => (0, strengthStarHelpers_1.evaluateStrengthStar)(ctx, "push", PUSH_PATTERNS, "constellation.push"),
+};

package/dist/utils/constellation/stars/quality.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Quality Star (the core)
+ * ============================================================================
+ *
+ * Execution quality. Brightness reflects how many of the user's recent sessions
+ * were executed well. Reads PRE-SCORED sessions from context (the orchestrator
+ * scores once); this star never calls the scoring engine itself.
+ *
+ * Session quality  = simple average of its exercises' quality scores (0-100).
+ * Star brightness  = count-based: of the last N sessions, how many cleared the
+ *                    quality bar, scaled toward a target count. Count-based (not
+ *                    a consecutive streak) so a single off day never zeroes the
+ *                    star — inviting, not punishing.
+ *
+ * Thresholds come from QUALITY_THRESHOLDS[level].
+ */
+import type { TStarDefinition } from "../types";
+export declare const qualityStar: TStarDefinition;

package/dist/utils/constellation/stars/quality.js

@@ -0,0 +1,98 @@
+"use strict";
+// utils/constellation/stars/quality.ts — Quality Star (the core)
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Quality Star (the core)
+ * ============================================================================
+ *
+ * Execution quality. Brightness reflects how many of the user's recent sessions
+ * were executed well. Reads PRE-SCORED sessions from context (the orchestrator
+ * scores once); this star never calls the scoring engine itself.
+ *
+ * Session quality  = simple average of its exercises' quality scores (0-100).
+ * Star brightness  = count-based: of the last N sessions, how many cleared the
+ *                    quality bar, scaled toward a target count. Count-based (not
+ *                    a consecutive streak) so a single off day never zeroes the
+ *                    star — inviting, not punishing.
+ *
+ * Thresholds come from QUALITY_THRESHOLDS[level].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qualityStar = void 0;
+const levelThresholds_1 = require("../levelThresholds");
+// --- Session quality --------------------------------------------------------
+/**
+ * Average score across a scored session's scorable exercises. Returns null if
+ * the session has no scorable exercises (all missing/unscorable).
+ */
+function sessionQuality(session) {
+    const scores = [];
+    for (const ex of session.exercises) {
+        if (typeof ex.score === "number")
+            scores.push(ex.score);
+    }
+    if (scores.length === 0)
+        return null;
+    return scores.reduce((s, v) => s + v, 0) / scores.length;
+}
+// --- Detail builders --------------------------------------------------------
+function clearingMeasure(clearing, target) {
+    return {
+        value: clearing,
+        unit: "sessions",
+        display: {
+            translationKey: "constellation.quality.measure.clearing",
+            params: [Math.min(clearing, target), target],
+        },
+    };
+}
+function buildGap(clearing, considered, target, bar) {
+    if (considered === 0) {
+        return { translationKey: "constellation.quality.gap.noData" };
+    }
+    if (clearing >= target) {
+        return { translationKey: "constellation.quality.gap.full" };
+    }
+    return {
+        translationKey: "constellation.quality.gap.moreQuality",
+        params: [target - clearing, bar],
+    };
+}
+// --- Evaluator --------------------------------------------------------------
+function evaluateQuality(ctx) {
+    const { bar, windowSessions, targetClearing } = levelThresholds_1.QUALITY_THRESHOLDS[ctx.level];
+    // Most recent N scored sessions (descending by date). Future sessions were
+    // already excluded by the orchestrator when scoring.
+    const recent = [...ctx.scoredSessions]
+        .sort((a, b) => b.date - a.date)
+        .slice(0, windowSessions);
+    let clearing = 0;
+    let considered = 0;
+    for (const session of recent) {
+        const q = sessionQuality(session);
+        if (q === null)
+            continue; // unscorable session counts neither way
+        considered++;
+        if (q >= bar)
+            clearing++;
+    }
+    const brightness = Math.min(100, (clearing / targetClearing) * 100);
+    return {
+        brightness,
+        detail: {
+            currentState: clearingMeasure(clearing, targetClearing),
+            target: clearingMeasure(targetClearing, targetClearing),
+            gap: buildGap(clearing, considered, targetClearing, bar),
+        },
+    };
+}
+// --- Definition -------------------------------------------------------------
+exports.qualityStar = {
+    id: "quality",
+    displayName: { translationKey: "constellation.quality.name" },
+    color: "#00c4b4", // teal — precision, cool focus
+    figurePosition: "core",
+    objective: { translationKey: "constellation.quality.objective" },
+    rationale: { translationKey: "constellation.quality.rationale" },
+    evaluate: evaluateQuality,
+};

package/dist/utils/constellation/stars/quality.test.d.ts

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

package/dist/utils/constellation/stars/quality.test.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/stars/quality.test.ts
+const vitest_1 = require("vitest");
+const starFoundation_1 = require("../starFoundation");
+const quality_1 = require("../stars/quality");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+/** A scored session whose single exercise has the given score. */
+const scored = (d, score) => ({
+    date: day(d),
+    exercises: [{ exerciseId: "x", score, muscleScores: {} }],
+});
+const ctx = (scoredSessions, level = 1) => ({
+    sessions: [],
+    scoredSessions,
+    exerciseCatalog: {},
+    user: {},
+    now: NOW,
+    level,
+});
+(0, vitest_1.describe)("quality — count-based brightness (L1 bar 70, target 5)", () => {
+    (0, vitest_1.it)("5 of 5 sessions clear → full", () => {
+        const s = [
+            scored(1, 80),
+            scored(3, 75),
+            scored(5, 90),
+            scored(7, 72),
+            scored(9, 85),
+        ];
+        const r = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s));
+        (0, vitest_1.expect)(r.brightness).toBe(100);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.quality.gap.full");
+    });
+    (0, vitest_1.it)("3 of 5 clear → 60%", () => {
+        const s = [
+            scored(1, 80),
+            scored(3, 60),
+            scored(5, 90),
+            scored(7, 50),
+            scored(9, 75),
+        ];
+        const r = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s));
+        (0, vitest_1.expect)(r.brightness).toBeCloseTo(60, 0);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.quality.gap.moreQuality");
+    });
+    (0, vitest_1.it)("none clear → 0", () => {
+        const s = [scored(1, 50), scored(3, 40)];
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s)).brightness).toBe(0);
+    });
+});
+(0, vitest_1.describe)("quality — the bar boundary (>= 70 clears)", () => {
+    (0, vitest_1.it)("exactly 70 clears", () => {
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx([scored(1, 70)])).currentState.value).toBe(1);
+    });
+    (0, vitest_1.it)("69 does not clear", () => {
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx([scored(1, 69)])).currentState.value).toBe(0);
+    });
+});
+(0, vitest_1.describe)("quality — session averaging & unscorable handling", () => {
+    (0, vitest_1.it)("session score is the average of its exercises", () => {
+        const s = [
+            {
+                date: day(1),
+                exercises: [
+                    { exerciseId: "a", score: 60, muscleScores: {} },
+                    { exerciseId: "b", score: 80, muscleScores: {} }, // avg 70 → clears
+                ],
+            },
+        ];
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s)).currentState.value).toBe(1);
+    });
+    (0, vitest_1.it)("sessions with no scorable exercises are skipped (neither clear nor fail)", () => {
+        const s = [scored(1, null), scored(3, 80)];
+        const r = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s));
+        (0, vitest_1.expect)(r.currentState.value).toBe(1); // only the scorable one counts
+    });
+    (0, vitest_1.it)("no data at all → noData gap", () => {
+        const r = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx([scored(1, null)]));
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.quality.gap.noData");
+    });
+});
+(0, vitest_1.describe)("quality — window & level scaling", () => {
+    (0, vitest_1.it)("only the most recent N sessions are considered", () => {
+        // L1 window 5: 5 recent good + 3 older bad → still full (bad ones out of window)
+        const s = [
+            scored(1, 90),
+            scored(3, 90),
+            scored(5, 90),
+            scored(7, 90),
+            scored(9, 90),
+            scored(20, 10),
+            scored(22, 10),
+            scored(24, 10),
+        ];
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s)).brightness).toBe(100);
+    });
+    (0, vitest_1.it)("L2 demands a higher bar (78) so 75s stop clearing", () => {
+        const s = [
+            scored(1, 75),
+            scored(3, 75),
+            scored(5, 75),
+            scored(7, 75),
+            scored(9, 75),
+            scored(11, 75),
+            scored(13, 75),
+            scored(15, 75),
+        ];
+        const l1 = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s, 1));
+        const l2 = (0, starFoundation_1.resolveStar)(quality_1.qualityStar, ctx(s, 2));
+        (0, vitest_1.expect)(l1.brightness).toBeGreaterThan(l2.brightness);
+    });
+});

package/dist/utils/constellation/stars/recovery.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Recovery Star (the crown)
+ * ============================================================================
+ *
+ * Recovery intelligence: does the user let trained muscles fully recover, not
+ * just grind through fatigue? Brightness reflects how many RECOVERY CYCLES the
+ * user achieved in the trailing window.
+ *
+ * ZONE-BASED (not all-or-nothing). The body is split into three independent
+ * recovery zones — upper, lower, core. A split-routine lifter (e.g. Push/Pull/
+ * Legs) almost never has the WHOLE body fresh at once, yet is recovering
+ * intelligently zone by zone; an all-muscles-at-once rule would wrongly score
+ * them near zero. So we count cycles PER ZONE.
+ *
+ * A zone "cycle" = a transition where that zone goes fatigued -> recovered
+ * (a multi-day rest counts once). Crucially, a zone only earns cycles if the
+ * user actually TRAINS it in the window — an untrained zone is "always fresh"
+ * and must not hand out free recovery credit. Total cycles = sum across the
+ * zones the user trains, capped at the level target.
+ *
+ * Reads PRE-SCORED sessions from context (orchestrator scores once); builds the
+ * enriched history the fatigue model consumes, then replays the model across
+ * each day of the window. This star never calls the scoring engine itself.
+ *
+ * Thresholds come from RECOVERY_THRESHOLDS[level].
+ */
+import type { TStarDefinition } from "../types";
+export declare const recoveryStar: TStarDefinition;