volleyballsimtypes 0.0.359 → 0.0.361

package/dist/cjs/src/service/match/schemas/match.z.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatchInputSchema = void 0;
+const zod_1 = require("zod");
+const team_1 = require("../../team");
+const common_1 = require("../../../data/common");
+const match_set_1 = require("../match-set");
+const vper_1 = require("../vper");
+const teamSchema = zod_1.z.custom((v) => v instanceof team_1.Team, {
+    message: 'INVALID_TEAM_INSTANCE'
+});
+exports.MatchInputSchema = zod_1.z.object({
+    id: zod_1.z.uuid(),
+    homeTeam: teamSchema,
+    awayTeam: teamSchema,
+    scheduledDate: zod_1.z.coerce.date(),
+    status: zod_1.z.enum(Object.values(common_1.StatusEnum)),
+    sets: zod_1.z.array(zod_1.z.custom((v) => v instanceof match_set_1.MatchSet, {
+        message: 'INVALID_MATCH_SET_INSTANCE'
+    })).optional(),
+    VPERs: zod_1.z.array(zod_1.z.custom((v) => v instanceof vper_1.VPER, {
+        message: 'INVALID_VPER_INSTANCE'
+    })).optional(),
+    homeScore: zod_1.z.number().int().optional(),
+    awayScore: zod_1.z.number().int().optional(),
+    winner: teamSchema.optional()
+}).superRefine((data, ctx) => {
+    if (data.homeTeam.id === data.awayTeam.id) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'HOME_AND_AWAY_TEAM_CANNOT_BE_EQUAL',
+            path: ['awayTeam', 'id']
+        });
+    }
+    if (data.sets !== undefined) {
+        const n = data.sets.length;
+        if (n !== 0 && (n < 3 || n > 5)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'SETS_LENGTH_MUST_BE_0_OR_BETWEEN_3_AND_5',
+                path: ['sets']
+            });
+        }
+        if (n > 0 && data.status !== common_1.StatusEnum.COMPLETE) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'NON_EMPTY_SETS_REQUIRE_COMPLETE_MATCH',
+                path: ['sets']
+            });
+        }
+    }
+    const { status, homeScore, awayScore } = data;
+    if (status !== common_1.StatusEnum.COMPLETE) {
+        if (homeScore !== undefined && homeScore !== 0) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'HOME_SCORE_MUST_BE_0_WHEN_UNFINISHED',
+                path: ['homeScore']
+            });
+        }
+        if (awayScore !== undefined && awayScore !== 0) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'AWAY_SCORE_MUST_BE_0_WHEN_UNFINISHED',
+                path: ['awayScore']
+            });
+        }
+        return;
+    }
+    if (homeScore === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'HOME_SCORE_REQUIRED_WHEN_COMPLETE',
+            path: ['homeScore']
+        });
+    }
+    if (awayScore === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'AWAY_SCORE_REQUIRED_WHEN_COMPLETE',
+            path: ['awayScore']
+        });
+    }
+    if (homeScore === undefined || awayScore === undefined)
+        return;
+    if (homeScore < 0 || homeScore > 3) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'HOME_SCORE_OUT_OF_RANGE',
+            path: ['homeScore']
+        });
+    }
+    if (awayScore < 0 || awayScore > 3) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'AWAY_SCORE_OUT_OF_RANGE',
+            path: ['awayScore']
+        });
+    }
+    if (homeScore !== 3 && awayScore !== 3) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'MATCH_COMPLETE_REQUIRES_A_TEAM_TO_HAVE_3_SETS',
+            path: []
+        });
+    }
+});

package/dist/cjs/src/service/match/schemas/rally.z.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { RallyEvent } from '../../event';
+export declare const RallyInputSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    order: z.ZodNumber;
+    servingTeamId: z.ZodUUID;
+    events: z.ZodArray<z.ZodCustom<RallyEvent, RallyEvent>>;
+}, z.core.$strip>;
+export type RallyInput = z.infer<typeof RallyInputSchema>;

