@dgpholdings/greatoak-shared 1.2.86 → 1.2.87

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 {};