coa-server-manager/docs/PORTABLE_LEVEL_PROJECTION.md

Level-cap projection (Phase 8): design, implementation, verification

Companion of PORTABLE_LEVEL_PROJECTION_AUDIT.md (what the core and mod-coa-content-scaling actually do; read it first). CoA only.

Invariant. The Owner's canonical character is never down-levelled. A realm whose MaxPlayerLevel is below the character's level is given a working copy at the cap (P = apply(hold, C)); everything the copy cannot hold stays in C; a realm that can hold it all gets all of it back.

1. Who decides, and about what

Only the running core knows the effective (post-scaling) item levels and holds the CoA progression tables, so the core decides and the Manager applies. The Manager never reads a level requirement.

Core (src/server/coa/CoAPortableProjection.{h,cpp})	Manager (crates/coa-core/src/portable/projection/)
portable project <job_id>: read-only query over a job file (header query:"project", snapshot) -> manifest in <job_id>.result	ProjectionAnswer::parse (strict), Decision::{Native, Projected(ProjectionHold)}
Project(input, level): held items, held abilities, held buttons, held entries of the stored build records, blocked records	apply(canonical, hold); settings::Record (structure-only codecs); merge3_with(.., MergeProjection)
Signature(), capabilities report v2 progression {max_player_level, projection_protocol, projection_policy_version, progression_signature, scaling_enabled}	profile v2 (capabilities::Progression), ProgressionPin, ProjectionContext
import job header projection {active, level, policy_version, progression_signature}: verified, idempotence check (the core projects the working copy again and it must hold nothing), coa.portable.pin written	realm::project::plan (the one policy for import, update, reconcile), CoreOracle, SuppliedDecision
login of a session character whose pin is not the core's progression: refused	HostService ends the session under the old pin, reproject_session

What the core holds at level L (policy version 1)

• Items: a top-level item in an equipment slot (0-18) or a bag slot (19-22) whose runtime RequiredLevel is above L (this is what _LoadInventory + CanEquipItem would otherwise delete from the slot and mail), and the contents of a held bag. Everything else (backpack, bank, bag contents) is written.
• Abilities: a spell of the character that appears in a CoA level table (ClassSpells, LegacyGeneratedClassSpells, Ranks, Felsworn rifts, TaughtAbilities, TalentReplacements, talent entries) and no source of which allows it at L (a source allows it if its level is <= L, its talent entry is not held, its parent ability is not held). Spells of the live baseline, proficiencies and unresolved trainer spells are level independent and never held. Computed to a fixpoint.
• Talent entries: held when RequiredLevel > L; paid entries (AE/TE cost) in (RequiredLevel, EntryId) order are kept while Spent fits GetCoATalentBudget(class, L), whole entries only (no partial rank); an automatic entry whose required entry is held is held with it.
• Buttons: character_action spell buttons showing a held ability.
• Stored builds (core.ascension_slot.<n>, core.ascension_build.*, core.ascension_bar.*, also .slot.<n>.build/.bar): the held entries/buttons are listed per record; a record the core cannot take apart is blocked: not given to the realm and never merged back.
• Level L, xp 0. Money, honor, reputation, quests, skills, pets, glyphs, wardrobe, collections, extensions: applied (unchanged by the cap).

If the cap has no talent budget row for a class, the query fails (projection): nothing is guessed.

The progression signature

SHA-256 over: policy version, MaxPlayerLevel, the content-scaling switches that decide the layout (Enable, Progression.Mode/ClassicEnd/TbcEnd, ScaleItems), the compile-time CoA progression tables, the talent data and budgets as loaded, and the sorted (entry, runtime RequiredLevel) of every item template (hashed once, lazily, not the item database). Eras/packs are covered through the item levels they change. It is constant while a worldserver runs; any change means a restart.

2. Manager flow

plan(C, revision, options, oracle)
  no capabilities          -> given as is (lower layers, bare tools)
  capabilities, no progression -> refused (unknown is never "no cap")
  level <= cap             -> native; pinned to the realm's progression
  level >  cap             -> oracle.decide(C) (running core via RA, or SuppliedDecision for a stopped realm) -> hold
                              checked: same signature/cap/policy as the realm's profile, made for exactly this snapshot
                              view = apply(C, hold); context = ProjectionContext{canonical_level, projected_level, canonical_revision,
                              content_profile_hash, progression_signature, projection_policy_version, hold}