package/dist/cjs/src/service/match/schemas/rally.z.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RallyInputSchema = void 0;
+const zod_1 = require("zod");
+const event_1 = require("../../event");
+const nonNegInt = zod_1.z.number().int().min(0);
+exports.RallyInputSchema = zod_1.z.object({
+    id: zod_1.z.uuid(),
+    order: nonNegInt,
+    servingTeamId: zod_1.z.uuid(),
+    events: zod_1.z.array(zod_1.z.custom((v) => v instanceof event_1.RallyEvent, {
+        message: 'INVALID_RALLY_EVENT_INSTANCE'
+    }))
+});

package/dist/cjs/src/service/match/schemas/vper.z.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const VPERInputSchema: z.ZodObject<{
+    playerId: z.ZodUUID;
+    matchId: z.ZodUUID;
+    value: z.ZodNumber;
+}, z.core.$strip>;
+export type VPERInput = z.infer<typeof VPERInputSchema>;

package/dist/cjs/src/service/match/schemas/vper.z.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VPERInputSchema = void 0;
+const zod_1 = require("zod");
+exports.VPERInputSchema = zod_1.z.object({
+    playerId: zod_1.z.uuid(),
+    matchId: zod_1.z.uuid(),
+    value: zod_1.z.number().finite()
+});

package/dist/cjs/src/service/match/vper.d.ts

@@ -0,0 +1,14 @@
+import { BoxScore } from './box-score';
+export interface VPERParams {
+    readonly playerId: string;
+    readonly matchId: string;
+    readonly value: number;
+}
+export declare class VPER {
+    readonly playerId: string;
+    readonly matchId: string;
+    readonly value: number;
+    static create(input: unknown): VPER;
+    private constructor();
+    static computeVPERForMatch(boxScores: BoxScore[]): number;
+}

package/dist/cjs/src/service/match/vper.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VPER = void 0;
+const vper_z_1 = require("./schemas/vper.z");
+const WEIGHTS = {
+    // terminal positive
+    ATTACK_KILL: 1.0,
+    SERVE_ACE: 1.0,
+    BLOCK_SOLO: 1.0,
+    BLOCK_ASSIST: 0.5,
+    // creation / continuation
+    SETTING_ASSIST: 0.7,
+    BLOCK_TOUCH: 0.2,
+    DEFENSE_DIG: 0.25,
+    SETTING_PASS: 0.15,
+    // reception quality
+    RECEPTION_PERFECT: 0.35,
+    RECEPTION_POSITIVE: 0.15,
+    RECEPTION_OVERPASS: -0.6,
+    // terminal errors (always point against)
+    TERMINAL_ERROR: -1.0
+};
+class VPER {
+    static create(input) {
+        const result = vper_z_1.VPERInputSchema.safeParse(input);
+        if (!result.success) {
+            throw new Error(`INVALID_VPER: ${result.error.message}. RECEIVED=${(() => { try {
+                return JSON.stringify(input);
+            }
+            catch {
+                return String(input);
+            } })()}`);
+        }
+        return new VPER(result.data);
+    }
+    constructor({ playerId, matchId, value }) {
+        this.matchId = matchId;
+        this.playerId = playerId;
+        this.value = value;
+    }
+    static computeVPERForMatch(boxScores) {
+        let rawSum = 0;
+        let pointsPlayedSum = 0;
+        for (const box of boxScores) {
+            const w = WEIGHTS;
+            const positive = w.ATTACK_KILL * box.attack.kills +
+                w.SERVE_ACE * box.serve.aces +
+                w.BLOCK_SOLO * box.block.solo +
+                w.BLOCK_ASSIST * box.block.assists +
+                w.SETTING_ASSIST * box.setting.assists +
+                w.BLOCK_TOUCH * box.block.touches +
+                w.DEFENSE_DIG * box.defense.digs +
+                w.SETTING_PASS * box.setting.pass +
+                w.RECEPTION_PERFECT * box.reception.perfect +
+                w.RECEPTION_POSITIVE * box.reception.positive;
+            const negative = w.RECEPTION_OVERPASS * box.reception.overpasses +
+                w.TERMINAL_ERROR * (box.attack.errors +
+                    box.serve.errors +
+                    box.reception.errors +
+                    box.defense.errors +
+                    box.block.errors +
+                    box.setting.errors);
+            rawSum += positive + negative;
+            pointsPlayedSum += box.misc.pointsPlayed;
+        }
+        return 100 * rawSum / Math.max(1, pointsPlayedSum);
+    }
+}
+exports.VPER = VPER;

