@dgpholdings/greatoak-shared 1.2.85 → 1.2.87

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;

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 (_b) {
+                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/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Public API
+ * ============================================================================
+ *
+ * The constellation module's surface. Consumers (the Lambda, tests) import from
+ * here, not from internal files.
+ *
+ *   import { evaluateConstellation } from ".../constellation";
+ *   const state = evaluateConstellation({ sessions, exerciseCatalog, user, now });
+ *
+ * Everything else (individual stars, helpers, the normalised-load math) is an
+ * implementation detail and intentionally not re-exported.
+ */
+export { evaluateConstellation } from "./evaluateConstellation";
+export type { TConstellationInput, TConstellationState, TConstellationFigure, TResolvedStar, TStarId, TStarTier, TFigurePosition, TStarMeasure, TLocalizedText, TSessionRecord, } from "./types";
+export { TIER_THRESHOLDS, deriveTier } from "./starFoundation";

package/dist/utils/constellation/index.js

@@ -0,0 +1,26 @@
+"use strict";
+// utils/constellation/index.ts — Public API
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Public API
+ * ============================================================================
+ *
+ * The constellation module's surface. Consumers (the Lambda, tests) import from
+ * here, not from internal files.
+ *
+ *   import { evaluateConstellation } from ".../constellation";
+ *   const state = evaluateConstellation({ sessions, exerciseCatalog, user, now });
+ *
+ * Everything else (individual stars, helpers, the normalised-load math) is an
+ * implementation detail and intentionally not re-exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveTier = exports.TIER_THRESHOLDS = exports.evaluateConstellation = void 0;
+// The single entry point.
+var evaluateConstellation_1 = require("./evaluateConstellation");
+Object.defineProperty(exports, "evaluateConstellation", { enumerable: true, get: function () { return evaluateConstellation_1.evaluateConstellation; } });
+// Tier thresholds are exported so the app can label tiers consistently with
+// the server (dormant / faint / rising / full) without hard-coding the cutoffs.
+var starFoundation_1 = require("./starFoundation");
+Object.defineProperty(exports, "TIER_THRESHOLDS", { enumerable: true, get: function () { return starFoundation_1.TIER_THRESHOLDS; } });
+Object.defineProperty(exports, "deriveTier", { enumerable: true, get: function () { return starFoundation_1.deriveTier; } });

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

@@ -0,0 +1,99 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Level Threshold Ladder
+ * ============================================================================
+ *
+ * The single source of truth for what "full" means at each level, for every
+ * star. Stars read their row by the user's current level; nothing about a
+ * threshold is hard-coded inside star logic.
+ *
+ * Design intent (coach's calibration):
+ *   Level 1 = committed beginner   (reachable in ~2-3 months of honest work)
+ *   Level 2 = solid intermediate   (~6-12 months)
+ *   Level 3 = advanced             (multi-year, genuinely strong)
+ *
+ * Strength thresholds are estimated-1RM as a ratio of bodyweight, by sex.
+ * `unmentioned` gender is resolved to `male` (the higher bar) elsewhere, so a
+ * star is never too-easily lit for an unspecified profile.
+ *
+ * Calibration note (v1.1): these are first-pass values to be tuned against real
+ * brightness distributions post-launch. L1 pull was lowered from 0.65 -> 0.50
+ * because 0.65x BW pull excluded the large beginner segment that cannot yet do
+ * bodyweight pull-ups; L1 push eased 0.75 -> 0.60 so the first milestone lands
+ * in ~6-8 weeks rather than feeling intermediate. Lower body held at 1.0x — the
+ * bodyweight-load path lets home users reach it via pistol squats/lunges.
+ *
+ * Adding a level later = adding a key to each record. Star code does not change.
+ * The future goal layer can multiply these per-goal without touching this file.
+ */
+export type TLevel = 1 | 2 | 3;
+export declare const MAX_LEVEL: TLevel;
+export interface ISexThreshold {
+    male: number;
+    female: number;
+}
+/**
+ * Bodyweight-ratio thresholds for a full strength star, per level.
+ *
+ * Push  (bench/press family):
+ *   L1 0.60 — a committed beginner pressing meaningful load (~6-8 weeks)
+ *   L2 1.00 — pressing ~bodyweight (classic intermediate bench)
+ *   L3 1.40 — advanced pressing strength
+ * Pull  (row/pulldown/pull-up family):
+ *   L1 0.50 — reachable beginner pulling (rows / pulldowns), pre-pull-up
+ *   L2 0.85 — strong rows / clean bodyweight pull-ups
+ *   L3 1.20 — advanced (heavy weighted pull-ups)
+ * Lower (squat/hinge/lunge family):
+ *   L1 1.00 — beginner squatting ~bodyweight (reachable via bodyweight work too)
+ *   L2 1.50 — intermediate
+ *   L3 2.00 — advanced (a 2x bodyweight squat is a real milestone)
+ */
+export declare const STRENGTH_THRESHOLDS: Record<"push" | "pull" | "lowerBody", Record<TLevel, ISexThreshold>>;
+export interface IConsistencyThreshold {
+    /** Training days required within the window for full brightness. */
+    requiredSessions: number;
+    /** Trailing window length in days. */
+    windowDays: number;
+    /** Maximum idle gap (days) allowed before the no-gap condition breaks. */
+    maxGapDays: number;
+    /** Trailing idle days at which the "cooling" warning begins. */
+    warningAtIdleDays: number;
+}
+/**
+ * L1 ~2x/week habit; L2 ~3x/week; L3 ~4x/week. Window stays 28 days so it always
+ * reads "this month's habit".
+ *
+ * L3 maxGap relaxed 3 -> 4 (v1.1): a 3-day cap punished legitimate splits and
+ * planned deloads. 4 still keeps higher-level gap discipline tighter than L1/L2
+ * without penalising smart programming.
+ */
+export declare const CONSISTENCY_THRESHOLDS: Record<TLevel, IConsistencyThreshold>;
+export interface IQualityThreshold {
+    /** A session "clears" at or above this score (0-100). */
+    bar: number;
+    /** Number of most-recent sessions considered. */
+    windowSessions: number;
+    /** How many of the window must clear for full brightness. */
+    targetClearing: number;
+}
+/**
+ * L1 forgiving bar (70) over a short window; higher levels demand both a higher
+ * bar and a longer clean streak.
+ */
+export declare const QUALITY_THRESHOLDS: Record<TLevel, IQualityThreshold>;
+export interface IRecoveryThreshold {
+    /** Recovery cycles needed for full brightness (summed across trained zones). */
+    targetCycles: number;
+    /** Trailing window length in days. */
+    windowDays: number;
+    /** A muscle is "recovered" below this fatigue value (0-100). */
+    recoveredBelow: number;
+}
+/**
+ * Cycles are counted PER trained zone (upper/lower/core), so targets reflect
+ * summed zone cycles. Recovery is meaningful only alongside training volume — a
+ * no-train user earns nothing (untrained zones give no credit).
+ */
+export declare const RECOVERY_THRESHOLDS: Record<TLevel, IRecoveryThreshold>;
+/** Clamp any incoming level into the valid 1..MAX_LEVEL range. */
+export declare function clampLevel(level: number | undefined): TLevel;

package/dist/utils/constellation/levelThresholds.js

@@ -0,0 +1,123 @@
+"use strict";
+// utils/constellation/levelThresholds.ts — Per-level threshold ladder
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Level Threshold Ladder
+ * ============================================================================
+ *
+ * The single source of truth for what "full" means at each level, for every
+ * star. Stars read their row by the user's current level; nothing about a
+ * threshold is hard-coded inside star logic.
+ *
+ * Design intent (coach's calibration):
+ *   Level 1 = committed beginner   (reachable in ~2-3 months of honest work)
+ *   Level 2 = solid intermediate   (~6-12 months)
+ *   Level 3 = advanced             (multi-year, genuinely strong)
+ *
+ * Strength thresholds are estimated-1RM as a ratio of bodyweight, by sex.
+ * `unmentioned` gender is resolved to `male` (the higher bar) elsewhere, so a
+ * star is never too-easily lit for an unspecified profile.
+ *
+ * Calibration note (v1.1): these are first-pass values to be tuned against real
+ * brightness distributions post-launch. L1 pull was lowered from 0.65 -> 0.50
+ * because 0.65x BW pull excluded the large beginner segment that cannot yet do
+ * bodyweight pull-ups; L1 push eased 0.75 -> 0.60 so the first milestone lands
+ * in ~6-8 weeks rather than feeling intermediate. Lower body held at 1.0x — the
+ * bodyweight-load path lets home users reach it via pistol squats/lunges.
+ *
+ * Adding a level later = adding a key to each record. Star code does not change.
+ * The future goal layer can multiply these per-goal without touching this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOVERY_THRESHOLDS = exports.QUALITY_THRESHOLDS = exports.CONSISTENCY_THRESHOLDS = exports.STRENGTH_THRESHOLDS = exports.MAX_LEVEL = void 0;
+exports.clampLevel = clampLevel;
+exports.MAX_LEVEL = 3;
+/**
+ * Bodyweight-ratio thresholds for a full strength star, per level.
+ *
+ * Push  (bench/press family):
+ *   L1 0.60 — a committed beginner pressing meaningful load (~6-8 weeks)
+ *   L2 1.00 — pressing ~bodyweight (classic intermediate bench)
+ *   L3 1.40 — advanced pressing strength
+ * Pull  (row/pulldown/pull-up family):
+ *   L1 0.50 — reachable beginner pulling (rows / pulldowns), pre-pull-up
+ *   L2 0.85 — strong rows / clean bodyweight pull-ups
+ *   L3 1.20 — advanced (heavy weighted pull-ups)
+ * Lower (squat/hinge/lunge family):
+ *   L1 1.00 — beginner squatting ~bodyweight (reachable via bodyweight work too)
+ *   L2 1.50 — intermediate
+ *   L3 2.00 — advanced (a 2x bodyweight squat is a real milestone)
+ */
+exports.STRENGTH_THRESHOLDS = {
+    push: {
+        1: { male: 0.6, female: 0.45 },
+        2: { male: 1.0, female: 0.7 },
+        3: { male: 1.4, female: 0.95 },
+    },
+    pull: {
+        1: { male: 0.5, female: 0.38 },
+        2: { male: 0.85, female: 0.6 },
+        3: { male: 1.2, female: 0.85 },
+    },
+    lowerBody: {
+        1: { male: 1.0, female: 0.75 },
+        2: { male: 1.5, female: 1.1 },
+        3: { male: 2.0, female: 1.5 },
+    },
+};
+/**
+ * L1 ~2x/week habit; L2 ~3x/week; L3 ~4x/week. Window stays 28 days so it always
+ * reads "this month's habit".
+ *
+ * L3 maxGap relaxed 3 -> 4 (v1.1): a 3-day cap punished legitimate splits and
+ * planned deloads. 4 still keeps higher-level gap discipline tighter than L1/L2
+ * without penalising smart programming.
+ */
+exports.CONSISTENCY_THRESHOLDS = {
+    1: {
+        requiredSessions: 8,
+        windowDays: 28,
+        maxGapDays: 5,
+        warningAtIdleDays: 4,
+    },
+    2: {
+        requiredSessions: 12,
+        windowDays: 28,
+        maxGapDays: 4,
+        warningAtIdleDays: 3,
+    },
+    3: {
+        requiredSessions: 16,
+        windowDays: 28,
+        maxGapDays: 4,
+        warningAtIdleDays: 3,
+    },
+};
+/**
+ * L1 forgiving bar (70) over a short window; higher levels demand both a higher
+ * bar and a longer clean streak.
+ */
+exports.QUALITY_THRESHOLDS = {
+    1: { bar: 70, windowSessions: 5, targetClearing: 5 },
+    2: { bar: 78, windowSessions: 8, targetClearing: 7 },
+    3: { bar: 85, windowSessions: 10, targetClearing: 9 },
+};
+/**
+ * Cycles are counted PER trained zone (upper/lower/core), so targets reflect
+ * summed zone cycles. Recovery is meaningful only alongside training volume — a
+ * no-train user earns nothing (untrained zones give no credit).
+ */
+exports.RECOVERY_THRESHOLDS = {
+    1: { targetCycles: 3, windowDays: 56, recoveredBelow: 25 },
+    2: { targetCycles: 5, windowDays: 56, recoveredBelow: 25 },
+    3: { targetCycles: 7, windowDays: 56, recoveredBelow: 25 },
+};
+// --- Level helper -----------------------------------------------------------
+/** Clamp any incoming level into the valid 1..MAX_LEVEL range. */
+function clampLevel(level) {
+    if (!level || level < 1)
+        return 1;
+    if (level > exports.MAX_LEVEL)
+        return exports.MAX_LEVEL;
+    return Math.floor(level);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Star Foundation
+ * ============================================================================
+ *
+ * Shared pure glue. Types come from ./types. Behaviour only:
+ *   - deriveTier:  continuous brightness -> discrete band (0-3)
+ *   - resolveStar: definition + context -> render-ready TResolvedStar
+ */
+import type { TStarTier, TStarDefinition, TStarContext, TResolvedStar } from "./types";
+/** Brightness lower-bounds per tier. Tunable in one place. */
+export declare const TIER_THRESHOLDS: {
+    readonly faint: 1;
+    readonly rising: 34;
+    readonly full: 100;
+};
+/**
+ * 0 dormant (<1) - 1 faint (1-33) - 2 rising (34-99) - 3 full (>=100).
+ */
+export declare function deriveTier(brightness: number): TStarTier;
+/**
+ * Run a star definition through its evaluator into the render-ready shape.
+ * Brightness clamped 0-100 here so evaluators don't each have to.
+ */
+export declare function resolveStar(def: TStarDefinition, ctx: TStarContext): TResolvedStar;

package/dist/utils/constellation/starFoundation.js

@@ -0,0 +1,54 @@
+"use strict";
+// utils/constellation/starFoundation.ts — Star Foundation
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Star Foundation
+ * ============================================================================
+ *
+ * Shared pure glue. Types come from ./types. Behaviour only:
+ *   - deriveTier:  continuous brightness -> discrete band (0-3)
+ *   - resolveStar: definition + context -> render-ready TResolvedStar
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIER_THRESHOLDS = void 0;
+exports.deriveTier = deriveTier;
+exports.resolveStar = resolveStar;
+/** Brightness lower-bounds per tier. Tunable in one place. */
+exports.TIER_THRESHOLDS = {
+    faint: 1,
+    rising: 34,
+    full: 100,
+};
+/**
+ * 0 dormant (<1) - 1 faint (1-33) - 2 rising (34-99) - 3 full (>=100).
+ */
+function deriveTier(brightness) {
+    if (brightness >= exports.TIER_THRESHOLDS.full)
+        return 3;
+    if (brightness >= exports.TIER_THRESHOLDS.rising)
+        return 2;
+    if (brightness >= exports.TIER_THRESHOLDS.faint)
+        return 1;
+    return 0;
+}
+/**
+ * Run a star definition through its evaluator into the render-ready shape.
+ * Brightness clamped 0-100 here so evaluators don't each have to.
+ */
+function resolveStar(def, ctx) {
+    const { brightness, detail } = def.evaluate(ctx);
+    const clamped = Math.max(0, Math.min(100, brightness));
+    return {
+        id: def.id,
+        displayName: def.displayName,
+        color: def.color,
+        figurePosition: def.figurePosition,
+        brightness: clamped,
+        tier: deriveTier(clamped),
+        objective: def.objective,
+        rationale: def.rationale,
+        currentState: detail.currentState,
+        target: detail.target,
+        gap: detail.gap,
+    };
+}