• Import (offline and online) and update use plan; the job/script carries the pin; after the realm committed, realm_projection (schema 8) holds the context and character_server_mapping.progression_pin the pin (cap, policy, signature, content profile hash, projected or native).
• Update merge3(realm now, P_old(synced), P_new(canonical), Strict): both ends are views (the stored hold is re-applied to the synced canonical, a fresh decision to the new one); build records merge key by key; when the old state was a working copy, the new view's level/xp win over the player's own (adopt_progression). A changed pin forces the update even at the same canonical revision. A stopped realm needs a supplied decision, else ProjectionNeedsRunningCore (nothing is written).
• Session / reconcile merge3(C0, B0, B1, Lenient) with freeze_progression (the realm's level/xp never reach C), blocked records ignored, build records merged by key. A held item/ability/button is absent from B0 and B1, which the existing three-way merge already reads as "filtered by the realm: kept". Nothing was added to the merge for them.
• Why key-wise merge of builds. The core rewrites core.ascension_slot.<n> from the live spellbook at every save (audit section 6). Replaced as one value, B0 -> B1 would erase every held entry of C. Merged by key (entries, buttons, (class, spec) head) the realm's rewrite changes nothing and a pick made at the cap arrives.
• Session protocol 2. PortableSessionStarted.progression {pin, projection?}, PortableCheckpoint.pin, OwnerAck.pin. The Owner stores the pin/context at the start (and refuses an inconsistent one: another canonical level/revision, a projected pin without its context), then refuses any checkpoint under another pin. session_protocol 2 in the content profile and the version check on every message make a v1 and a v2 peer refuse each other before a character is armed.
• The cap moves under a session (restart with another MaxPlayerLevel/rules). The core refuses to let the character in (coa.portable.pin is not its progression; read at login by query, because character_settings sources outside core. are not loaded into the player). HostService::observe_profile sees the new signature; tick reads the realm as it is (the old working copy: nobody played it) and sends the final checkpoint under the old pin; the Owner merges it as a projection of the old cap. The next session is flagged reproject and rearm_pending does not arm it. reproject_session asks for the decision at the new cap, updates the working copy in place (arming the next session in the same transaction) and clears the flag. No message ever merges across two progressions.

3. Classification of the other state

Apply: money, honor, arena points, currencies, titles, explored zones, reputation, rewarded and active quests, skills, glyph rows (none exist), pets (the core levels a pet to its owner at load: normalisation, not progress), wardrobe, collections, extensions, macros. HoldByProjection: items, abilities, buttons, build entries as above. Projection-owned: level, xp. Unsupported: stock talent rows (never written, as before), a build record that does not parse (blocked, kept canonical). Evidence per row: audit sections 4-7.

4. Capability profile v2

profile_version 2 adds progression (outside the content hash) and Feature::LevelProjection; core report v2 carries progression (a v1 core reports none). A stored v1 profile is migrated (from_json): content and hash are unchanged, progression = None, which compat reads as Blocking "probe the realm through its core" for every operation. ProfileChange::progression_changed reports a moved cap/signature even when the content hash did not move.

5. Verification

Unit (Manager, cargo test -p coa-core --lib): codecs, apply, activation matrix (80->80 none, 80->70, 80->60, 70->60, 60->60 none), strict answer parsing, key-wise merge incl. idle session equals canonical, repeated and later checkpoints, blocked records, level freeze, adoption, pins/contexts in the store, fake-realm sessions (whole projected session, forged pin, wrong projection, cap change under a session, online at the change), profile v1 migration, compat outcomes.

Live (#[ignore], real MySQL A/B): realm::live_projection (offline import at cap 60 with a supplied decision, offline play + reconcile with the realm's level moved and a new item, update to a cap-80 profile restoring helmet/abilities with the canonical byte-identical, down to 70 and 60 again). Live with a real worldserver (session::live_projection, cap-60 build of the fork, optional cap-70 configuration, fixture ranger or a real level-80 character): the core refuses an unprojected level-80 job (above_level_cap), an inconsistent working copy (projection_inconsistent) and another progression (progression_changed); the real load mails nothing the projection held; the Host takes B0 under the pin; the realm-side level is moved (59) and the canonical level/xp stay; checkpoints and the final checkpoint keep held items, abilities and build entries; after a restart at cap 70 the core refuses the character, the Host ends the session under the old pin, reproject_session brings the working copy to 70 and restores exactly what 70 allows.

6. Limits

• A stopped realm cannot be projected without a decision supplied from its core (portable_smoke project ... --out, then --projection).
• Whole-entry hold of talents (a partly affordable entry is held entirely); the budget order is deterministic, not optimal.
• Offline (non-runtime-session) play is not guarded against a cap change in between; run update after a cap change (the pin makes it write) before playing. Runtime sessions are guarded by the core.
• Item holding is by level only (equipment and bag slots), as in the audit; skill/proficiency requirements stay the realm's own business.
• No conflict-resolution UI, Registry, Relay, Wildcard, personal bank or equipment sets in this phase.