package/dist/cjs/src/service/match/vper.test.d.ts

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

package/dist/cjs/src/service/match/vper.test.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const uuid_1 = require("uuid");
+const vper_1 = require("./vper");
+const box_score_1 = require("./box-score");
+// ─── helpers ─────────────────────────────────────────────────────────────────
+function makeBox() {
+    return box_score_1.BoxScore.createEmptyBoxScore((0, uuid_1.v4)(), (0, uuid_1.v4)());
+}
+// ─── VPER.computeVPERForMatch ─────────────────────────────────────────────────
+(0, globals_1.describe)('VPER.computeVPERForMatch()', () => {
+    (0, globals_1.it)('returns 0 when box score list is empty', () => {
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([])).toBe(0);
+    });
+    (0, globals_1.it)('returns 0 for a single all-zero box score', () => {
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([makeBox()])).toBe(0);
+    });
+    (0, globals_1.it)('uses max(1, pointsPlayed) to avoid division by zero', () => {
+        const box = makeBox();
+        box.attack.kills = 1;
+        // pointsPlayed remains 0 → denominator becomes 1
+        // 100 * 1.0 / 1 = 100
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(100, 5);
+    });
+    (0, globals_1.it)('returns positive value for attack kills (weight 1.0)', () => {
+        const box = makeBox();
+        box.attack.kills = 5;
+        box.misc.pointsPlayed = 10;
+        // 100 * 5 / 10 = 50
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(50, 5);
+    });
+    (0, globals_1.it)('returns positive value for serve aces (weight 1.0)', () => {
+        const box = makeBox();
+        box.serve.aces = 4;
+        box.misc.pointsPlayed = 10;
+        // 100 * 4 / 10 = 40
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(40, 5);
+    });
+    (0, globals_1.it)('returns positive value for solo blocks (weight 1.0)', () => {
+        const box = makeBox();
+        box.block.solo = 3;
+        box.misc.pointsPlayed = 10;
+        // 100 * 3 / 10 = 30
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(30, 5);
+    });
+    (0, globals_1.it)('returns positive value for block assists (weight 0.5)', () => {
+        const box = makeBox();
+        box.block.assists = 4;
+        box.misc.pointsPlayed = 10;
+        // 100 * (4 * 0.5) / 10 = 20
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(20, 5);
+    });
+    (0, globals_1.it)('returns positive value for setting assists (weight 0.7)', () => {
+        const box = makeBox();
+        box.setting.assists = 10;
+        box.misc.pointsPlayed = 10;
+        // 100 * 7 / 10 = 70
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(70, 5);
+    });
+    (0, globals_1.it)('penalises terminal errors at weight -1.0 each', () => {
+        const box = makeBox();
+        box.attack.errors = 3;
+        box.misc.pointsPlayed = 10;
+        // 100 * (-3) / 10 = -30
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(-30, 5);
+    });
+    (0, globals_1.it)('penalises overpasses at weight -0.6 each', () => {
+        const box = makeBox();
+        box.reception.overpasses = 5;
+        box.misc.pointsPlayed = 10;
+        // 100 * (5 * -0.6) / 10 = -30
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(-30, 5);
+    });
+    (0, globals_1.it)('combines all types of contributions across a single box score', () => {
+        const box = makeBox();
+        box.attack.kills = 10; // +10
+        box.serve.errors = 2; // -2
+        box.setting.assists = 5; // +3.5
+        box.misc.pointsPlayed = 20;
+        // rawSum = 10 - 2 + 3.5 = 11.5; 100 * 11.5 / 20 = 57.5
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(57.5, 5);
+    });
+    (0, globals_1.it)('aggregates rawSum and pointsPlayed across multiple box scores', () => {
+        const box1 = makeBox();
+        box1.attack.kills = 10;
+        box1.misc.pointsPlayed = 20;
+        const box2 = makeBox();
+        box2.serve.errors = 2;
+        box2.misc.pointsPlayed = 10;
+        // rawSum = 10 - 2 = 8; pointsPlayedSum = 30; 100 * 8 / 30 ≈ 26.667
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box1, box2])).toBeCloseTo(26.667, 2);
+    });
+    (0, globals_1.it)('rewards defense digs (weight 0.25)', () => {
+        const box = makeBox();
+        box.defense.digs = 8;
+        box.misc.pointsPlayed = 10;
+        // 100 * (8 * 0.25) / 10 = 20
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(20, 5);
+    });
+    (0, globals_1.it)('rewards perfect receptions (weight 0.35)', () => {
+        const box = makeBox();
+        box.reception.perfect = 4;
+        box.misc.pointsPlayed = 10;
+        // 100 * (4 * 0.35) / 10 = 14
+        (0, globals_1.expect)(vper_1.VPER.computeVPERForMatch([box])).toBeCloseTo(14, 5);
+    });
+});

