@dgpholdings/greatoak-shared 1.2.86 → 1.2.88

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/evaluateConstellation.test.ts
+const evaluateConstellation_1 = require("./evaluateConstellation");
+const vitest_1 = require("vitest");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+const wr = (kg, reps) => ({ type: "weight-reps", kg, reps, isDone: true, isStrictMode: false });
+const catalog = {
+    bench: {
+        exerciseId: "bench",
+        name: "Bench",
+        primaryMuscles: ["pectoralis-major"],
+        secondaryMuscles: [],
+        difficultyLevel: 3,
+        movementPattern: "push_horizontal",
+        status: "active",
+    },
+};
+const baseInput = (over = {}) => ({
+    sessions: [
+        {
+            date: day(2),
+            exercises: [{ exerciseId: "bench", records: [wr("60", "5")] }],
+        },
+    ],
+    exerciseCatalog: catalog,
+    user: { weightKg: 80, gender: "male" },
+    now: NOW,
+    ...over,
+});
+(0, vitest_1.describe)("orchestrator — now guard", () => {
+    (0, vitest_1.it)("throws on NaN now", () => {
+        (0, vitest_1.expect)(() => (0, evaluateConstellation_1.evaluateConstellation)(baseInput({ now: NaN }))).toThrow();
+    });
+    (0, vitest_1.it)("throws on Infinity now", () => {
+        (0, vitest_1.expect)(() => (0, evaluateConstellation_1.evaluateConstellation)(baseInput({ now: Infinity }))).toThrow();
+    });
+    (0, vitest_1.it)("accepts a finite now", () => {
+        (0, vitest_1.expect)((0, evaluateConstellation_1.evaluateConstellation)(baseInput()).stars).toHaveLength(6);
+    });
+});
+(0, vitest_1.describe)("orchestrator — shape & aggregate", () => {
+    (0, vitest_1.it)("returns six stars and a figure", () => {
+        const s = (0, evaluateConstellation_1.evaluateConstellation)(baseInput());
+        (0, vitest_1.expect)(s.stars).toHaveLength(6);
+        (0, vitest_1.expect)(s.figure.auraIntensity).toBeGreaterThanOrEqual(0);
+        (0, vitest_1.expect)(s.figure.auraIntensity).toBeLessThanOrEqual(100);
+    });
+    (0, vitest_1.it)("auraIntensity equals the mean star brightness", () => {
+        const s = (0, evaluateConstellation_1.evaluateConstellation)(baseInput());
+        const mean = s.stars.reduce((a, x) => a + x.brightness, 0) / s.stars.length;
+        (0, vitest_1.expect)(s.figure.auraIntensity).toBeCloseTo(Math.round(mean * 10) / 10, 1);
+    });
+    (0, vitest_1.it)("fullStarCount matches tier-3 stars", () => {
+        const s = (0, evaluateConstellation_1.evaluateConstellation)(baseInput());
+        const full = s.stars.filter((x) => x.tier === 3).length;
+        (0, vitest_1.expect)(s.figure.fullStarCount).toBe(full);
+    });
+    (0, vitest_1.it)("evaluatedAt is the ISO of now", () => {
+        const s = (0, evaluateConstellation_1.evaluateConstellation)(baseInput());
+        (0, vitest_1.expect)(s.evaluatedAt).toBe(new Date(NOW).toISOString());
+    });
+});
+(0, vitest_1.describe)("orchestrator — level clamping", () => {
+    (0, vitest_1.it)("undefined level → 1", () => (0, vitest_1.expect)((0, evaluateConstellation_1.evaluateConstellation)(baseInput()).currentLevel).toBe(1));
+    (0, vitest_1.it)("out-of-range level → clamped to 3", () => (0, vitest_1.expect)((0, evaluateConstellation_1.evaluateConstellation)(baseInput({ currentLevel: 99 })).currentLevel).toBe(3));
+    (0, vitest_1.it)("level 2 echoed", () => (0, vitest_1.expect)((0, evaluateConstellation_1.evaluateConstellation)(baseInput({ currentLevel: 2 })).currentLevel).toBe(2));
+});
+(0, vitest_1.describe)("orchestrator — future sessions excluded from scoring", () => {
+    (0, vitest_1.it)("a session dated after now does not light push", () => {
+        const future = (0, evaluateConstellation_1.evaluateConstellation)(baseInput({
+            sessions: [
+                {
+                    date: NOW + 86400000,
+                    exercises: [{ exerciseId: "bench", records: [wr("100", "5")] }],
+                },
+            ],
+        }));
+        (0, vitest_1.expect)(future.stars.find((s) => s.id === "push").brightness).toBe(0);
+    });
+    (0, vitest_1.it)("a present session does light push (control)", () => {
+        (0, vitest_1.expect)((0, evaluateConstellation_1.evaluateConstellation)(baseInput()).stars.find((s) => s.id === "push")
+            .brightness).toBeGreaterThan(0);
+    });
+});
+(0, vitest_1.describe)("orchestrator — empty input is safe", () => {
+    (0, vitest_1.it)("no sessions → all stars resolve, none throw", () => {
+        const s = (0, evaluateConstellation_1.evaluateConstellation)(baseInput({ sessions: [] }));
+        (0, vitest_1.expect)(s.stars).toHaveLength(6);
+        (0, vitest_1.expect)(s.stars.every((x) => Number.isFinite(x.brightness))).toBe(true);
+    });
+});

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

