@dgpholdings/greatoak-shared 1.2.85 → 1.2.87

package/dist/utils/constellation/strengthStarHelpers.js

@@ -0,0 +1,104 @@
+"use strict";
+// utils/constellation/strengthStarHelpers.ts — Strength Star Helpers
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Strength Star Helpers
+ * ============================================================================
+ *
+ * Shared by the three strength stars (push, pull, lowerBody). Each star is a
+ * thin definition that names its movement patterns and its threshold key; this
+ * helper does the rest: filter the catalog to those patterns, compute the
+ * normalised load, and turn the ratio into brightness + i18n detail.
+ *
+ * Thresholds come from STRENGTH_THRESHOLDS[key][level], resolved by sex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRENGTH_WINDOW_DAYS = void 0;
+exports.resolveThreshold = resolveThreshold;
+exports.userBodyweight = userBodyweight;
+exports.ratioToBrightness = ratioToBrightness;
+exports.buildGap = buildGap;
+exports.evaluateStrengthStar = evaluateStrengthStar;
+const computeNormalisedLoad_1 = require("./computeNormalisedLoad");
+const levelThresholds_1 = require("./levelThresholds");
+/** Rolling window for strength PRs: 8 weeks. */
+exports.STRENGTH_WINDOW_DAYS = 56;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_BODYWEIGHT_KG = 70;
+/** Resolve the threshold ratio for this user. unmentioned -> male (higher bar). */
+function resolveThreshold(threshold, gender) {
+    return gender === "female" ? threshold.female : threshold.male;
+}
+/** User bodyweight with fallback. */
+function userBodyweight(user) {
+    const bw = user.weightKg;
+    return bw && bw > 0 ? bw : DEFAULT_BODYWEIGHT_KG;
+}
+/**
+ * Brightness from current ratio vs threshold, graded & continuous.
+ *   brightness = (currentRatio / thresholdRatio) * 100, capped at 100.
+ * Faint from the first rep; full at threshold. No wall.
+ */
+function ratioToBrightness(currentRatio, thresholdRatio) {
+    if (thresholdRatio <= 0)
+        return 0;
+    return Math.min(100, (currentRatio / thresholdRatio) * 100);
+}
+/** Build a bodyweight-ratio measure for the detail panel. */
+function bwRatioMeasure(ratio) {
+    const rounded = Math.round(ratio * 100) / 100;
+    return {
+        value: rounded,
+        unit: "bw_ratio",
+        display: {
+            translationKey: "constellation.measure.bwRatio",
+            params: [rounded],
+        },
+    };
+}
+/**
+ * Build the "what's missing" gap text. At/above threshold -> a "full" message;
+ * otherwise the remaining kg on the user's best lift to reach the threshold.
+ */
+function buildGap(gapKeyPrefix, currentRatio, thresholdRatio, bodyweightKg) {
+    if (currentRatio >= thresholdRatio) {
+        return { translationKey: `${gapKeyPrefix}.gap.full` };
+    }
+    const remainingKg = Math.max(0, Math.round((thresholdRatio - currentRatio) * bodyweightKg));
+    return {
+        translationKey: `${gapKeyPrefix}.gap.toGo`,
+        params: [remainingKg],
+    };
+}
+/**
+ * The full strength-star evaluation, shared by push/pull/lowerBody.
+ *
+ * @param ctx               star context (sessions, catalog, user, now, level)
+ * @param strengthKey       which STRENGTH_THRESHOLDS row to use ("push" | "pull" | "lowerBody")
+ * @param matchingPatterns  movement patterns this star counts
+ * @param gapKeyPrefix      translation-key prefix (e.g. "constellation.push")
+ */
+function evaluateStrengthStar(ctx, strengthKey, matchingPatterns, gapKeyPrefix) {
+    const bw = userBodyweight(ctx.user);
+    const gender = ctx.user.gender;
+    const thresholdRatio = resolveThreshold(levelThresholds_1.STRENGTH_THRESHOLDS[strengthKey][ctx.level], gender);
+    // Build the matching-exercise id set from the catalog by movement pattern.
+    const patternSet = new Set(matchingPatterns);
+    const matchingIds = new Set();
+    for (const id of Object.keys(ctx.exerciseCatalog)) {
+        const ex = ctx.exerciseCatalog[id];
+        if (patternSet.has(ex.movementPattern))
+            matchingIds.add(id);
+    }
+    const windowStart = ctx.now - exports.STRENGTH_WINDOW_DAYS * MS_PER_DAY;
+    const load = (0, computeNormalisedLoad_1.computeNormalisedLoad)(matchingIds, ctx.sessions, ctx.exerciseCatalog, bw, gender, windowStart, ctx.now);
+    const brightness = ratioToBrightness(load.ratio, thresholdRatio);
+    return {
+        brightness,
+        detail: {
+            currentState: bwRatioMeasure(load.ratio),
+            target: bwRatioMeasure(thresholdRatio),
+            gap: buildGap(gapKeyPrefix, load.ratio, thresholdRatio, bw),
+        },
+    };
+}

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