package/dist/cjs/src/service/player/decline.d.ts

@@ -0,0 +1,43 @@
+import { PerformanceStatsKey } from './performance-stats-keys';
+export declare enum DeclineProfileEnum {
+    PRODIGY = "PRODIGY",
+    STANDARD = "STANDARD",
+    VETERAN = "VETERAN",
+    IRONMAN = "IRONMAN"
+}
+export type DeclineProfile = DeclineProfileEnum.PRODIGY | DeclineProfileEnum.STANDARD | DeclineProfileEnum.VETERAN | DeclineProfileEnum.IRONMAN;
+export declare const declineProfiles: DeclineProfileEnum[];
+interface DeclineProfileEntry {
+    profile: string;
+    startAge: number;
+    initTicks: number;
+    accel: number;
+    peakTicks: number;
+}
+/**
+ * Stats that decline first (technique / skill). One random stat from this pool is
+ * removed per tick during the pre-peak decline phase.
+ */
+export declare const SKILL_POOL: PerformanceStatsKey[];
+/**
+ * Energy / reaction stats (incl. crit-chance stats). These only start declining
+ * once the player reaches peak decline, alongside the skill pool.
+ */
+export declare const ENERGY_POOL: PerformanceStatsKey[];
+export declare function getDeclineProfile(profile: DeclineProfile): DeclineProfileEntry;
+export type DeclineStatus = 'ACTIVE' | 'DECLINING' | 'PEAK';
+export interface DeclineTick {
+    /** Number of decline ticks to apply this iteration. */
+    ticks: number;
+    /** True once tick rate hits the profile ceiling — both pools decline and training is blocked. */
+    atPeak: boolean;
+    /** Coarse status for display / gating. */
+    status: DeclineStatus;
+}
+/**
+ * Decline is fully derivable from age + profile — no running state is persisted.
+ *   tickRate = min(peakTicks, initTicks + (age - startAge) * accel)
+ * Pre-peak: `ticks` random SKILL stats lost. At peak: `ticks` from BOTH pools + training blocked.
+ */
+export declare function computeDeclineTick(age: number, profile: DeclineProfile): DeclineTick;
+export {};

package/dist/cjs/src/service/player/decline.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENERGY_POOL = exports.SKILL_POOL = exports.declineProfiles = exports.DeclineProfileEnum = void 0;
+exports.getDeclineProfile = getDeclineProfile;
+exports.computeDeclineTick = computeDeclineTick;
+const stat_config_1 = require("../../stat-config");
+var DeclineProfileEnum;
+(function (DeclineProfileEnum) {
+    DeclineProfileEnum["PRODIGY"] = "PRODIGY";
+    DeclineProfileEnum["STANDARD"] = "STANDARD";
+    DeclineProfileEnum["VETERAN"] = "VETERAN";
+    DeclineProfileEnum["IRONMAN"] = "IRONMAN";
+})(DeclineProfileEnum || (exports.DeclineProfileEnum = DeclineProfileEnum = {}));
+exports.declineProfiles = Object.values(DeclineProfileEnum);
+const profileEntries = stat_config_1.declineProfilesJSON;
+/**
+ * Stats that decline first (technique / skill). One random stat from this pool is
+ * removed per tick during the pre-peak decline phase.
+ */
+exports.SKILL_POOL = [
+    'setting', 'serve', 'spike', 'quick', 'power', 'backAttack',
+    'reception', 'overhand', 'bump', 'block', 'attack', 'defense'
+];
+/**
+ * Energy / reaction stats (incl. crit-chance stats). These only start declining
+ * once the player reaches peak decline, alongside the skill pool.
+ */
+exports.ENERGY_POOL = [
+    'stamina', 'reflex', 'read', 'commit', 'awareness', 'focus'
+];
+function getDeclineProfile(profile) {
+    const entry = profileEntries.find(e => e.profile === profile);
+    if (entry == null)
+        throw new Error(`UNKNOWN_DECLINE_PROFILE: ${profile}`);
+    return entry;
+}
+/**
+ * Decline is fully derivable from age + profile — no running state is persisted.
+ *   tickRate = min(peakTicks, initTicks + (age - startAge) * accel)
+ * Pre-peak: `ticks` random SKILL stats lost. At peak: `ticks` from BOTH pools + training blocked.
+ */
+function computeDeclineTick(age, profile) {
+    const { startAge, initTicks, accel, peakTicks } = getDeclineProfile(profile);
+    if (age < startAge) {
+        return { ticks: 0, atPeak: false, status: 'ACTIVE' };
+    }
+    const rawRate = initTicks + (age - startAge) * accel;
+    const tickRate = Math.min(peakTicks, rawRate);
+    const atPeak = rawRate >= peakTicks;
+    return {
+        ticks: Math.round(tickRate),
+        atPeak,
+        status: atPeak ? 'PEAK' : 'DECLINING'
+    };
+}

