volleyballsimtypes 0.0.356 → 0.0.358

package/dist/esm/src/service/match/schemas/match-set.z.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { Rally } from '../rally';
+import { BoxScore } from '../box-score';
+const nonNegInt = z.number().int().min(0);
+const orderSchema = z.number().int().min(0).max(4);
+/**
+ * NOTE:
+ * This validates that the input contains actual instances of Rally / BoxScore.
+ * If you're validating plain JSON (e.g. from DB/API), swap these for object schemas.
+ */
+const PlayerPositionSchema = z.custom((v) => v != null, {
+    message: 'INVALID_PLAYER_POSITION'
+});
+export const MatchSetInputSchema = z.object({
+    id: z.uuid(),
+    order: orderSchema,
+    isTieBreak: z.boolean(),
+    homePlayerPosition: z.array(PlayerPositionSchema).max(12),
+    awayPlayerPosition: z.array(PlayerPositionSchema).max(12),
+    homeScore: nonNegInt,
+    awayScore: nonNegInt,
+    boxScores: z.array(z.custom((v) => v instanceof BoxScore, {
+        message: 'INVALID_BOX_SCORE_INSTANCE'
+    })),
+    rallies: z.array(z.custom((v) => v instanceof Rally, {
+        message: 'INVALID_RALLY_INSTANCE'
+    }))
+}).superRefine((data, ctx) => {
+    const { order, isTieBreak, rallies, homeScore, awayScore } = data;
+    // isTieBreak <-> order === 4
+    if (isTieBreak && order !== 4) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'TIEBREAK_REQUIRES_ORDER_4',
+            path: ['order']
+        });
+    }
+    if (!isTieBreak && order === 4) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'ORDER_4_REQUIRES_TIEBREAK',
+            path: ['isTieBreak']
+        });
+    }
+    const hasRallies = rallies.length > 0;
+    const isZeroZero = homeScore === 0 && awayScore === 0;
+    const scoreThreshold = isTieBreak ? 15 : 25;
+    // Score rule: one side must reach threshold, unless this is an empty-rallies 0-0 set.
+    if (!isZeroZero && homeScore < scoreThreshold && awayScore < scoreThreshold) {
+        ctx.addIssue({
+            code: 'custom',
+            message: isTieBreak ? 'SCORE_REQUIRES_SIDE_AT_LEAST_15' : 'SCORE_REQUIRES_SIDE_AT_LEAST_25',
+            path: ['homeScore']
+        });
+    }
+    // If rallies exist, score cannot be 0-0 and must match the number of rallies.
+    if (hasRallies) {
+        if (isZeroZero) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'NON_EMPTY_RALLIES_CANNOT_HAVE_0_0_SCORE',
+                path: ['rallies']
+            });
+        }
+        if (homeScore + awayScore !== rallies.length) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'RALLIES_LENGTH_MUST_EQUAL_SCORE_SUM',
+                path: ['rallies']
+            });
+        }
+    }
+});

