mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-19 19:25:56 +00:00
Phase 8: documentation
This commit is contained in:
1 parent
ffb1df3fce
commit
c2e4634367
4 files changed
+123
No files matched your search
@@ -122,3 +122,9 @@ after every import, update and re-evaluation). When the realm's profile changes:
|
||||
* A held-back **selection** is restored by a re-evaluation (a profile change); a held-back **extension** is applied by it; nothing is re-applied when the profile did not change.
|
||||
* Whether the profile of a running realm still matches (a core upgraded in place) is noticed only when it is read again; there is no push.
|
||||
* The Host driver is still a library plus the harness; the profile is not yet fetched by the Manager application on its own.
|
||||
|
||||
## 7. Phase 8: profile version 2 (progression)
|
||||
|
||||
`profile_version` is 2: the profile gains `progression` (the running core's `MaxPlayerLevel`, projection protocol/policy, an opaque `progression_signature`, `scaling_enabled`), outside
|
||||
the content hash, and `Feature::LevelProjection`. A stored version 1 profile is migrated on read (content and hash unchanged, `progression = None`); with no progression every operation
|
||||
is `Blocking` until the realm is probed through its core. The core report is version 2 (version 1 cores are still read, without progression). See `PORTABLE_LEVEL_PROJECTION.md`.
|
||||
@@ -0,0 +1,106 @@
|
||||
# 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
|
||||
|
||||
```text
|
||||
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.
|
||||
@@ -168,3 +168,8 @@ Findings:
|
||||
* **Setup facts** (for the next person): the client's saved `realmName` must equal the realm's name or it loops on
|
||||
`REALM_NOT_FOUND`; a race/class needs a `playercreateinfo` row to be imported (race 3 / class 23 has none on this data); stale
|
||||
`online` flags and a realm flag of 3 block imports and the authserver respectively.
|
||||
|
||||
## Phase 8: projected characters
|
||||
|
||||
Reconcile and update of a character that is projected on a realm (level above its cap) use the same `merge3`, with the level and xp of the working copy frozen (reconcile) or taken from
|
||||
the new view (update) and the stored build records merged by key. See `PORTABLE_LEVEL_PROJECTION.md`.
|
||||
@@ -246,3 +246,9 @@ tests above instead.
|
||||
|
||||
Known limits: a bot session has no socket, so the gate's packet hold and kick are only exercised for real clients by a manual test; the
|
||||
core's job parser is exercised through the live importer test, not through its own unit tests.
|
||||
|
||||
## 11. Phase 8: protocol version 2
|
||||
|
||||
`PROTOCOL_VERSION` is 2. `PortableSessionStarted` carries `progression {pin, projection?}`, `PortableCheckpoint` and `OwnerAck` carry the `pin` (cap, policy, progression signature,
|
||||
content profile hash, projected or native). The Owner stores the pin at the start and refuses a checkpoint under any other pin; a realm whose progression moves under an open session ends
|
||||
it with a final checkpoint taken under the old pin and does not arm the next session until the working copy is projected again. See `PORTABLE_LEVEL_PROJECTION.md`.
|
||||
Reference in new issue
Block a user