package/dist/cjs/src/service/player/decline.test.d.ts

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

package/dist/cjs/src/service/player/decline.test.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const decline_1 = require("./decline");
+const performance_stats_keys_1 = require("./performance-stats-keys");
+// ─── getDeclineProfile ─────────────────────────────────────────────────────────
+(0, globals_1.describe)('getDeclineProfile()', () => {
+    globals_1.it.each([
+        [decline_1.DeclineProfileEnum.PRODIGY, 27, 13.0, 1.0, 16.0],
+        [decline_1.DeclineProfileEnum.STANDARD, 29, 9.0, 1.75, 16.0],
+        [decline_1.DeclineProfileEnum.VETERAN, 32, 10.0, 1.5, 16.0],
+        [decline_1.DeclineProfileEnum.IRONMAN, 34, 10.0, 1.5, 16.0]
+    ])('%s → startAge %i', (profile, startAge, initTicks, accel, peakTicks) => {
+        const entry = (0, decline_1.getDeclineProfile)(profile);
+        (0, globals_1.expect)(entry.startAge).toBe(startAge);
+        (0, globals_1.expect)(entry.initTicks).toBeCloseTo(initTicks, 5);
+        (0, globals_1.expect)(entry.accel).toBeCloseTo(accel, 5);
+        (0, globals_1.expect)(entry.peakTicks).toBeCloseTo(peakTicks, 5);
+    });
+    (0, globals_1.it)('throws UNKNOWN_DECLINE_PROFILE for an unrecognised profile', () => {
+        (0, globals_1.expect)(() => (0, decline_1.getDeclineProfile)('LEGEND')).toThrow('UNKNOWN_DECLINE_PROFILE');
+    });
+    (0, globals_1.it)('declineProfiles lists all four enum values', () => {
+        (0, globals_1.expect)([...decline_1.declineProfiles].sort()).toEqual([...Object.values(decline_1.DeclineProfileEnum)].sort());
+    });
+});
+// ─── stat pools ────────────────────────────────────────────────────────────────
+(0, globals_1.describe)('decline stat pools', () => {
+    (0, globals_1.it)('SKILL_POOL and ENERGY_POOL are disjoint', () => {
+        const overlap = decline_1.SKILL_POOL.filter(k => decline_1.ENERGY_POOL.includes(k));
+        (0, globals_1.expect)(overlap).toEqual([]);
+    });
+    (0, globals_1.it)('together they cover every performance stat key exactly once', () => {
+        const union = [...decline_1.SKILL_POOL, ...decline_1.ENERGY_POOL].sort();
+        (0, globals_1.expect)(union).toEqual([...performance_stats_keys_1.performanceStatKeys].sort());
+    });
+    (0, globals_1.it)('ENERGY_POOL holds the reaction/energy stats (incl. crit-chance stats)', () => {
+        (0, globals_1.expect)([...decline_1.ENERGY_POOL].sort()).toEqual(['awareness', 'commit', 'focus', 'read', 'reflex', 'stamina'].sort());
+    });
+});
+// ─── computeDeclineTick ────────────────────────────────────────────────────────
+(0, globals_1.describe)('computeDeclineTick()', () => {
+    (0, globals_1.it)('returns no decline before the profile start age', () => {
+        for (const profile of decline_1.declineProfiles) {
+            const { startAge } = (0, decline_1.getDeclineProfile)(profile);
+            const tick = (0, decline_1.computeDeclineTick)(startAge - 1, profile);
+            (0, globals_1.expect)(tick.ticks).toBe(0);
+            (0, globals_1.expect)(tick.atPeak).toBe(false);
+            (0, globals_1.expect)(tick.status).toBe('ACTIVE');
+        }
+    });
+    (0, globals_1.it)('at the start age, tick rate equals round(initTicks) and status is DECLINING', () => {
+        for (const profile of decline_1.declineProfiles) {
+            const { startAge, initTicks } = (0, decline_1.getDeclineProfile)(profile);
+            const tick = (0, decline_1.computeDeclineTick)(startAge, profile);
+            (0, globals_1.expect)(tick.ticks).toBe(Math.round(initTicks));
+            (0, globals_1.expect)(tick.atPeak).toBe(false);
+            (0, globals_1.expect)(tick.status).toBe('DECLINING');
+        }
+    });
+    (0, globals_1.it)('tick count is non-decreasing as age increases', () => {
+        for (const profile of decline_1.declineProfiles) {
+            const { startAge } = (0, decline_1.getDeclineProfile)(profile);
+            let prev = -1;
+            for (let age = startAge; age <= startAge + 30; age++) {
+                const { ticks } = (0, decline_1.computeDeclineTick)(age, profile);
+                (0, globals_1.expect)(ticks).toBeGreaterThanOrEqual(prev);
+                prev = ticks;
+            }
+        }
+    });
+    (0, globals_1.it)('never exceeds peakTicks, and reaching it flips atPeak / PEAK', () => {
+        for (const profile of decline_1.declineProfiles) {
+            const { startAge, peakTicks } = (0, decline_1.getDeclineProfile)(profile);
+            for (let age = startAge; age <= startAge + 40; age++) {
+                const tick = (0, decline_1.computeDeclineTick)(age, profile);
+                (0, globals_1.expect)(tick.ticks).toBeLessThanOrEqual(Math.round(peakTicks));
+                if (tick.atPeak) {
+                    (0, globals_1.expect)(tick.ticks).toBe(Math.round(peakTicks));
+                    (0, globals_1.expect)(tick.status).toBe('PEAK');
+                }
+            }
+        }
+    });
+    (0, globals_1.it)('peak triggers at the analytically expected age for each profile', () => {
+        // age at peak = startAge + ceil((peakTicks - initTicks) / accel)
+        for (const profile of decline_1.declineProfiles) {
+            const { startAge, initTicks, accel, peakTicks } = (0, decline_1.getDeclineProfile)(profile);
+            const peakAge = startAge + Math.ceil((peakTicks - initTicks) / accel);
+            (0, globals_1.expect)((0, decline_1.computeDeclineTick)(peakAge - 1, profile).atPeak).toBe(false);
+            (0, globals_1.expect)((0, decline_1.computeDeclineTick)(peakAge, profile).atPeak).toBe(true);
+        }
+    });
+    (0, globals_1.it)('Standard profile matches the validated model at key ages', () => {
+        // initTicks 9, accel 1.75, peakTicks 16, startAge 29
+        (0, globals_1.expect)((0, decline_1.computeDeclineTick)(28, decline_1.DeclineProfileEnum.STANDARD)).toEqual({ ticks: 0, atPeak: false, status: 'ACTIVE' });
+        (0, globals_1.expect)((0, decline_1.computeDeclineTick)(29, decline_1.DeclineProfileEnum.STANDARD).ticks).toBe(9);
+        (0, globals_1.expect)((0, decline_1.computeDeclineTick)(30, decline_1.DeclineProfileEnum.STANDARD).ticks).toBe(Math.round(9 + 1.75)); // 11
+        // 9 + 4*1.75 = 16 → peak at age 33
+        (0, globals_1.expect)((0, decline_1.computeDeclineTick)(33, decline_1.DeclineProfileEnum.STANDARD).atPeak).toBe(true);
+    });
+});

