coa-server-manager/docs/PORTABLE_LEVEL_PROJECTION_AUDIT.md

Level-cap projection: audit and policy (Phase 8)

Scope: CoA only. Written from the code of the core fork (feat/portable-session-bridge, commit 2f6f9f0ca + modules mod-coa-content-scaling, mod-coa-playerbots, ...) and from experiments on a real worldserver with MaxPlayerLevel = 60 against the disposable realm databases. Nothing in this document is assumed from stock WotLK: each statement names the code or the observation behind it.

The invariant the whole phase rests on: the Owner's canonical character is never down-levelled. A projection is a view made for one realm; the full state (C0) stays canonical, and a realm only ever holds a working copy P0 derived from it.

1. Where the effective cap comes from, and whether it can move

Question	Answer	Evidence
Source of MaxPlayerLevel	worldserver.conf MaxPlayerLevel, read once into CONFIG_MAX_PLAYER_LEVEL; range 1..MAX_LEVEL	WorldConfig.cpp:302
Can it change while the worldserver runs?	No. The key is registered ConfigValueCache::Reloadable::No; nothing in the core or any module calls setIntConfig(CONFIG_MAX_PLAYER_LEVEL) (grep over src/ and modules/); mod-coa-content-scaling itself logs "Progression layout, expansion packs and MaxPlayerLevel cannot be changed at runtime! Server restart required." on a config reload	CoAContentScaling.cpp:948-955
Does anything clamp a real player above the cap at login?	No. Player::LoadFromDB does SetUInt32Value(UNIT_FIELD_LEVEL, fields[6]) with no comparison (PlayerStorage.cpp:5099); HandlePlayerLoginFromDB has no level check; ObjectMgr::GetXPForLevel returns 0 above the table (ObjectMgr.cpp:8126) and GetPlayerLevelInfo silently uses the cap's row for a higher level. The only clamp in the tree is ClampBotLevel of mod-coa-playerbots (BotMgr.cpp:360), which GiveLevel(cap) + XP = 0 + SaveToDB for bots only (observed: "BotMgr: clamped 'Shaniel' to server level cap 60")	code + experiment E1

Consequence: a level-80 canonical character must never be written to a cap-60 realm as level 80 (the core would run it as an over-level player with no XP table and no stat row of its own); and the cap is a per-process constant, so a change of cap is always a restart, which is a session boundary (section 8).

2. How mod-coa-content-scaling derives its ProgressionLayout

• CoAContentScaling::InitializeLayout() (CoAContentScaling.cpp:262) takes maxPlayerLevel from CONFIG_MAX_PLAYER_LEVEL, tbcActive = CoAContentScaling TBC pack enabled && pack registered, wotlkActive likewise, and Progression.Mode (Auto | Custom + ClassicEnd, TbcEnd) from mod-coa-content-scaling.conf; then ProgressionLayout::Create(...) (ProgressionLayout.cpp).
• Create: cap 80 with both packs and no custom bounds is the stock identity (Classic 1-60, TBC 58-70, WotLK 68-80). Otherwise Classic ends at 45 (cap 60) .. 60 (cap 80) by linear interpolation, TBC at 55 .. 70, WotLK ends at the cap. Observed on the cap-60 realm: Classic 1-45, TBC 45-55, WotLK 55-60.
• Validate() accepts only 60 <= MaxPlayerLevel <= 80. A layout that fails disables scaling (_enabled = false, LOG_FATAL).
• The layout is frozen at startup (OnLoadCustomDatabaseTable -> FinalizeAndInitialize); OnAfterConfigLoad(reload=true) only reloads the non-structural options (LoadReloadableConfig).
• The module is not part of the core repository (it is copied into modules/, git-ignored there): the Manager cannot rely on its API, and the core cannot link to it. What the module changes in memory is observable through sObjectMgr->GetItemTemplate(), which is the surface projection must use.

3. Which ItemTemplate fields are changed in memory

ItemBudgetScaler::ScaleAllItems runs once in OnStartup (CoAContentScaling.cpp:966, guarded by _itemsScaled, skipped when CoAContentScaling.ScaleItems = 0 or scaling is disabled). Per template, unless its policy is PRESERVE (ItemBudgetScaler.cpp:306):