@@ -0,0 +1,124 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Model & API Contract
+ * ============================================================================
+ *
+ * Purely live: every value is recomputed from raw records each call. Nothing is
+ * persisted. brightness (0-100) is the only signal; tier is derived from it.
+ *
+ * i18n: all user-facing text is a TLocalizedText ({ translationKey, params }).
+ * Evaluators never emit raw display strings — the client renders the key with
+ * locale-correct formatting. Numeric measures send value + unit only.
+ *
+ * Scoring is computed ONCE by the orchestrator and shared via TStarContext
+ * (scoredSessions), so quality and recovery never re-run the scoring engine.
+ */
+import type { TExercise, TUserMetric, TRecord } from "../../types";
+import type { TLevel } from "./levelThresholds";
+export interface TLocalizedText {
+    translationKey: string;
+    /** Ordered interpolation values, e.g. [10] -> "about {0}kg more". */
+    params?: (string | number)[];
+}
+export type TStarId = "consistency" | "quality" | "push" | "pull" | "lowerBody" | "recovery";
+export type TFigurePosition = "heart" | "core" | "leftArm" | "rightArm" | "base" | "crown";
+/** 0 dormant - 1 faint - 2 rising - 3 full. Derived from brightness. */
+export type TStarTier = 0 | 1 | 2 | 3;
+/** Unit codes a measure can carry. Keep in sync with the client's unit labels. */
+export type TMeasureUnit = "bw_ratio" | "sessions" | "cycles" | "days";
+/**
+ * A numeric measure. The client formats `value` for locale and renders `unit`
+ * via its translation. `display` is a localized template if the unit needs
+ * prose around the number (e.g. "{0} of {1} days"); for plain values the client
+ * may format value+unit directly.
+ */
+export interface TStarMeasure {
+    value: number;
+    unit: TMeasureUnit;
+    display: TLocalizedText;
+}
+export interface TResolvedStar {
+    id: TStarId;
+    displayName: TLocalizedText;
+    color: string;
+    figurePosition: TFigurePosition;
+    brightness: number;
+    tier: TStarTier;
+    objective: TLocalizedText;
+    rationale: TLocalizedText;
+    currentState: TStarMeasure;
+    target: TStarMeasure;
+    gap: TLocalizedText;
+}
+export interface TConstellationFigure {
+    /** 0-100, avg brightness across stars -> aura intensity. */
+    auraIntensity: number;
+    /** Count of stars currently at full brightness (tier 3). */
+    fullStarCount: number;
+}
+export interface TConstellationState {
+    stars: TResolvedStar[];
+    figure: TConstellationFigure;
+    currentLevel: TLevel;
+    evaluatedAt: string;
+}
+export interface TSessionRecord {
+    date: number;
+    exercises: {
+        exerciseId: string;
+        records: TRecord[];
+    }[];
+}
+export interface TConstellationInput {
+    sessions: TSessionRecord[];
+    /** Full catalog - UNFILTERED (incl. inactive). */
+    exerciseCatalog: Record<string, TExercise>;
+    user: Partial<TUserMetric>;
+    now: number;
+    currentLevel?: number;
+}
+/** One exercise within a session, scored once by the orchestrator. */
+export interface TScoredExercise {
+    exerciseId: string;
+    /** Quality score 0-100 from the scoring engine, or null if unscorable. */
+    score: number | null;
+    /** Per-muscle scores (fatigue input), empty if unscorable. */
+    muscleScores: Record<string, number>;
+}
+/** A session with each exercise pre-scored. */
+export interface TScoredSession {
+    date: number;
+    exercises: TScoredExercise[];
+}
+export interface TStarDynamicDetail {
+    currentState: TStarMeasure;
+    target: TStarMeasure;
+    gap: TLocalizedText;
+}
+export interface TStarEvaluation {
+    brightness: number;
+    detail: TStarDynamicDetail;
+}
+/**
+ * Everything a star needs to evaluate. Scoring is pre-computed
+ * (scoredSessions) so quality/recovery don't re-run the engine. Raw sessions
+ * remain available for stars that work off dates/records directly (consistency,
+ * strength).
+ */
+export interface TStarContext {
+    sessions: TSessionRecord[];
+    scoredSessions: TScoredSession[];
+    exerciseCatalog: Record<string, TExercise>;
+    user: Partial<TUserMetric>;
+    now: number;
+    level: TLevel;
+}
+export interface TStarDefinition {
+    id: TStarId;
+    displayName: TLocalizedText;
+    color: string;
+    figurePosition: TFigurePosition;
+    objective: TLocalizedText;
+    rationale: TLocalizedText;
+    evaluate: (ctx: TStarContext) => TStarEvaluation;
+}