package/dist/cjs/src/service/player/improvement.d.ts

@@ -0,0 +1,8 @@
+import { Rarity } from './rarity';
+import { Stats } from './stats';
+export type TrainingFocus = Stats;
+export declare function getStatCap(rarity: Rarity): number;
+export declare function getRarityMultiplier(rarity: Rarity): number;
+export declare function getImprovementThreshold(statTotal: number, rarity: Rarity): number;
+export declare function getCoachMultiplier(rarity: Rarity): number;
+export declare function selectImprovableStat(rarity: Rarity, trainingFocus: TrainingFocus, currentStats: Record<string, number>): string | null;

package/dist/cjs/src/service/player/improvement.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStatCap = getStatCap;
+exports.getRarityMultiplier = getRarityMultiplier;
+exports.getImprovementThreshold = getImprovementThreshold;
+exports.getCoachMultiplier = getCoachMultiplier;
+exports.selectImprovableStat = selectImprovableStat;
+const stat_config_1 = require("../../stat-config");
+const rarity_1 = require("./rarity");
+const performance_stats_1 = require("./performance-stats");
+const stats_1 = require("./stats");
+const CURVE_BASE = 100;
+const CURVE_SCALAR = 0.098;
+const CURVE_EXPONENT = 1.5;
+const statCaps = stat_config_1.statCapsJSON;
+function getStatCap(rarity) {
+    const entry = statCaps.find(e => e.rarity === rarity);
+    if (entry == null)
+        throw new Error(`UNKNOWN_RARITY: ${rarity}`);
+    return entry.cap;
+}
+function getRarityMultiplier(rarity) {
+    const entry = statCaps.find(e => e.rarity === rarity);
+    if (entry == null)
+        throw new Error(`UNKNOWN_RARITY: ${rarity}`);
+    return entry.rarityMultiplier;
+}
+function getImprovementThreshold(statTotal, rarity) {
+    const rarityMultiplier = getRarityMultiplier(rarity);
+    const raw = CURVE_BASE + CURVE_SCALAR * Math.pow(Math.max(0, statTotal - 6), CURVE_EXPONENT);
+    return Math.round(raw / rarityMultiplier);
+}
+const COACH_MULTIPLIERS = {
+    [rarity_1.RarityEnum.COMMON]: 2.0,
+    [rarity_1.RarityEnum.RARE]: 1.5,
+    [rarity_1.RarityEnum.LEGENDARY]: 1.0,
+    [rarity_1.RarityEnum.MYTHIC]: 0.85,
+    [rarity_1.RarityEnum.SPECIAL]: 0.65
+};
+function getCoachMultiplier(rarity) {
+    return COACH_MULTIPLIERS[rarity] ?? 1.0;
+}
+const KEY_TO_COLUMN = {
+    setting: 'setting',
+    serve: 'serve',
+    spike: 'spike',
+    quick: 'quick',
+    power: 'power',
+    awareness: 'awareness',
+    attack: 'attack',
+    backAttack: 'back_attack',
+    reception: 'reception',
+    overhand: 'overhand',
+    bump: 'bump',
+    block: 'block',
+    read: 'read',
+    commit: 'commit',
+    focus: 'focus',
+    defense: 'defense',
+    stamina: 'stamina',
+    reflex: 'reflex'
+};
+function selectImprovableStat(rarity, trainingFocus, currentStats) {
+    const cap = getStatCap(rarity);
+    const multipliers = (0, stats_1.getMultipliers)(trainingFocus);
+    const focusPool = [];
+    const fallbackPool = [];
+    for (const key of performance_stats_1.performanceStatKeys) {
+        const col = KEY_TO_COLUMN[key];
+        if ((currentStats[col] ?? 0) >= cap)
+            continue;
+        fallbackPool.push(col);
+        if ((multipliers[key] ?? 0) > 0)
+            focusPool.push(col);
+    }
+    if (focusPool.length > 0) {
+        return focusPool[Math.floor(Math.random() * focusPool.length)];
+    }
+    if (fallbackPool.length === 0)
+        return null;
+    return fallbackPool[Math.floor(Math.random() * fallbackPool.length)];
+}

package/dist/cjs/src/service/player/improvement.test.d.ts

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