• RequiredLevel and ItemLevel are replaced by the effective values of the layout;
• only when statMultiplier < 1: every ItemStat[i].ItemStatValue, Damage[i].DamageMin/Max, and Armor are multiplied;
• separately (same function of OnStartup) DungeonProgressionRequirements::reqItemLevel and the LFG dungeons' min/max levels.

Raw RequiredLevel in item_template is therefore not the rule. Observed on the cap-60 realm (.coascale item):

Item	raw RequiredLevel	runtime RequiredLevel	policy
19019 Thunderfury	60	41	REVIEW_SPECIAL
1063235 custom dagger	80	60	TIER_ALIGNED
300000 Valiant Holy Champion's Gloves	80	60	TIER_ALIGNED
490 Frosty Gauntlets	70	55	TIER_ALIGNED
2061035 Stormwatcher's Turban (custom)	80	80	PRESERVE
2069385 Legwraps of Eternal Sorrow (custom)	80	80	PRESERVE

Of 60 random weapons/armor authored above 60, 57 compress to <= 60 and 3 (CUSTOM_FALLBACK, PRESERVE) keep 70/80; of 250 random cloth/misc armor authored above 60, 2 keep 80. So on a cap-60 realm almost everything is legal at 60, and the exceptions are exactly the PRESERVE items, which only the running core can name. A Manager reading the world database would decide wrongly in both directions.

4. How Player::LoadFromDB reacts

Observed on the cap-60 realm with real characters imported through the Manager (E1-E4), and read in PlayerStorage.cpp:

State at load	Reaction	Evidence
level > cap	none for a real player (section 1)	code
equipped item whose runtime RequiredLevel > level	CanEquipItem returns EQUIP_ERR_CANT_EQUIP_LEVEL_I, the item is removed from the slot, deleted from the inventory tables and sent by mail ("There were problems with equipping item(s)")	_LoadInventory 6076-6110, CanEquipItem 2427; E2: a level-60 character with the runtime-80 Turban equipped lost it from slot 0 and got a This item(s) have problems with equipping/storing in inventory mail
the same item in a bag / backpack	loads normally (CanStoreItem has no level rule)	E2 (the Legwraps stayed in the backpack, no mail for them)
known spell above the working level	_LoadSpells calls addSpell blindly: no level check, no removal	PlayerStorage.cpp:6643-6658; E3: after a clamp to 60 the character still had all 1512 spells, 14 of them gated above 60
stock talents	character_talent is empty in all real characters (0 rows in the 2.5M-spell realm); CoA talents are spells (section 5)	DB
glyph rows	_LoadGlyphs copies the rows with no level check; 0 rows exist in the real realm	Player.cpp:15835, DB
active / rewarded quests	no level check in _LoadQuestStatus* (effective quest levels are compressed by the module)	code
pet	Pet::LoadPetFromDB -> SynchronizeLevelWithOwner: a hunter pet above its owner is lowered to the owner's level, a summon follows the owner (Pet.cpp:2366); GivePetXP gives nothing at or above the owner's level	code
class abilities (level-driven)	OnPlayerLevelChanged -> AscensionClassService::SynchronizeProgression (see section 5)	code, E3

So the load itself never holds anything back by level except the equip check, and that check destroys the placement and mails the item: holding must happen before load.

5. How CoA abilities, talents and builds are represented

CoA availability is data driven by level, not SpellInfo::SpellLevel:

• AscensionProgression::Ranks (2709 rows {class, first spell of chain, spell, RequiredLevel}), AscensionCompatData::ClassSpells (847), LegacyGeneratedClassSpells (270), TaughtAbilities (20), TalentReplacements (15) are compile-time tables; CoATalentEntries (entry id, class, spec, up to 3 rank spells, AECost, TECost, RequiredLevel), the automatic-entry dependencies and the talent budgets by class and level (CoATalentBudgets {class, level, AE, TE}) are read at startup from the client DBCs CharacterAdvancement.dbc, CharacterAdvancementEssence.dbc, CharacterAdvancementClassTypes.dbc, ... (AscensionCoATalentData.cpp:114).
• SynchronizeProgression(player) (called at level change, spec change, and on several commands) removes a ClassSpells/LegacyGeneratedClassSpells grant whose RequiredLevel exceeds the live level (AscensionCompat.cpp:700-745), and learns missing grants, ranks and automatic talent entries whose level is reached. It never removes a Ranks row's spell, a paid talent, or a spell outside the tables. Observed (E3): 14 of the 142 level-table spells of a real level-80 ranger need > 60 and stay after the level drops to 60.
• A paid talent (AECost/TECost > 0) is a spell in character_spell (rank n = the entry's n-th SpellIds); a pick requires player->GetLevel() >= entry.RequiredLevel and spent + cost <= budget(class, level) only when it is chosen (SetTalentRank, AscensionCompat.cpp:1552-1590); a spell already in the book is not re-checked against a lower level or budget.
• AscensionCoATalentState::KnownEntries / KnownRank / Spent are pure functions of a HasSpell predicate, so the core can evaluate a character's talent state from a spell set, without a Player.
• Builds are stored in character_settings in three shapes (all integers):
  • core.ascension_slot.<n>: [1, class, spec, N, (entry, rank) * N, M, (button, action) * M, 0...] (SpecializationSlotRecord, ParseSpecializationSlot); core.ascension_slot.active is the active slot;
  • core.ascension_build.<spec> and core.ascension_slot.<n>.build.<spec>: [count, pick * count] with pick = entry * 10 + rank (StoreBuild);
  • core.ascension_bar.<spec> and core.ascension_slot.<n>.bar.<spec>: [count, (button, spell) * count] (StoreBar). The active slot's record is regenerated from the live spellbook at every save (SaveSlot -> StoreSlot(LiveSlot)); an inactive slot's record is stored data and is applied by SwitchSlot through ApplyKnownEntriesUpload, which refuses entries above the level or over the budget. Observed (E2): after one login and save, core.ascension_slot.0 had been rewritten from the live state.

6. The P0 hazard, stated against the code

The Phase 4/5 merge replaces a character_settings source as a whole (cx.map("settings", ...)). Under projection:

C0  core.ascension_slot.0 = full level-80 record (83 entries, actions)
B0  core.ascension_slot.0 = what the level-60 realm regenerated at its first save (the projected subset)
B1  the same, after the player moved one talent at level 60

B0 -> B1 differs, so the whole record would replace C0's and erase every suspended 61-80 entry. Even with no edit at all, any save rewrites the record; the generic map merge is not enough. The same holds for core.ascension_build.* and the bars (a held spell on a bar button), and for character_action (model actions). All of them are decomposable (section 5): entries by id, picks by id, buttons by index. They are merged semantically under projection (overlay), and a record that does not parse is blocked (kept canonical, not applied), never replaced.

7. Classification of portable state under projection

State	Class	Rule (and why)
progression.level, progression.xp	Projection-owned	working = (cap, 0); any B0 -> B1 change is working-copy state and never reaches the canonical (level, xp)
money, honor, arena points, currencies, titles, explored zones	Apply	level independent; merged by delta as before
reputation, rewarded quests, client data, macros, wardrobe, collections, extensions	Apply	level independent
active quests	Apply	no level check at load; effective quest levels are compressed by the module
skills	Apply	rank caps follow the level at level-up; loading a higher rank does not fail
items: equipped (slots 0-18) or in a bag slot (19-22) with runtime RequiredLevel > projected level	HoldByProjection	the load would remove and mail them (section 4)
items: anywhere else (bags, bank-side containers, backpack)	Apply	loads normally; the realm refuses to equip them by its own rule
spells that appear in a CoA level table and whose every granting source needs > projected level	HoldByProjection	CanPortableSpellExistAtProjectedLevel; the core would not remove them by itself (section 5)
spells in no level table (racial, proficiencies, professions, mounts, stock, item-learned)	Apply	level independent
paid talents: entry RequiredLevel > L, then in data order those that exceed the AE (class tree) / TE (spec tree) budget of L	HoldByProjection	deterministic: keep the cheapest-level-first prefix that fits; the dependency closure of automatic entries is held with them
core.ascension_slot.*, core.ascension_build.*, core.ascension_bar.*	Apply (projected) + overlay merge	held entries/picks/actions are removed from P0 and survive in C0 (section 6)
a build record that does not parse	Unsupported	blocked: kept canonical, not applied, reported
character_action buttons whose action is a held spell	HoldByProjection	removed from P0, kept canonical
stock talents	Unsupported if any	none exist; a row would be refused rather than guessed
glyph rows	Apply	no level gate at load; none exist
pets	Apply	the core syncs the pet level to the owner at load (a normalisation, not progress)
item-linked appearance data	n/a	none (Phase 6)

8. Policy that follows

1. Activation. canonical.level > destination.max_player_level -> projection active at L = max_player_level; otherwise none. Matrix: 80->80 none, 80->70 L=70, 80->60 L=60, 70->60 L=60, 60->60 none.
2. Who decides. The running core decides items, spells and builds (section 3: only it knows the post-scaling templates; section 5: only it holds the CoA tables) through one pure function, exposed as the console command portable project (a read-only query) and inside the online import job. The result is a manifest: held item ids, held spell ids, held character_action buttons and the projected build vectors, stamped with the core's progression_signature and the policy version. The Manager never evaluates level requirements itself.
3. Stopped realm. A projection needs a manifest. On a stopped realm the Manager cannot obtain one and refuses explicitly (ProjectionNeedsRunningCore) unless the caller supplies a manifest taken from a core with the realm's current signature. Nothing is guessed.
4. P0 is an ordinary working copy. P0 = C0 - held + (level, 0) + projected builds. Import, update, B0, B1 and checkpoints work on it with the Phase 3/4/5 machinery; only the projection-owned parts of the merge are special (level/xp frozen, builds merged as an overlay). Held items map as filtered, held spells are absent from B0/B1, so the existing three-way merge keeps them without a second engine.
5. Session pinning. A session is pinned to (content_profile_hash, progression_signature, projection policy version, projected level) at the baseline. The pin travels in the (version 2) session messages and the Owner refuses a message under another pin. The signature is constant while a worldserver runs; a different one means a restart, which ends the session; the Host then does not re-arm the old working copy: it must be re-projected under the new profile first, and the realm refuses logins in the meantime (the session row stays ended).
6. Profile change (cap 60 -> 70): the next update re-projects with the new manifest; entries newly allowed at 70 are restored, entries still held until 80 stay canonical-only.
7. Capabilities. RealmCapabilities profile version 2 carries progression { max_player_level, projection_protocol, progression_signature, scaling_enabled }. The core's progression_signature is a SHA-256 over MaxPlayerLevel, the content-scaling switches that decide the layout, the policy version, a digest of the compile-time CoA progression tables and the talent data/budgets as loaded, and a digest of the effective (entry, RequiredLevel) of every item template (a few MB hashed once at startup, not the item database). It moves whenever anything above moves.

9. Experiments (cap-60 realm, scratch databases, bot logins = real LoadFromDB)

• E1 level-80 ranger (real, 21 items, 1512 spells) logged in on cap 60: level read as 80 by LoadFromDB; only the bot manager lowered it ("clamped ... to server level cap 60"), after which SynchronizeProgression ran at level 60.
• E2 level-60 necromancer with a runtime-80 turban equipped and a runtime-80 legwrap in the backpack: the turban left slot 0 and arrived by mail; the legwrap stayed; core.ascension_slot.0 was rewritten at the first save.
• E3 spell count 1512 before and after the drop to 60: no ability above 60 was removed (14 of them gated above 60 in the level tables, 5 above 70).
• E4 .coascale item samples (section 3).

10. What is deliberately not done in v1

• Projection on a stopped realm without a manifest; any guess from the world database.
• A conflict-resolution UI, Registry, Relay, Wildcard, the personal bank, equipment sets.
• Holding items outside the equipment/bag slots, or holding by rules other than the level (skill, spell, proficiency requirements stay the realm's own business, as in Phase 4).