package/dist/esm/src/service/match/schemas/match.z.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { Team } from '../../team';
+import { StatusEnum } from '../../../data/common';
+import { MatchSet } from '../match-set';
+import { VPER } from '../vper';
+export declare const MatchInputSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    homeTeam: z.ZodCustom<Team, Team>;
+    awayTeam: z.ZodCustom<Team, Team>;
+    scheduledDate: z.ZodCoercedDate<unknown>;
+    status: z.ZodEnum<{
+        PENDING: StatusEnum.PENDING;
+        IN_PROGRESS: StatusEnum.IN_PROGRESS;
+        COMPLETE: StatusEnum.COMPLETE;
+    }>;
+    sets: z.ZodOptional<z.ZodArray<z.ZodCustom<MatchSet, MatchSet>>>;
+    VPERs: z.ZodOptional<z.ZodArray<z.ZodCustom<VPER, VPER>>>;
+    homeScore: z.ZodOptional<z.ZodNumber>;
+    awayScore: z.ZodOptional<z.ZodNumber>;
+    winner: z.ZodOptional<z.ZodCustom<Team, Team>>;
+}, z.core.$strip>;
+export type MatchInput = z.infer<typeof MatchInputSchema>;

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

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { Team } from '../../team';
+import { StatusEnum } from '../../../data/common';
+import { MatchSet } from '../match-set';
+import { VPER } from '../vper';
+const teamSchema = z.custom((v) => v instanceof Team, {
+    message: 'INVALID_TEAM_INSTANCE'
+});
+export const MatchInputSchema = z.object({
+    id: z.uuid(),
+    homeTeam: teamSchema,
+    awayTeam: teamSchema,
+    scheduledDate: z.coerce.date(),
+    status: z.enum(Object.values(StatusEnum)),
+    sets: z.array(z.custom((v) => v instanceof MatchSet, {
+        message: 'INVALID_MATCH_SET_INSTANCE'
+    })).optional(),
+    VPERs: z.array(z.custom((v) => v instanceof VPER, {
+        message: 'INVALID_VPER_INSTANCE'
+    })).optional(),
+    homeScore: z.number().int().optional(),
+    awayScore: 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 !== StatusEnum.COMPLETE) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'NON_EMPTY_SETS_REQUIRE_COMPLETE_MATCH',
+                path: ['sets']
+            });
+        }
+    }
+    const { status, homeScore, awayScore } = data;
+    if (status !== 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/esm/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/esm/src/service/match/schemas/rally.z.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { RallyEvent } from '../../event';
+const nonNegInt = z.number().int().min(0);
+export const RallyInputSchema = z.object({
+    id: z.uuid(),
+    order: nonNegInt,
+    servingTeamId: z.uuid(),
+    events: z.array(z.custom((v) => v instanceof RallyEvent, {
+        message: 'INVALID_RALLY_EVENT_INSTANCE'
+    }))
+});

package/dist/esm/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/esm/src/service/match/schemas/vper.z.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export const VPERInputSchema = z.object({
+    playerId: z.uuid(),
+    matchId: z.uuid(),
+    value: z.number().finite()
+});

package/dist/esm/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/esm/src/service/match/vper.js

@@ -0,0 +1,65 @@
+import { VPERInputSchema } from './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
+};
+export class VPER {
+    static create(input) {
+        const result = 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);
+    }
+}

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

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

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

