volleyballsimtypes 0.0.521 → 0.0.523

package/dist/cjs/src/service/team/default-base-config.js

@@ -199,22 +199,24 @@ const DEFAULT_5_1_RECEIVE = {
     5: { 1: true, 2: false, 3: true, 4: false, 5: false, 6: true },
     6: { 1: true, 2: false, 3: false, 4: true, 5: true, 6: false }
 };
-// Rotation index -> the setter's rotational zone (inverse of SETTER_ZONE_TO_ROTATION {1:1,6:2,5:3,4:4,3:5,2:6}).
-const ROTATION_TO_SETTER_ZONE = { 1: 1, 2: 6, 3: 5, 4: 4, 5: 3, 6: 2 };
-// The default serve-receive participation map: the standard 3-passer formation. A rotational slot passes iff its
-// slot function is an OUTSIDE_HITTER (either row) or a BACK-ROW MIDDLE_BLOCKER (the libero's slot). The setter, the
-// opposite and the front-row middle hide. slotFunctionAt maps the opposite slot to SETTER in 4-2/6-2, so the
-// second setter is excluded too, giving the same 3-passer map for every system.
+// The default serve-receive participation map: the standard 3-passer formation. Keyed by the MAIN setter's rotational
+// ZONE (raw 1..6 = the canonical convention: receive[Z] describes the formation with the setter at zone Z), matching
+// DEFAULT_5_1_RECEIVE, the PRESET_6_2/PRESET_4_2 presets, the tactics editor, and the engine's rotationOf. A rotational
+// slot passes iff its slot function is an OUTSIDE_HITTER (either row) or a BACK-ROW MIDDLE_BLOCKER (the libero's slot);
+// the setter, the opposite and the front-row middle hide. slotFunctionAt maps the opposite slot to SETTER in 4-2/6-2,
+// so the second setter is excluded too, giving the same 3-passer map for every system.
+// (History: this used to key by a rotation INDEX via ROTATION_TO_SETTER_ZONE {1:1,2:6,3:5,4:4,5:3,6:2}, a leftover of
+// the old setter-zone->rotation remap removed from rotationOf; that transposed the non-5-1 default receive maps at
+// rotations 2/3/5/6. Fixed 2026-08-23, see VolleyballSim/plans/rotation-key-main-setter.md + the re-key migration.)
 function defaultReceiveMap(system) {
     const receive = {};
-    for (let rotation = 1; rotation <= 6; rotation++) {
-        const setterZone = ROTATION_TO_SETTER_ZONE[rotation];
+    for (let setterZone = 1; setterZone <= 6; setterZone++) {
         const perZone = {};
         for (let zone = 1; zone <= 6; zone++) {
             const fn = (0, lineup_function_1.slotFunctionAt)(system, setterZone, zone);
             perZone[String(zone)] = fn === player_1.RoleEnum.OUTSIDE_HITTER || (fn === player_1.RoleEnum.MIDDLE_BLOCKER && (0, match_1.isBackRow)(zone));
         }
-        receive[String(rotation)] = perZone;
+        receive[String(setterZone)] = perZone;
     }
     return receive;
 }

package/dist/cjs/src/service/team/default-base-config.test.js

@@ -2,8 +2,60 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const rotation_system_1 = require("./rotation-system");
 const default_base_config_1 = require("./default-base-config");
+const receive_overlap_1 = require("./receive-overlap");
 // Back-row rotational zones (right/left/middle back). Front row is {2,3,4}.
 const BACK_ROW = new Set([1, 5, 6]);
+// The editor and the sim BOTH fall back to defaultBaseConfig for a zone a config leaves unset, so the default base
+// MUST itself pass the FIVB overlap / serve-line rules in every rotation. Otherwise a partial config (some zones
+// stored, others defaulted) can render/commit an unset zone onto a neighbour and read "out of rotation even in
+// base" for a formation the sim runs legally (rush6@ tournament report, 2026-08-21).
+// The default receive map must key by the MAIN setter's RAW rotational zone (receive[R] describes the formation with
+// the setter at zone R), the single canonical convention shared by DEFAULT_5_1_RECEIVE, the PRESET_6_2/4_2 presets,
+// the tactics editor, and the engine's rotationOf. It used to key by a rotation INDEX (ROTATION_TO_SETTER_ZONE), which
+// transposed non-5-1 maps at rotations 2/3/5/6 (fixed 2026-08-23; see plans/rotation-key-main-setter.md).
+describe('defaultReceiveMap: raw main-setter-zone convention', () => {
+    it('5-1: the computed map equals the hand-authored raw DEFAULT_5_1_RECEIVE', () => {
+        // defaultBaseConfig(5-1).receive IS the hand-authored DEFAULT_5_1_RECEIVE. The computed map matching it proves
+        // defaultReceiveMap keys by the raw setter zone (receive[R] = setter@R), not the old index.
+        expect((0, default_base_config_1.defaultReceiveMap)(rotation_system_1.RotationSystemEnum.FIVE_ONE)).toEqual((0, default_base_config_1.defaultBaseConfig)(rotation_system_1.RotationSystemEnum.FIVE_ONE).receive);
+    });
+    it('every system: receive[R] hides the setter at zone R (raw), never at ROTATION_TO_SETTER_ZONE[R]', () => {
+        for (const system of Object.values(rotation_system_1.RotationSystemEnum)) {
+            if (system === rotation_system_1.RotationSystemEnum.SIX_ZERO)
+                continue; // 6-0 has no designated setter
+            const map = (0, default_base_config_1.defaultReceiveMap)(system);
+            for (const z of [2, 3, 5, 6]) { // the rotations where raw and the old index convention diverge
+                expect({ system, z, passes: map[String(z)]?.[String(z)] }).toEqual({ system, z, passes: false });
+            }
+        }
+    });
+});
+describe('defaultBaseConfig base-config legality', () => {
+    it('has zero SERVE/RECEIVE overlap violations for every rotation system', () => {
+        for (const system of Object.values(rotation_system_1.RotationSystemEnum)) {
+            expect({ system, violations: (0, receive_overlap_1.baseConfigViolations)((0, default_base_config_1.defaultBaseConfig)(system)) }).toEqual({ system, violations: [] });
+        }
+    });
+});
+// Regression (rush6@ tournament report, 2026-08-21): a partial RECEIVE config (some zones stored, one left unset)
+// reads "out of rotation even in base" ONLY when the editor fills the unset zone from a coarse flat grid (all
+// back-row zones at depth 6.5), which lands on a stored DEEP neighbour. Filling from the sim's per-rotation default
+// (what the editor's coordOf now does, matching what the sim always did) keeps it legal.
+describe('unset RECEIVE zone fallback (editor gap fill)', () => {
+    // The reported user's real rotation-2 RECEIVE: zone 3 sits abnormally deep at d 6.5; zone 6 is unset.
+    const partialRot2 = {
+        1: { d: 6.4, r: 3.15 }, 2: { d: 2.75, r: 1.65 }, 3: { d: 6.5, r: -2.65 }, 4: { d: 2.75, r: -2.75 }, 5: { d: 2.8, r: -3.05 }
+    };
+    const FLAT_GRID_ZONE6 = { d: 6.5, r: 0 }; // the editor's OLD blank-slate default for a back-row zone
+    const SIM_DEFAULT_ZONE6 = (0, default_base_config_1.defaultBaseConfig)(rotation_system_1.RotationSystemEnum.FIVE_ONE).coords.RECEIVE['2']['6']; // the fix's fallback
+    const violationsWithZone6 = (zone6) => (0, receive_overlap_1.baseConfigViolations)({ coords: { RECEIVE: { 2: { ...partialRot2, 6: zone6 } } } });
+    it('collides (zones 3,6) when the gap is filled from the flat grid - the bug', () => {
+        expect(violationsWithZone6(FLAT_GRID_ZONE6).map(v => v.zones)).toEqual([[3, 6]]);
+    });
+    it('stays legal when the gap is filled from the sim per-rotation default - the fix', () => {
+        expect(violationsWithZone6(SIM_DEFAULT_ZONE6)).toEqual([]);
+    });
+});
 // The trajectory-set default desired-contact (owner D9, 2026-08-12): a near-net hitting point in each attacker's
 // lane, NOT the old set-to-the-standing-dot location. Front row contacts sit ~0.5 m off the net; back row on the
 // ~1.8 m pipe line; the lateral is the ATTACK-dot's r clamped inside the antenna (|r| <= 4.3).

package/dist/esm/src/api/index.d.ts

@@ -60,7 +60,7 @@ export interface ApiPlayerInjuryStatus {
     severity: number;
     injuredUntil: string;
 }
-export type ChampionRegion = 'azureich' | 'borealas' | 'varune' | 'tirdeas';
+export type ChampionRegion = 'azureich' | 'borealas' | 'varune' | 'tirdeas' | 'kyorin';
 export type ChampionBadgeSpec = {
     type: 'league';
 } | {

package/dist/esm/src/data/country-locales.json

@@ -47,6 +47,18 @@
     "XP": [
         "nl_NL"
     ],
+    "XQ": [
+        "pl_PL"
+    ],
+    "XR": [
+        "th_TH"
+    ],
+    "XS": [
+        "ar_SA"
+    ],
+    "XT": [
+        "en_IN"
+    ],
     "PK": [
         "bal_Arab_PK",
         "bal_Latn_PK",

package/dist/esm/src/data/init-models.js

@@ -1,4 +1,4 @@
-import { AuthIdentityModel, AuthSessionModel, AuthUserModel, BoxScoreModel, CoachModel, ScoutModel, PhysicianModel, PhysiotherapistModel, BoxScoreTotalsModel, CompetitionChampionModel, JerseyBadgeModel, CurrencyTransactionModel, GachaPityModel, GachaPullHistoryModel, WishlistModel, UserSettingsModel, UserDeviceTokenModel, BasePositionPresetModel, CompetitionMatchModel, CompetitionMVPModel, CompetitionModel, CompetitionStandingsMatchModel, CompetitionStandingsModel, CompetitionTeamsModel, CountryModel, DivisionModel, DivisionSeasonModel, IterationModel, LeagueModel, MatchModel, MatchRatingModel, MatchResultModel, MatchSetModel, PerformanceStatsModel, PlayerModel, PlayerImprovementLogModel, PlayerDeclineLogModel, PlayerTeamModel, RetiredPlayerModel, PromotionMatchModel, FriendlyModel, RegionQualifierModel, NationalCountryModel, RallyModel, TacticsModel, TeamJerseyModel, LineupPresetModel, MatchPresetModel, EventModel, EventCompetitionModel, EventSquadModel, EventPackModel, EventPackPlayerModel, EventResultModel, EventBotTeamModel, TeamModel, TeamReplacementModel, UserCurrencyModel, UserPlayerProgressModel, UserPullGrantModel, PremiumGrantModel, UserTeamModel, VPERModel, NotificationModel, AppConfigModel, LegacyTeamFlagModel } from './models';
+import { AuthIdentityModel, AuthSessionModel, AuthUserModel, BoxScoreModel, CoachModel, ScoutModel, PhysicianModel, PhysiotherapistModel, BoxScoreTotalsModel, CompetitionChampionModel, JerseyBadgeModel, CurrencyTransactionModel, GachaPityModel, GachaPullHistoryModel, WishlistModel, UserSettingsModel, UserAchievementsModel, UserDeviceTokenModel, BasePositionPresetModel, CompetitionMatchModel, CompetitionMVPModel, CompetitionModel, CompetitionStandingsMatchModel, CompetitionStandingsModel, CompetitionTeamsModel, CountryModel, DivisionModel, DivisionSeasonModel, IterationModel, LeagueModel, MatchModel, MatchRatingModel, MatchResultModel, MatchSetModel, PerformanceStatsModel, PlayerModel, PlayerImprovementLogModel, PlayerDeclineLogModel, PlayerTeamModel, RetiredPlayerModel, PromotionMatchModel, FriendlyModel, RegionQualifierModel, NationalCountryModel, RallyModel, TacticsModel, TeamJerseyModel, LineupPresetModel, MatchPresetModel, EventModel, EventCompetitionModel, EventSquadModel, EventPackModel, EventPackPlayerModel, EventResultModel, EventBotTeamModel, TeamModel, TeamReplacementModel, UserCurrencyModel, UserPlayerProgressModel, UserPullGrantModel, PremiumGrantModel, UserTeamModel, VPERModel, NotificationModel, AppConfigModel, LegacyTeamFlagModel } from './models';
 export function initModels(sequelize) {
     const Coach = CoachModel.initModel(sequelize);
     const Scout = ScoutModel.initModel(sequelize);
@@ -25,6 +25,7 @@ export function initModels(sequelize) {
     const PremiumGrant = PremiumGrantModel.initModel(sequelize);
     const Wishlist = WishlistModel.initModel(sequelize);
     const UserSettings = UserSettingsModel.initModel(sequelize);
+    const UserAchievements = UserAchievementsModel.initModel(sequelize);
     const UserDeviceToken = UserDeviceTokenModel.initModel(sequelize);
     const BasePositionPreset = BasePositionPresetModel.initModel(sequelize);
     const Notification = NotificationModel.initModel(sequelize);
@@ -75,6 +76,7 @@ export function initModels(sequelize) {
     AuthUser.hasOne(GachaPity, { as: 'GachaPity', foreignKey: 'user_id' });
     AuthUser.hasOne(Wishlist, { as: 'Wishlist', foreignKey: 'user_id' });
     AuthUser.hasOne(UserSettings, { as: 'UserSettings', foreignKey: 'user_id' });
+    AuthUser.hasOne(UserAchievements, { as: 'UserAchievements', foreignKey: 'user_id' });
     AuthUser.hasMany(UserDeviceToken, { as: 'UserDeviceTokens', foreignKey: 'user_id' });
     AuthUser.hasMany(BasePositionPreset, { as: 'BasePositionPresets', foreignKey: 'user_id' });
     AuthUser.hasMany(Notification, { as: 'Notifications', foreignKey: 'user_id' });
@@ -98,6 +100,7 @@ export function initModels(sequelize) {
     PremiumGrant.belongsTo(AuthUser, { as: 'grantedByUser', foreignKey: 'granted_by' });
     Wishlist.belongsTo(AuthUser, { as: 'user', foreignKey: 'user_id' });
     UserSettings.belongsTo(AuthUser, { as: 'user', foreignKey: 'user_id' });
+    UserAchievements.belongsTo(AuthUser, { as: 'user', foreignKey: 'user_id' });
     Competition.belongsTo(Iteration, { as: 'Iteration', foreignKey: 'iteration' });
     Competition.hasMany(CompetitionMatch, { as: 'CompetitionMatches', foreignKey: 'competition_id' });
     Competition.hasMany(CompetitionStandings, { as: 'CompetitionStandings', foreignKey: 'competition_id' });
@@ -367,6 +370,7 @@ export function initModels(sequelize) {
         PremiumGrant,
         Wishlist,
         UserSettings,
+        UserAchievements,
         UserDeviceToken,
         BasePositionPreset,
         Notification,

package/dist/esm/src/data/models/currency-transaction.d.ts

@@ -17,9 +17,10 @@ export declare enum CurrencyTransactionSourceEnum {
     SEASON_REWARD = "SEASON_REWARD",
     COMPETITION_REWARD = "COMPETITION_REWARD",
     PHYSICIAN_UPGRADE = "PHYSICIAN_UPGRADE",
-    PHYSIOTHERAPIST_UPGRADE = "PHYSIOTHERAPIST_UPGRADE"
+    PHYSIOTHERAPIST_UPGRADE = "PHYSIOTHERAPIST_UPGRADE",
+    ACHIEVEMENT_CLAIM = "ACHIEVEMENT_CLAIM"
 }
-export type CurrencyTransactionSource = CurrencyTransactionSourceEnum.MATCH_REWARD | CurrencyTransactionSourceEnum.GACHA_PULL | CurrencyTransactionSourceEnum.COACH_UPGRADE | CurrencyTransactionSourceEnum.SCOUT_UPGRADE | CurrencyTransactionSourceEnum.PLAYER_DISMISS | CurrencyTransactionSourceEnum.PLAYER_RETIRE | CurrencyTransactionSourceEnum.ADMIN_GRANT | CurrencyTransactionSourceEnum.SEASON_REWARD | CurrencyTransactionSourceEnum.COMPETITION_REWARD | CurrencyTransactionSourceEnum.PHYSICIAN_UPGRADE | CurrencyTransactionSourceEnum.PHYSIOTHERAPIST_UPGRADE;
+export type CurrencyTransactionSource = CurrencyTransactionSourceEnum.MATCH_REWARD | CurrencyTransactionSourceEnum.GACHA_PULL | CurrencyTransactionSourceEnum.COACH_UPGRADE | CurrencyTransactionSourceEnum.SCOUT_UPGRADE | CurrencyTransactionSourceEnum.PLAYER_DISMISS | CurrencyTransactionSourceEnum.PLAYER_RETIRE | CurrencyTransactionSourceEnum.ADMIN_GRANT | CurrencyTransactionSourceEnum.SEASON_REWARD | CurrencyTransactionSourceEnum.COMPETITION_REWARD | CurrencyTransactionSourceEnum.PHYSICIAN_UPGRADE | CurrencyTransactionSourceEnum.PHYSIOTHERAPIST_UPGRADE | CurrencyTransactionSourceEnum.ACHIEVEMENT_CLAIM;
 export interface CurrencyTransactionAttributes {
     transaction_id: string;
     user_id: string;

package/dist/esm/src/data/models/currency-transaction.js

@@ -17,6 +17,7 @@ export var CurrencyTransactionSourceEnum;
     CurrencyTransactionSourceEnum["COMPETITION_REWARD"] = "COMPETITION_REWARD";
     CurrencyTransactionSourceEnum["PHYSICIAN_UPGRADE"] = "PHYSICIAN_UPGRADE";
     CurrencyTransactionSourceEnum["PHYSIOTHERAPIST_UPGRADE"] = "PHYSIOTHERAPIST_UPGRADE";
+    CurrencyTransactionSourceEnum["ACHIEVEMENT_CLAIM"] = "ACHIEVEMENT_CLAIM";
 })(CurrencyTransactionSourceEnum || (CurrencyTransactionSourceEnum = {}));
 export class CurrencyTransactionModel extends Model {
     static initModel(sequelize) {

package/dist/esm/src/data/models/index.d.ts

@@ -58,6 +58,7 @@ export * from './wishlist';
 export * from './currency-transaction';
 export * from './user-pull-grant';
 export * from './user-settings';
+export * from './user-achievements';
 export * from './user-device-token';
 export * from './notification';
 export * from './vper';

package/dist/esm/src/data/models/index.js

@@ -58,6 +58,7 @@ export * from './wishlist';
 export * from './currency-transaction';
 export * from './user-pull-grant';
 export * from './user-settings';
+export * from './user-achievements';
 export * from './user-device-token';
 export * from './notification';
 export * from './vper';

package/dist/esm/src/data/models/user-achievements.d.ts

@@ -0,0 +1,19 @@
+import * as Sequelize from 'sequelize';
+import { Model } from 'sequelize';
+import { AuthUserId, AuthUserModel } from '.';
+export interface UserAchievementsAttributes {
+    user_id: string;
+    achievements: Record<string, string>;
+}
+export type UserAchievementsPk = 'user_id';
+export type UserAchievementsId = UserAchievementsModel[UserAchievementsPk];
+export type UserAchievementsCreationAttributes = Sequelize.Optional<UserAchievementsAttributes, 'achievements'>;
+export declare class UserAchievementsModel extends Model<UserAchievementsAttributes, UserAchievementsCreationAttributes> implements UserAchievementsAttributes {
+    user_id: string;
+    achievements: Record<string, string>;
+    user: AuthUserModel;
+    getUser: Sequelize.BelongsToGetAssociationMixin<AuthUserModel>;
+    setUser: Sequelize.BelongsToSetAssociationMixin<AuthUserModel, AuthUserId>;
+    createUser: Sequelize.BelongsToCreateAssociationMixin<AuthUserModel>;
+    static initModel(sequelize: Sequelize.Sequelize): typeof UserAchievementsModel;
+}

package/dist/esm/src/data/models/user-achievements.js

@@ -0,0 +1,33 @@
+import { DataTypes, Model } from 'sequelize';
+export class UserAchievementsModel extends Model {
+    static initModel(sequelize) {
+        return UserAchievementsModel.init({
+            user_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: {
+                    model: 'AuthUser',
+                    key: 'user_id'
+                }
+            },
+            achievements: {
+                type: DataTypes.JSONB,
+                allowNull: false,
+                defaultValue: {}
+            }
+        }, {
+            sequelize,
+            tableName: 'UserAchievements',
+            schema: 'public',
+            timestamps: false,
+            indexes: [
+                {
+                    name: 'UserAchievements_pk',
+                    unique: true,
+                    fields: [{ name: 'user_id' }]
+                }
+            ]
+        });
+    }
+}

package/dist/esm/src/service/achievement/achievement-status.d.ts

@@ -0,0 +1,5 @@
+export declare enum AchievementStatus {
+    NOT_DONE = "NOT_DONE",
+    DONE = "DONE",
+    CLAIMED = "CLAIMED"
+}

package/dist/esm/src/service/achievement/achievement-status.js

@@ -0,0 +1,10 @@
+// Per-user achievement progress state. Stored only inside the UserAchievements.achievements jsonb map
+// (achievementKey -> status); an absent key means NOT_DONE, so no data backfill is ever needed when new
+// achievements are added. Because it lives only inside jsonb it is NOT a Sequelize DataTypes.ENUM and has no
+// Postgres CREATE TYPE (mirrors how Tactics stores RoleEnum values inside jsonb without a DB enum).
+export var AchievementStatus;
+(function (AchievementStatus) {
+    AchievementStatus["NOT_DONE"] = "NOT_DONE";
+    AchievementStatus["DONE"] = "DONE";
+    AchievementStatus["CLAIMED"] = "CLAIMED";
+})(AchievementStatus || (AchievementStatus = {}));

package/dist/esm/src/service/achievement/achievement-type.d.ts

@@ -0,0 +1,24 @@
+import { AchievementStatus } from './achievement-status';
+export declare const ACHIEVEMENT_KEYS: readonly ["NORMAL_RECRUIT", "SPECIAL_RECRUIT", "DISMISS_PLAYER", "RETIRE_PLAYER", "GIVE_NICKNAME", "PLAY_MATCH", "WIN_MATCH", "FINISH_LEAGUE_SEASON", "UPGRADE_COACH", "UPGRADE_SCOUT", "UPGRADE_PHYSICIAN", "UPGRADE_PHYSIOTHERAPIST", "CHANGE_TRAINING_FOCUS", "CHANGE_TACTICS", "REGISTER_EVENT", "WIN_LEAGUE", "WIN_NATIONALS", "WIN_REGIONALS", "WIN_WCC", "READ_WIKI", "CLAIM_DAILY", "VIEW_MATCH", "PREVIEW_MATCH"];
+export type AchievementKey = typeof ACHIEVEMENT_KEYS[number];
+export declare const ACHIEVEMENT_REWARD = 500;
+export declare const MILESTONE_ACHIEVEMENTS: readonly AchievementKey[];
+export declare function isMilestone(key: AchievementKey): boolean;
+export declare const MILESTONE_THRESHOLDS: readonly number[];
+export declare function nextMilestone(claimedLevel: number): number | null;
+export interface MilestoneProgress {
+    c: number;
+    l: number;
+}
+export interface MilestoneState {
+    count: number;
+    claimed: number;
+    target: number | null;
+    claimable: boolean;
+    maxed: boolean;
+}
+export declare function milestoneState(value: unknown): MilestoneState;
+export type AchievementMap = Partial<Record<AchievementKey, AchievementStatus | MilestoneProgress>>;
+export declare const CLIENT_COMPLETABLE_ACHIEVEMENTS: readonly AchievementKey[];
+export declare function isAchievementKey(value: string): value is AchievementKey;
+export declare function isClientCompletable(key: AchievementKey): boolean;

package/dist/esm/src/service/achievement/achievement-type.js

@@ -0,0 +1,77 @@
+// Single source of truth for the set of achievement keys (the tutorial checklist). Adding an achievement:
+//   1. add its key here,
+//   2. add its display config in the UI (src/view/achievements/achievements-config.ts),
+//   3. add its name + description to every locale file,
+//   4. wire its completion trigger (API handler or sim engine) to call completeAchievement.
+// The key is only ever a jsonb map key, so there is no Postgres enum/column to migrate when the list grows.
+export const ACHIEVEMENT_KEYS = [
+    'NORMAL_RECRUIT',
+    'SPECIAL_RECRUIT',
+    'DISMISS_PLAYER',
+    'RETIRE_PLAYER',
+    'GIVE_NICKNAME',
+    'PLAY_MATCH',
+    'WIN_MATCH',
+    'FINISH_LEAGUE_SEASON',
+    'UPGRADE_COACH',
+    'UPGRADE_SCOUT',
+    'UPGRADE_PHYSICIAN',
+    'UPGRADE_PHYSIOTHERAPIST',
+    'CHANGE_TRAINING_FOCUS',
+    'CHANGE_TACTICS',
+    'REGISTER_EVENT',
+    'WIN_LEAGUE',
+    'WIN_NATIONALS',
+    'WIN_REGIONALS',
+    'WIN_WCC',
+    'READ_WIKI',
+    'CLAIM_DAILY',
+    'VIEW_MATCH',
+    'PREVIEW_MATCH'
+];
+// Every achievement grants the same flat coin reward when the user claims it (each milestone reached is a fresh claim).
+export const ACHIEVEMENT_REWARD = 500;
+// Recurring "milestone" achievements: instead of a one-shot NOT_DONE->DONE->CLAIMED status, these store a running count
+// and re-arm at escalating thresholds. Their map value is a MilestoneProgress object, not a status string.
+export const MILESTONE_ACHIEVEMENTS = [
+    'CLAIM_DAILY',
+    'PLAY_MATCH',
+    'WIN_MATCH',
+    'NORMAL_RECRUIT',
+    'DISMISS_PLAYER',
+    'WIN_LEAGUE',
+    'WIN_NATIONALS',
+    'WIN_REGIONALS',
+    'WIN_WCC'
+];
+export function isMilestone(key) {
+    return MILESTONE_ACHIEVEMENTS.includes(key);
+}
+// The claim thresholds every milestone steps through (x5, x2 alternating). Past the last one the milestone is "maxed".
+export const MILESTONE_THRESHOLDS = [1, 5, 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000, 500000, 1000000];
+// The next threshold strictly greater than `claimedLevel` (0 = nothing claimed yet), or null when all are claimed.
+export function nextMilestone(claimedLevel) {
+    return MILESTONE_THRESHOLDS.find(t => t > claimedLevel) ?? null;
+}
+// Derive a milestone's display/claim state from its raw map value (a MilestoneProgress object, a legacy status string,
+// or undefined). Anything that is not a well-formed object counts as no progress ({c:0, l:0}). Shared by the API claim
+// path and the UI.
+export function milestoneState(value) {
+    const mp = (value != null && typeof value === 'object') ? value : {};
+    const count = typeof mp.c === 'number' && Number.isFinite(mp.c) ? mp.c : 0;
+    const claimed = typeof mp.l === 'number' && Number.isFinite(mp.l) ? mp.l : 0;
+    const target = nextMilestone(claimed);
+    return { count, claimed, target, claimable: target != null && count >= target, maxed: target == null };
+}
+// Achievements the client is allowed to self-complete because there is no server-side action to hook: opening the
+// wiki and opening a match detail. The POST /achievements/:key/complete endpoint MUST reject any key not in this set,
+// so a client can never self-complete a server-authoritative achievement (recruit, win, upgrade, ...).
+export const CLIENT_COMPLETABLE_ACHIEVEMENTS = ['READ_WIKI', 'VIEW_MATCH', 'PREVIEW_MATCH'];
+// Whether `value` is one of the known achievement keys (use before trusting a request param).
+export function isAchievementKey(value) {
+    return ACHIEVEMENT_KEYS.includes(value);
+}
+// Whether the client is allowed to fire completion for this key (only READ_WIKI / VIEW_MATCH).
+export function isClientCompletable(key) {
+    return CLIENT_COMPLETABLE_ACHIEVEMENTS.includes(key);
+}

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

@@ -0,0 +1,3 @@
+export * from './achievement-status';
+export * from './achievement-type';
+export * from './schemas/achievements.z';

package/dist/esm/src/service/achievement/index.js

@@ -0,0 +1,3 @@
+export * from './achievement-status';
+export * from './achievement-type';
+export * from './schemas/achievements.z';

package/dist/esm/src/service/achievement/schemas/achievements.z.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import { AchievementStatus } from '../achievement-status';
+export declare const achievementMapSchema: z.ZodRecord<z.ZodString, z.ZodEnum<typeof AchievementStatus>>;

package/dist/esm/src/service/achievement/schemas/achievements.z.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import { AchievementStatus } from '../achievement-status';
+// Validates a UserAchievements.achievements jsonb map (achievementKey -> status). Keys are loose strings so an
+// unknown/legacy key never fails validation; values must be a known AchievementStatus. Mirrors the z.record idiom
+// used by Tactics (tactics.z.ts).
+export const achievementMapSchema = z.record(z.string(), z.nativeEnum(AchievementStatus));

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

@@ -6,4 +6,5 @@ export * from './player';
 export * from './competition';
 export * from './notification';
 export * from './premium';
+export * from './achievement';
 export * from './utils';

package/dist/esm/src/service/index.js

@@ -6,4 +6,5 @@ export * from './player';
 export * from './competition';
 export * from './notification';
 export * from './premium';
+export * from './achievement';
 export * from './utils';

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

@@ -10,11 +10,14 @@ const WEIGHTS = {
     BLOCK_TOUCH: 0.2,
     DEFENSE_DIG: 0.25,
     SETTING_PASS: 0.15,
+    // A swing that neither killed nor was stuffed nor sailed: the ball is still alive and the defence had to play it.
+    ATTACK_IN_PLAY: 0.10,
     // reception quality
     RECEPTION_PERFECT: 0.35,
     RECEPTION_POSITIVE: 0.15,
     RECEPTION_OVERPASS: -0.6,
-    // terminal errors (always point against)
+    // terminal errors (always point against). A stuffed attack is booked as an attack error by the simulator, so
+    // being blocked is penalised here at the same -1.0 as a swing into the net.
     TERMINAL_ERROR: -1.0
 };
 // Minimum points a player must be on court for in a match to receive a VPER. VPER is a per-100-points rate,
@@ -44,14 +47,31 @@ export class VPER {
         let pointsPlayedSum = 0;
         for (const box of boxScores) {
             const w = WEIGHTS;
+            // Each action is scored ONCE, at its highest-value outcome. A set that became a kill is an assist, not an
+            // assist plus a pass; a touch that became a stuff is a block point, not a block point plus a touch. The
+            // subtractions below strip the lower-value credit that the simulator books alongside the terminal one.
+            //
+            // Each remainder is clamped at 0. A well-formed row can never make one negative (a swing yields at most one
+            // of {kill, error}; every assist belongs to a set that booked a pass on this same row; BlockStatsSchema
+            // enforces solo + assists <= touches), so the clamp only guards against a malformed or hand-built row
+            // silently turning a subtraction into a bonus.
+            //
+            // A swing that stayed alive: attempts minus the ones that terminated (a kill, or an error, which now
+            // includes being stuffed).
+            const inPlayAttacks = Math.max(0, box.attack.attempts - box.attack.kills - box.attack.errors);
+            // Sets that did NOT convert into a kill.
+            const unconvertedSets = Math.max(0, box.setting.pass - box.setting.assists);
+            // Touches that did not become a block point.
+            const nonScoringTouches = Math.max(0, box.block.touches - box.block.solo - box.block.assists);
             const positive = w.ATTACK_KILL * box.attack.kills +
+                w.ATTACK_IN_PLAY * inPlayAttacks +
                 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.BLOCK_TOUCH * nonScoringTouches +
                 w.DEFENSE_DIG * box.defense.digs +
-                w.SETTING_PASS * box.setting.pass +
+                w.SETTING_PASS * unconvertedSets +
                 w.RECEPTION_PERFECT * box.reception.perfect +
                 w.RECEPTION_POSITIVE * box.reception.positive;
             const negative = w.RECEPTION_OVERPASS * box.reception.overpasses +

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

@@ -104,6 +104,92 @@ describe('VPER.computeVPERForMatch()', () => {
         expect(VPER.computeVPERForMatch([box])).toBeCloseTo(14, 5);
     });
 });
+// ─── each action scores once, at its highest-value outcome ────────────────────
+describe('VPER.computeVPERForMatch() — no double-counting', () => {
+    it('scores a converted set as an assist only, never assist + pass', () => {
+        const box = makeBox();
+        box.setting.pass = 1;
+        box.setting.assists = 1;
+        box.misc.pointsPlayed = 10;
+        // unconvertedSets = 1 - 1 = 0, so the setter earns 0.7, not 0.85.
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(7, 5);
+    });
+    it('pays the pass weight only on sets that did not convert', () => {
+        const box = makeBox();
+        box.setting.pass = 10;
+        box.setting.assists = 4;
+        box.misc.pointsPlayed = 10;
+        // assists 4 * 0.7 = 2.8; unconverted 6 * 0.15 = 0.9; raw 3.7
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(37, 5);
+    });
+    it('scores a solo stuff as a block point only, never solo + touch', () => {
+        const box = makeBox();
+        box.block.touches = 1;
+        box.block.solo = 1;
+        box.misc.pointsPlayed = 10;
+        // nonScoringTouches = 1 - 1 - 0 = 0, so the blocker earns 1.0, not 1.2.
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(10, 5);
+    });
+    it('pays the touch weight only on touches that did not become a point', () => {
+        const box = makeBox();
+        box.block.touches = 5;
+        box.block.solo = 1;
+        box.block.assists = 2;
+        box.misc.pointsPlayed = 10;
+        // solo 1.0 + assists 2 * 0.5 = 1.0 + nonScoringTouches 2 * 0.2 = 0.4; raw 2.4
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(24, 5);
+    });
+    it('never lets a malformed row turn a subtraction into a bonus', () => {
+        // kills without attempts, assists without passes, blocks without touches: every remainder clamps to 0.
+        const box = makeBox();
+        box.attack.kills = 5;
+        box.setting.assists = 10;
+        box.block.solo = 3;
+        box.misc.pointsPlayed = 10;
+        // 5 * 1.0 + 10 * 0.7 + 3 * 1.0 = 15, with no negative remainder contribution
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(150, 5);
+    });
+});
+// ─── the non-scoring attack ──────────────────────────────────────────────────
+describe('VPER.computeVPERForMatch() — attack outcomes', () => {
+    it('rewards a swing that stays in play (weight 0.10)', () => {
+        const box = makeBox();
+        box.attack.attempts = 10;
+        box.attack.kills = 3;
+        box.attack.errors = 1;
+        box.misc.pointsPlayed = 10;
+        // kills 3 * 1.0 = 3; inPlay (10 - 3 - 1) = 6 * 0.10 = 0.6; errors 1 * -1.0; raw 2.6
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(26, 5);
+    });
+    it('penalises a stuffed swing at -1.0 (the simulator books it as an attack error)', () => {
+        const box = makeBox();
+        box.attack.attempts = 1;
+        box.attack.errors = 1;
+        box.misc.pointsPlayed = 10;
+        // inPlay = 0; the stuff is a terminal error
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(-10, 5);
+    });
+    it('separates volume from efficiency: more dug swings for the same kills rates higher', () => {
+        const efficient = makeBox();
+        efficient.attack.attempts = 12;
+        efficient.attack.kills = 10;
+        efficient.misc.pointsPlayed = 100;
+        const volume = makeBox();
+        volume.attack.attempts = 30;
+        volume.attack.kills = 10;
+        volume.misc.pointsPlayed = 100;
+        // Pre-fix both scored exactly 10.0. Now the extra 18 dug swings are worth 0.10 each.
+        expect(VPER.computeVPERForMatch([efficient])).toBeCloseTo(10.2, 5);
+        expect(VPER.computeVPERForMatch([volume])).toBeCloseTo(12.0, 5);
+    });
+    it('a swing that is killed scores the kill, not the kill plus an in-play credit', () => {
+        const box = makeBox();
+        box.attack.attempts = 1;
+        box.attack.kills = 1;
+        box.misc.pointsPlayed = 10;
+        expect(VPER.computeVPERForMatch([box])).toBeCloseTo(10, 5);
+    });
+});
 // ─── VPER eligibility threshold ───────────────────────────────────────────────
 describe('VPER.qualifiesForVPER()', () => {
     function boxWithPoints(points) {

package/dist/esm/src/service/notification/catalog/en.json

@@ -58,5 +58,9 @@
         "title": "Event finished",
         "body": "The event is over. See the final table and your rewards.",
         "placed": "The event is over. You finished {{position}} of {{entrants}}."
+    },
+    "regionRelocation": {
+        "title": "Your team is moving",
+        "body": "Your team has been chosen to be moved to the new region: Kyorin. Nothing has changed in terms of the team you manage, your players or anything else."
     }
 }

package/dist/esm/src/service/notification/catalog/es.json

@@ -58,5 +58,9 @@
         "title": "Evento terminado",
         "body": "El evento ha terminado. Mira la tabla final y tus recompensas.",
         "placed": "El evento ha terminado. Has quedado {{position}} de {{entrants}}."
+    },
+    "regionRelocation": {
+        "title": "Tu equipo se traslada",
+        "body": "Tu equipo ha sido elegido para trasladarse a la nueva región: Kyorin. No cambia nada en cuanto al equipo que gestionas, tus jugadores ni nada más."
     }
 }

package/dist/esm/src/service/notification/catalog/fr.json

@@ -58,5 +58,9 @@
         "title": "Événement terminé",
         "body": "L'événement est terminé. Consulte le classement final et tes récompenses.",
         "placed": "L'événement est terminé. Tu finis {{position}} sur {{entrants}}."
+    },
+    "regionRelocation": {
+        "title": "Votre équipe déménage",
+        "body": "Votre équipe a été choisie pour être transférée vers la nouvelle région : Kyorin. Rien ne change concernant l'équipe que vous gérez, vos joueurs ni quoi que ce soit d'autre."
     }
 }

package/dist/esm/src/service/notification/catalog/it.json

@@ -58,5 +58,9 @@
         "title": "Evento concluso",
         "body": "L'evento è finito. Guarda la classifica finale e i tuoi premi.",
         "placed": "L'evento è finito. Hai chiuso {{position}} su {{entrants}}."
+    },
+    "regionRelocation": {
+        "title": "La tua squadra si trasferisce",
+        "body": "La tua squadra è stata scelta per essere spostata nella nuova regione: Kyorin. Non cambia nulla riguardo alla squadra che gestisci, ai tuoi giocatori o a qualsiasi altra cosa."
     }
 }

package/dist/esm/src/service/notification/catalog/pl.json

@@ -58,5 +58,9 @@
         "title": "Wydarzenie zakończone",
         "body": "Wydarzenie się skończyło. Zobacz tabelę końcową i nagrody.",
         "placed": "Wydarzenie się skończyło. Zająłeś {{position}} miejsce na {{entrants}}."
+    },
+    "regionRelocation": {
+        "title": "Twoja drużyna się przenosi",
+        "body": "Twoja drużyna została wybrana do przeniesienia do nowego regionu: Kyorin. Nic się nie zmienia, jeśli chodzi o zarządzaną przez ciebie drużynę, twoich zawodników ani cokolwiek innego."
     }
 }