volleyballsimtypes 0.0.522 → 0.0.523

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

@@ -28,6 +28,7 @@ function initModels(sequelize) {
     const PremiumGrant = models_1.PremiumGrantModel.initModel(sequelize);
     const Wishlist = models_1.WishlistModel.initModel(sequelize);
     const UserSettings = models_1.UserSettingsModel.initModel(sequelize);
+    const UserAchievements = models_1.UserAchievementsModel.initModel(sequelize);
     const UserDeviceToken = models_1.UserDeviceTokenModel.initModel(sequelize);
     const BasePositionPreset = models_1.BasePositionPresetModel.initModel(sequelize);
     const Notification = models_1.NotificationModel.initModel(sequelize);
@@ -78,6 +79,7 @@ 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' });
@@ -101,6 +103,7 @@ 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' });
@@ -370,6 +373,7 @@ function initModels(sequelize) {
         PremiumGrant,
         Wishlist,
         UserSettings,
+        UserAchievements,
         UserDeviceToken,
         BasePositionPreset,
         Notification,

package/dist/cjs/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/cjs/src/data/models/currency-transaction.js

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

package/dist/cjs/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/cjs/src/data/models/index.js

@@ -74,6 +74,7 @@ __exportStar(require("./wishlist"), exports);
 __exportStar(require("./currency-transaction"), exports);
 __exportStar(require("./user-pull-grant"), exports);
 __exportStar(require("./user-settings"), exports);
+__exportStar(require("./user-achievements"), exports);
 __exportStar(require("./user-device-token"), exports);
 __exportStar(require("./notification"), exports);
 __exportStar(require("./vper"), exports);

package/dist/cjs/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/cjs/src/data/models/user-achievements.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserAchievementsModel = void 0;
+const sequelize_1 = require("sequelize");
+class UserAchievementsModel extends sequelize_1.Model {
+    static initModel(sequelize) {
+        return UserAchievementsModel.init({
+            user_id: {
+                type: sequelize_1.DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: {
+                    model: 'AuthUser',
+                    key: 'user_id'
+                }
+            },
+            achievements: {
+                type: sequelize_1.DataTypes.JSONB,
+                allowNull: false,
+                defaultValue: {}
+            }
+        }, {
+            sequelize,
+            tableName: 'UserAchievements',
+            schema: 'public',
+            timestamps: false,
+            indexes: [
+                {
+                    name: 'UserAchievements_pk',
+                    unique: true,
+                    fields: [{ name: 'user_id' }]
+                }
+            ]
+        });
+    }
+}
+exports.UserAchievementsModel = UserAchievementsModel;

package/dist/cjs/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/cjs/src/service/achievement/achievement-status.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AchievementStatus = void 0;
+// 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).
+var AchievementStatus;
+(function (AchievementStatus) {
+    AchievementStatus["NOT_DONE"] = "NOT_DONE";
+    AchievementStatus["DONE"] = "DONE";
+    AchievementStatus["CLAIMED"] = "CLAIMED";
+})(AchievementStatus || (exports.AchievementStatus = AchievementStatus = {}));

package/dist/cjs/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/cjs/src/service/achievement/achievement-type.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_COMPLETABLE_ACHIEVEMENTS = exports.MILESTONE_THRESHOLDS = exports.MILESTONE_ACHIEVEMENTS = exports.ACHIEVEMENT_REWARD = exports.ACHIEVEMENT_KEYS = void 0;
+exports.isMilestone = isMilestone;
+exports.nextMilestone = nextMilestone;
+exports.milestoneState = milestoneState;
+exports.isAchievementKey = isAchievementKey;
+exports.isClientCompletable = isClientCompletable;
+// 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.
+exports.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).
+exports.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.
+exports.MILESTONE_ACHIEVEMENTS = [
+    'CLAIM_DAILY',
+    'PLAY_MATCH',
+    'WIN_MATCH',
+    'NORMAL_RECRUIT',
+    'DISMISS_PLAYER',
+    'WIN_LEAGUE',
+    'WIN_NATIONALS',
+    'WIN_REGIONALS',
+    'WIN_WCC'
+];
+function isMilestone(key) {
+    return exports.MILESTONE_ACHIEVEMENTS.includes(key);
+}
+// The claim thresholds every milestone steps through (x5, x2 alternating). Past the last one the milestone is "maxed".
+exports.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.
+function nextMilestone(claimedLevel) {
+    return exports.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.
+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, ...).
+exports.CLIENT_COMPLETABLE_ACHIEVEMENTS = ['READ_WIKI', 'VIEW_MATCH', 'PREVIEW_MATCH'];
+// Whether `value` is one of the known achievement keys (use before trusting a request param).
+function isAchievementKey(value) {
+    return exports.ACHIEVEMENT_KEYS.includes(value);
+}
+// Whether the client is allowed to fire completion for this key (only READ_WIKI / VIEW_MATCH).
+function isClientCompletable(key) {
+    return exports.CLIENT_COMPLETABLE_ACHIEVEMENTS.includes(key);
+}

package/dist/cjs/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/cjs/src/service/achievement/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./achievement-status"), exports);
+__exportStar(require("./achievement-type"), exports);
+__exportStar(require("./schemas/achievements.z"), exports);

package/dist/cjs/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/cjs/src/service/achievement/schemas/achievements.z.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.achievementMapSchema = void 0;
+const zod_1 = require("zod");
+const achievement_status_1 = require("../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).
+exports.achievementMapSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.nativeEnum(achievement_status_1.AchievementStatus));

package/dist/cjs/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/cjs/src/service/index.js

@@ -22,4 +22,5 @@ __exportStar(require("./player"), exports);
 __exportStar(require("./competition"), exports);
 __exportStar(require("./notification"), exports);
 __exportStar(require("./premium"), exports);
+__exportStar(require("./achievement"), exports);
 __exportStar(require("./utils"), exports);

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

@@ -5,10 +5,14 @@
 // (and populated from a picked default preset); consumed by the positional engine to place players. A team with no
 // `basePositions` falls back to the default preset for its `rotationSystem`.
 //
-// KEYING: rotation 1..6 and zone 1..6 are the ROTATIONAL (at-the-whistle) slots. The stored rotation convention is
-// the ENGINE's (SETTER_ZONE_TO_ROTATION); the UI editor re-keys the mapper's setter-zone rotation to it on save.
-// `coords[formation][rotation][zone]` is the standing coordinate for that formation; `receive[rotation][zone]` is
-// the reception-participation flag (absent zone => default to participating).
+// KEYING: rotation 1..6 and zone 1..6 are the ROTATIONAL (at-the-whistle) slots. The `rotation` key is the MAIN
+// designated setter's (designatedSetters[0]) rotational ZONE, raw 1..6 (`rotation` == that setter's zone; there is
+// NO setter-zone->rotation remap). This is the single convention everywhere: the editor writes it (posOf anchored on
+// the main setter, saved verbatim), the engine reads it (positioning.rotationOf = getMainSetter zone), and the
+// offensive/tempo/blocking prefs key by mainSetter.position. `coords[formation][rotation][zone]` is the standing
+// coordinate for that formation; `receive[rotation][zone]` is the reception-participation flag (absent zone => default
+// to participating). (History: rotationOf once remapped via SETTER_ZONE_TO_ROTATION and defaultReceiveMap once keyed
+// by that index; both were unified to the raw main-setter zone. See VolleyballSim/plans/rotation-key-main-setter.md.)
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BASE_FORMATIONS = void 0;
 exports.BASE_FORMATIONS = ['SERVE', 'RECEIVE', 'DEFENCE', 'DEF_L', 'DEF_M', 'DEF_R', 'ATTACK'];

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

@@ -9,6 +9,27 @@ const BACK_ROW = new Set([1, 5, 6]);
 // 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)) {

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/team/base-config.js

@@ -4,8 +4,12 @@
 // (and populated from a picked default preset); consumed by the positional engine to place players. A team with no
 // `basePositions` falls back to the default preset for its `rotationSystem`.
 //
-// KEYING: rotation 1..6 and zone 1..6 are the ROTATIONAL (at-the-whistle) slots. The stored rotation convention is
-// the ENGINE's (SETTER_ZONE_TO_ROTATION); the UI editor re-keys the mapper's setter-zone rotation to it on save.
-// `coords[formation][rotation][zone]` is the standing coordinate for that formation; `receive[rotation][zone]` is
-// the reception-participation flag (absent zone => default to participating).
+// KEYING: rotation 1..6 and zone 1..6 are the ROTATIONAL (at-the-whistle) slots. The `rotation` key is the MAIN
+// designated setter's (designatedSetters[0]) rotational ZONE, raw 1..6 (`rotation` == that setter's zone; there is
+// NO setter-zone->rotation remap). This is the single convention everywhere: the editor writes it (posOf anchored on
+// the main setter, saved verbatim), the engine reads it (positioning.rotationOf = getMainSetter zone), and the
+// offensive/tempo/blocking prefs key by mainSetter.position. `coords[formation][rotation][zone]` is the standing
+// coordinate for that formation; `receive[rotation][zone]` is the reception-participation flag (absent zone => default
+// to participating). (History: rotationOf once remapped via SETTER_ZONE_TO_ROTATION and defaultReceiveMap once keyed
+// by that index; both were unified to the raw main-setter zone. See VolleyballSim/plans/rotation-key-main-setter.md.)
 export const BASE_FORMATIONS = ['SERVE', 'RECEIVE', 'DEFENCE', 'DEF_L', 'DEF_M', 'DEF_R', 'ATTACK'];

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

@@ -195,22 +195,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.)
 export 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 = slotFunctionAt(system, setterZone, zone);
             perZone[String(zone)] = fn === RoleEnum.OUTSIDE_HITTER || (fn === RoleEnum.MIDDLE_BLOCKER && isBackRow(zone));
         }
-        receive[String(rotation)] = perZone;
+        receive[String(setterZone)] = perZone;
     }
     return receive;
 }

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

@@ -1,5 +1,5 @@
 import { RotationSystemEnum } from './rotation-system';
-import { defaultBaseConfig } from './default-base-config';
+import { defaultBaseConfig, defaultReceiveMap } from './default-base-config';
 import { baseConfigViolations } from './receive-overlap';
 // Back-row rotational zones (right/left/middle back). Front row is {2,3,4}.
 const BACK_ROW = new Set([1, 5, 6]);
@@ -7,6 +7,27 @@ const BACK_ROW = new Set([1, 5, 6]);
 // 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(defaultReceiveMap(RotationSystemEnum.FIVE_ONE)).toEqual(defaultBaseConfig(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(RotationSystemEnum)) {
+            if (system === RotationSystemEnum.SIX_ZERO)
+                continue; // 6-0 has no designated setter
+            const map = 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(RotationSystemEnum)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "volleyballsimtypes",
-  "version": "0.0.522",
+  "version": "0.0.523",
   "description": "vbsim types",
   "main": "./dist/cjs/src/index.js",
   "module": "./dist/esm/src/index.js",