@@ -0,0 +1,106 @@
+import { describe, it, expect } from '@jest/globals';
+import { v4 as uuidv4 } from 'uuid';
+import { VPER } from './vper';
+import { BoxScore } from './box-score';
+// ─── helpers ─────────────────────────────────────────────────────────────────
+function makeBox() {
+    return BoxScore.createEmptyBoxScore(uuidv4(), uuidv4());
+}
+// ─── VPER.computeVPERForMatch ─────────────────────────────────────────────────
+describe('VPER.computeVPERForMatch()', () => {
+    it('returns 0 when box score list is empty', () => {
+        expect(VPER.computeVPERForMatch([])).toBe(0);
+    });
+    it('returns 0 for a single all-zero box score', () => {
+        expect(VPER.computeVPERForMatch([makeBox()])).toBe(0);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(100, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(50, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(40, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(30, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(20, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(70, 5);
+    });
+    it('penalises terminal errors at weight -1.0 each', () => {
+        const box = makeBox();
+        box.attack.errors = 3;
+        box.misc.pointsPlayed = 10;
+        // 100 * (-3) / 10 = -30
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(-30, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(-30, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(57.5, 5);
+    });
+    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
+        expect(VPER.computeVPERForMatch([box1, box2])).toBeCloseTo(26.667, 2);
+    });
+    it('rewards defense digs (weight 0.25)', () => {
+        const box = makeBox();
+        box.defense.digs = 8;
+        box.misc.pointsPlayed = 10;
+        // 100 * (8 * 0.25) / 10 = 20
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(20, 5);
+    });
+    it('rewards perfect receptions (weight 0.35)', () => {
+        const box = makeBox();
+        box.reception.perfect = 4;
+        box.misc.pointsPlayed = 10;
+        // 100 * (4 * 0.35) / 10 = 14
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(14, 5);
+    });
+});

package/dist/esm/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/esm/src/service/player/improvement.js

@@ -0,0 +1,75 @@
+import { statCapsJSON } from '../../stat-config';
+import { RarityEnum } from './rarity';
+import { performanceStatKeys } from './performance-stats';
+import { getMultipliers } from './stats';
+const CURVE_BASE = 100;
+const CURVE_SCALAR = 0.098;
+const CURVE_EXPONENT = 1.5;
+const statCaps = statCapsJSON;
+export function getStatCap(rarity) {
+    const entry = statCaps.find(e => e.rarity === rarity);
+    if (entry == null)
+        throw new Error(`UNKNOWN_RARITY: ${rarity}`);
+    return entry.cap;
+}
+export function getRarityMultiplier(rarity) {
+    const entry = statCaps.find(e => e.rarity === rarity);
+    if (entry == null)
+        throw new Error(`UNKNOWN_RARITY: ${rarity}`);
+    return entry.rarityMultiplier;
+}
+export 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 = {
+    [RarityEnum.COMMON]: 2.0,
+    [RarityEnum.RARE]: 1.5,
+    [RarityEnum.LEGENDARY]: 1.0,
+    [RarityEnum.MYTHIC]: 0.85,
+    [RarityEnum.SPECIAL]: 0.65
+};
+export 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'
+};
+export function selectImprovableStat(rarity, trainingFocus, currentStats) {
+    const cap = getStatCap(rarity);
+    const multipliers = getMultipliers(trainingFocus);
+    const focusPool = [];
+    const fallbackPool = [];
+    for (const key of 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/esm/src/service/player/improvement.test.d.ts

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

package/dist/esm/src/service/player/improvement.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect } from '@jest/globals';
+import { RarityEnum } from './rarity';
+import { getStatCap, getRarityMultiplier, getImprovementThreshold, getCoachMultiplier, selectImprovableStat } from './improvement';
+import { StatsEnum } from './stats';
+// ─── getStatCap ───────────────────────────────────────────────────────────────
+describe('getStatCap()', () => {
+    it.each([
+        [RarityEnum.COMMON, 59],
+        [RarityEnum.RARE, 69],
+        [RarityEnum.LEGENDARY, 79],
+        [RarityEnum.MYTHIC, 89],
+        [RarityEnum.SPECIAL, 99]
+    ])('%s → cap %i', (rarity, expected) => {
+        expect(getStatCap(rarity)).toBe(expected);
+    });
+    it('throws UNKNOWN_RARITY for an unrecognised rarity string', () => {
+        expect(() => getStatCap('DIVINE')).toThrow('UNKNOWN_RARITY');
+    });
+});
+// ─── getRarityMultiplier ──────────────────────────────────────────────────────
+describe('getRarityMultiplier()', () => {
+    it.each([
+        [RarityEnum.COMMON, 1.0],
+        [RarityEnum.RARE, 1.15],
+        [RarityEnum.LEGENDARY, 1.3],
+        [RarityEnum.MYTHIC, 1.5],
+        [RarityEnum.SPECIAL, 1.75]
+    ])('%s → multiplier %f', (rarity, expected) => {
+        expect(getRarityMultiplier(rarity)).toBeCloseTo(expected, 5);
+    });
+    it('throws UNKNOWN_RARITY for an unrecognised rarity string', () => {
+        expect(() => getRarityMultiplier('DIVINE')).toThrow('UNKNOWN_RARITY');
+    });
+});
+// ─── getImprovementThreshold ──────────────────────────────────────────────────
+describe('getImprovementThreshold()', () => {
+    it('at statTotal=6 the curve exponent term is 0 → threshold = round(100 / rarityMultiplier)', () => {
+        // COMMON (multiplier 1.0): round(100 / 1.0) = 100
+        expect(getImprovementThreshold(6, RarityEnum.COMMON)).toBe(100);
+        // LEGENDARY (multiplier 1.3): round(100 / 1.3) = 77
+        expect(getImprovementThreshold(6, RarityEnum.LEGENDARY)).toBe(Math.round(100 / 1.3));
+    });
+    it('threshold increases as statTotal grows beyond 6', () => {
+        const low = getImprovementThreshold(10, RarityEnum.COMMON);
+        const high = getImprovementThreshold(50, RarityEnum.COMMON);
+        expect(high).toBeGreaterThan(low);
+    });
+    it('higher rarity multiplier yields lower threshold (easier improvement)', () => {
+        const common = getImprovementThreshold(30, RarityEnum.COMMON);
+        const legendary = getImprovementThreshold(30, RarityEnum.LEGENDARY);
+        expect(legendary).toBeLessThan(common);
+    });
+    it('returns an integer (Math.round applied)', () => {
+        expect(Number.isInteger(getImprovementThreshold(20, RarityEnum.RARE))).toBe(true);
+    });
+});
+// ─── getCoachMultiplier ───────────────────────────────────────────────────────
+describe('getCoachMultiplier()', () => {
+    it.each([
+        [RarityEnum.COMMON, 2.0],
+        [RarityEnum.RARE, 1.5],
+        [RarityEnum.LEGENDARY, 1.0],
+        [RarityEnum.MYTHIC, 0.85],
+        [RarityEnum.SPECIAL, 0.65]
+    ])('%s → %f', (rarity, expected) => {
+        expect(getCoachMultiplier(rarity)).toBeCloseTo(expected, 10);
+    });
+    it('higher rarity → lower coach multiplier (rarer players improve more slowly)', () => {
+        expect(getCoachMultiplier(RarityEnum.COMMON)).toBeGreaterThan(getCoachMultiplier(RarityEnum.LEGENDARY));
+    });
+});
+// ─── selectImprovableStat ─────────────────────────────────────────────────────
+/** Builds a stat record (DB column names) with every value set to `value`. */
+function allStats(value) {
+    return {
+        setting: value,
+        serve: value,
+        spike: value,
+        quick: value,
+        power: value,
+        awareness: value,
+        attack: value,
+        back_attack: value,
+        reception: value,
+        overhand: value,
+        bump: value,
+        block: value,
+        read: value,
+        commit: value,
+        focus: value,
+        defense: value,
+        stamina: value,
+        reflex: value
+    };
+}
+describe('selectImprovableStat()', () => {
+    it('returns null when every stat is at or above the rarity cap', () => {
+        const cap = getStatCap(RarityEnum.COMMON); // 59
+        expect(selectImprovableStat(RarityEnum.COMMON, StatsEnum.ATTACK, allStats(cap))).toBeNull();
+    });
+    it('returns a stat from the SERVE focus pool (serve, awareness, attack)', () => {
+        const focusPool = new Set(['serve', 'awareness', 'attack']);
+        const stats = allStats(1);
+        // Run many times to confirm we never escape the focus pool
+        for (let i = 0; i < 100; i++) {
+            const result = selectImprovableStat(RarityEnum.COMMON, StatsEnum.SERVE, stats);
+            expect(result).not.toBeNull();
+            expect(focusPool.has(result)).toBe(true);
+        }
+    });
+    it('returns a stat from the RECEIVE focus pool (reception, overhand, bump, focus, defense, reflex)', () => {
+        const focusPool = new Set(['reception', 'overhand', 'bump', 'focus', 'defense', 'reflex']);
+        const stats = allStats(1);
+        for (let i = 0; i < 100; i++) {
+            const result = selectImprovableStat(RarityEnum.COMMON, StatsEnum.RECEIVE, stats);
+            expect(result).not.toBeNull();
+            expect(focusPool.has(result)).toBe(true);
+        }
+    });
+    it('falls back to any improvable stat when all focus-pool stats are capped', () => {
+        const cap = getStatCap(RarityEnum.COMMON);
+        // Cap the SERVE focus stats: serve, awareness, attack
+        const stats = { ...allStats(1), serve: cap, awareness: cap, attack: cap };
+        for (let i = 0; i < 50; i++) {
+            const result = selectImprovableStat(RarityEnum.COMMON, StatsEnum.SERVE, stats);
+            expect(result).not.toBeNull();
+            // Must never return one of the capped focus stats
+            expect(['serve', 'awareness', 'attack']).not.toContain(result);
+        }
+    });
+    it('returns a string (DB column name) not a PerformanceStatsKey', () => {
+        const stats = allStats(1);
+        const result = selectImprovableStat(RarityEnum.COMMON, StatsEnum.ATTACK, stats);
+        // back_attack is the DB column for backAttack — verify the column naming convention
+        if (result === 'back_attack') {
+            expect(result).toBe('back_attack');
+        }
+        else {
+            expect(typeof result).toBe('string');
+        }
+    });
+});

package/dist/esm/src/service/player/index.d.ts

@@ -0,0 +1,8 @@
+export * from './player';
+export * from './improvement';
+export * from './player-generator';
+export * from './performance-stats';
+export * from './trait';
+export * from './rarity';
+export * from './role';
+export * from './stats';