package/dist/utils/constellation/types.js

@@ -0,0 +1,18 @@
+"use strict";
+// utils/constellation/types.ts — Model & API Contract
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Model & API Contract
+ * ============================================================================
+ *
+ * Purely live: every value is recomputed from raw records each call. Nothing is
+ * persisted. brightness (0-100) is the only signal; tier is derived from it.
+ *
+ * i18n: all user-facing text is a TLocalizedText ({ translationKey, params }).
+ * Evaluators never emit raw display strings — the client renders the key with
+ * locale-correct formatting. Numeric measures send value + unit only.
+ *
+ * Scoring is computed ONCE by the orchestrator and shared via TStarContext
+ * (scoredSessions), so quality and recovery never re-run the scoring engine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/index.d.ts

@@ -7,9 +7,11 @@ export { toError } from "./toError.util";
 export { generatePlanCode } from "./planCode.util";
 export { maskEmail, isAnonymousEmail, isEmail } from "./email.utils";
 export { NOOP } from "./noop.utils";
-export { calculateExerciseScoreV2, calculateTotalVolume, deriveTrainingAgeBracket, computeMuscleFatigueMap } from "./scoringWorkout";
-export type { IHistoricalContext, TTrainingAgeBracket, TEnrichedSessionScore, TEnrichedExerciseRecord, TMuscleFatigueEntry, TMuscleFatigueResult } from "./scoringWorkout";
-export { scaleProPlan, calculateBMI, calculateDayPlanDuration, calculateExerciseDurationSecs } from "./adoptionEngine/scaleProPlan.util";
+export { calculateExerciseScoreV2, calculateTotalVolume, deriveTrainingAgeBracket, computeMuscleFatigueMap, } from "./scoringWorkout";
+export type { IHistoricalContext, TTrainingAgeBracket, TEnrichedSessionScore, TEnrichedExerciseRecord, TMuscleFatigueEntry, TMuscleFatigueResult, } from "./scoringWorkout";
+export { scaleProPlan, calculateBMI, calculateDayPlanDuration, calculateExerciseDurationSecs, } from "./adoptionEngine/scaleProPlan.util";
 export * from "./exerciseRecord/workoutMath";
 export * from "./exerciseRecord/recordValidator";
 export * from "./metricConversions";