@@ -0,0 +1,18 @@
+/**
+ * ============================================================================
+ * 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";
+export { MAX_LEVEL as CONSTELLATION_USER_MAX_LEVEL, clampLevel as constellationClampLevel, type TLevel as TConstellationUserLevel, } from "./levelThresholds";

package/dist/utils/constellation/index.js

@@ -0,0 +1,29 @@
+"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.constellationClampLevel = exports.CONSTELLATION_USER_MAX_LEVEL = 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; } });
+var levelThresholds_1 = require("./levelThresholds");
+Object.defineProperty(exports, "CONSTELLATION_USER_MAX_LEVEL", { enumerable: true, get: function () { return levelThresholds_1.MAX_LEVEL; } });
+Object.defineProperty(exports, "constellationClampLevel", { enumerable: true, get: function () { return levelThresholds_1.clampLevel; } });

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,
+    };
+}

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

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

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/starFoundation.test.ts
+const starFoundation_1 = require("./starFoundation");
+const levelThresholds_1 = require("./levelThresholds");
+const vitest_1 = require("vitest");
+(0, vitest_1.describe)("deriveTier — brightness band boundaries", () => {
+    (0, vitest_1.it)("0 brightness → tier 0 (dormant)", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(0)).toBe(0));
+    (0, vitest_1.it)("just below faint (0.9) → tier 0", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(0.9)).toBe(0));
+    (0, vitest_1.it)("exactly faint (1) → tier 1", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(1)).toBe(1));
+    (0, vitest_1.it)("mid faint (33) → tier 1", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(33)).toBe(1));
+    (0, vitest_1.it)("exactly rising (34) → tier 2", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(34)).toBe(2));
+    (0, vitest_1.it)("just below full (99) → tier 2", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(99)).toBe(2));
+    (0, vitest_1.it)("exactly full (100) → tier 3", () => (0, vitest_1.expect)((0, starFoundation_1.deriveTier)(100)).toBe(3));
+    (0, vitest_1.it)("thresholds are the documented values", () => {
+        (0, vitest_1.expect)(starFoundation_1.TIER_THRESHOLDS.faint).toBe(1);
+        (0, vitest_1.expect)(starFoundation_1.TIER_THRESHOLDS.rising).toBe(34);
+        (0, vitest_1.expect)(starFoundation_1.TIER_THRESHOLDS.full).toBe(100);
+    });
+});
+(0, vitest_1.describe)("resolveStar — clamps brightness and packages output", () => {
+    const ctx = {};
+    const make = (brightness) => ({
+        id: "push",
+        displayName: { translationKey: "constellation.push.name" },
+        color: "#fff",
+        figurePosition: "leftArm",
+        objective: { translationKey: "constellation.push.objective" },
+        rationale: { translationKey: "constellation.push.rationale" },
+        evaluate: () => ({
+            brightness,
+            detail: {
+                currentState: {
+                    value: 0,
+                    unit: "bw_ratio",
+                    display: { translationKey: "x" },
+                },
+                target: {
+                    value: 1,
+                    unit: "bw_ratio",
+                    display: { translationKey: "x" },
+                },
+                gap: { translationKey: "g" },
+            },
+        }),
+    });
+    (0, vitest_1.it)("clamps brightness > 100 down to 100", () => {
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(make(150), ctx).brightness).toBe(100);
+    });
+    (0, vitest_1.it)("clamps negative brightness up to 0", () => {
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(make(-20), ctx).brightness).toBe(0);
+    });
+    (0, vitest_1.it)("derives tier from the clamped value", () => {
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(make(150), ctx).tier).toBe(3);
+        (0, vitest_1.expect)((0, starFoundation_1.resolveStar)(make(-20), ctx).tier).toBe(0);
+    });
+    (0, vitest_1.it)("passes through identity + i18n fields unchanged", () => {
+        const r = (0, starFoundation_1.resolveStar)(make(50), ctx);
+        (0, vitest_1.expect)(r.id).toBe("push");
+        (0, vitest_1.expect)(r.figurePosition).toBe("leftArm");
+        (0, vitest_1.expect)(r.displayName.translationKey).toBe("constellation.push.name");
+    });
+});
+(0, vitest_1.describe)("clampLevel — valid level range", () => {
+    (0, vitest_1.it)("undefined → 1", () => (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(undefined)).toBe(1));
+    (0, vitest_1.it)("0 → 1", () => (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(0)).toBe(1));
+    (0, vitest_1.it)("negative → 1", () => (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(-3)).toBe(1));
+    (0, vitest_1.it)("1/2/3 pass through", () => {
+        (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(1)).toBe(1);
+        (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(2)).toBe(2);
+        (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(3)).toBe(3);
+    });
+    (0, vitest_1.it)("above max → 3", () => (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(99)).toBe(3));
+    (0, vitest_1.it)("fractional floored", () => (0, vitest_1.expect)((0, levelThresholds_1.clampLevel)(2.7)).toBe(2));
+});

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

@@ -0,0 +1,29 @@
+/**
+ * ============================================================================
+ * 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].
+ */
+import type { TStarDefinition } from "../types";
+export declare const consistencyStar: TStarDefinition;