+export * from "./constellation";
+export type * from "./constellation/types";

package/dist/utils/index.js

@@ -51,3 +51,4 @@ Object.defineProperty(exports, "calculateExerciseDurationSecs", { enumerable: tr
 __exportStar(require("./exerciseRecord/workoutMath"), exports);
 __exportStar(require("./exerciseRecord/recordValidator"), exports);
 __exportStar(require("./metricConversions"), exports);
+__exportStar(require("./constellation"), exports);

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

@@ -8,33 +8,54 @@
  * Quality is about execution: did you finish, stay consistent, push hard
  * enough, and rest appropriately?
  *
- * FOUR SUB-COMPONENTS:
+ * THREE ALWAYS-ACTIVE COMPONENTS + ONE CONDITIONAL:
  *
- * ┌─────────────────────┬────────┬──────────────────────────────────────────┐
- * │ Component           │ Weight │ What it measures                         │
- * ├─────────────────────┼────────┼──────────────────────────────────────────┤
- * │ Completion          │  20%   │ Did you finish all planned sets?         │
- * │ Consistency         │  35%   │ Were sets stable or intentionally        │
- * │                     │        │ progressive? (not random drops)          │
- * │ Effort Adequacy     │  30%   │ Were you in the productive effort zone?  │
- * │                     │        │ (RPE 6–9 or RIR 1–4)                     │
- * │ Rest Discipline     │  15%   │ Did you respect optimal rest windows?    │
- * └─────────────────────┴────────┴──────────────────────────────────────────┘
+ * ┌─────────────────────┬────────────┬──────────────────────────────────────────┐
+ * │ Component           │ Base weight│ What it measures                         │
+ * ├─────────────────────┼────────────┼──────────────────────────────────────────┤
+ * │ Completion          │  20%       │ Completed sets / planned sets            │
+ * │ Consistency         │  35%       │ Stable or intentionally progressive sets │
+ * │ Effort Adequacy     │  30%       │ RPE/RIR proximity to productive failure  │
+ * │ Rest Discipline     │  15%       │ Rest periods within optimal windows      │
+ * │  (conditional)      │  or 0%     │ Only scored when rest data exists.       │
+ * │                     │            │ Absent → weight redistributed to others. │
+ * └─────────────────────┴────────────┴──────────────────────────────────────────┘
  *
- * Each sub-component produces 0–100. The final score is a weighted average.
+ * EFFORT SCORING (UPDATED):
+ * RPE/RIR is now captured on EVERY set via the post-set "How did that feel?"
+ * one-tap modal (Warm-up=RPE4 / Challenging=RPE7 / Maximum=RPE9). Because effort
+ * is now always present, scoring is GRADED and MONOTONIC: harder sets score
+ * strictly higher than easier ones, so Gate 2 can distinguish "going through the
+ * motions" from "genuinely training" — which the old flat "in-band = 100" logic
+ * could not (RPE 7 and RPE 9 both scored 100).
  *
- * DESIGN PRINCIPLES:
- * - Motivational: even a mediocre workout should score 40–60, not 10
- * - Honest: perfect scores require real effort and discipline
- * - Fair across types: cardio and strength use the same framework
- * - Transparent: the breakdown is returned so the UI can explain the score
+ *   RPE 9 → 100   RPE 7 → ~81   RPE 4 → ~53   RPE 1 → 25   (floor 20)
+ *   RIR 0 → 100   RIR 3 → 76    RIR 6 → 52    RIR 10 → 20  (floor 20)
+ *
+ * A genuine warm-up-effort working set now drags the score down instead of
+ * floating at a neutral 50 — an "easy on every set" session correctly fails
+ * Gate 2. RIR is preferred over RPE when both are present (more objective).
+ *
+ * REST DISCIPLINE:
+ * Strict timing mode is not implemented in the app, so rest data is absent in
+ * most sessions. When present, rest contributes meaningfully. When absent, the
+ * 15% weight is redistributed proportionally across the three active components
+ * via dynamic normalisation — score cannot be biased by uncollected data.
+ *
+ * EFFORT-WEIGHTED AVERAGING:
+ * Effort adequacy weights the FINAL set most heavily. The last working set is
+ * where adequacy is truly determined — a strong finish (or a sandbagged one)
+ * is the clearest signal of whether the session stimulated adaptation.
+ *
+ * SINGLE SCORE OUTPUT:
+ * Returns one score, not per-goal. Goal-specific progression logic lives in the
+ * gate system and quick plan generator upstream.
  */
-import type { IParsedSet, IUserContext, IHistoricalContext } from "./types";
+import type { IParsedSet, IQualityBreakdown, IHistoricalContext } from "./types";
 import type { ITimingGuardrails } from "./parseRecords";
-import type { TAiFitnessGoal } from "../../constants/AiExerciseVocabulary";
 /**
  * Raw record shape — we need the original RPE/RIR strings and isDone flag
- * that aren't in IParsedSet (which only contains completed sets).
+ * that are not present in IParsedSet (which contains only completed sets).
  */
 interface IRawRecord {
     type: string;
@@ -51,23 +72,25 @@ interface IRawRecord {
     distance?: string;
     restDurationSecs?: number;
 }
+export interface IQualityScoreResult {
+    /** Overall quality score 0–100. */
+    score: number;
+    /** Per-component breakdown — each sub-score is 0–100. */
+    qualityBreakdown: IQualityBreakdown;
+    /**
+     * True when rest discipline was included in the weighted score.
+     * False when no rest data was logged — weight redistributed to other components.
+     * Use this flag to gate the rest discipline bar in the UI.
+     */
+    restDisciplineActive: boolean;
+}
 /**
- * Calculate the overall quality score and its breakdown.
- *
- * @param parsedSets        Cleaned sets (from parseRecords) — only completed sets
- * @param rawRecords        Original TRecord[] — needed for completion count (includes skipped)
- * @param timingGuardrails  Exercise's guardrails — for rest period validation
- * @param isStrictTimingModeScoring If false, ignores the rest discipline penalty.
- * @param userContext       User context for dynamic weighting (P2-3)
- * @param historicalContext Optional history for progressive overload detection (P2-6)
- * @returns                 { score: 0–100, breakdown: { completion, consistency, effortAdequacy, restDiscipline } }
+ * Calculate the overall quality score and its component breakdown.
  *
- * @example
- * const { score, breakdown } = calculateQualityScore(parsed, raw, guardrails, false, userCtx, historyCtx);
- * // score: 81
- * // breakdown: { completion: 100, consistency: 75, effortAdequacy: 80, restDiscipline: 65 }
+ * @param parsedSets        Cleaned completed sets (output of parseRecords)
+ * @param rawRecords        Original TRecord[] — needed for completion count and RPE/RIR
+ * @param timingGuardrails  Exercise DB guardrails — for rest period validation
+ * @param historicalContext Optional cross-session context for overload detection
  */
-export declare function calculateQualityScore(parsedSets: IParsedSet[], rawRecords: IRawRecord[], timingGuardrails: ITimingGuardrails | undefined, isStrictTimingModeScoring: boolean, userContext: IUserContext, historicalContext?: IHistoricalContext): {
-    scoresByGoal: Partial<Record<TAiFitnessGoal, import("./types").IScoreByGoal>>;
-};
+export declare function calculateQualityScore(parsedSets: IParsedSet[], rawRecords: IRawRecord[], timingGuardrails: ITimingGuardrails | undefined, historicalContext?: IHistoricalContext): IQualityScoreResult;
 export {};