Files
coa-server-manager/docs/MULTIRULESET_PORTABLE_AUDIT.md
T
Дмитрий ba143e1ccd fix(control): MR2.1 fail-closed world-port resolution and ruleset invariant verification
- Make world_port resolution fallible (Result<u16>) across LocalBackend, HostService, DirectRouteManager, and RelayLink without default fallbacks to 8085.
- Enforce strict 4-way invariant: local_id ruleset == RealmAccess.mode == Db.realm() == RealmInfo.ruleset. Malformed or unknown suffixes fail closed.
- If Wildcard is selected and world-port resolution fails (or simultaneous mode is disabled), Direct and Relay fail closed with actionable error and zero fallback to CoA.
- Fix documentation drift in docs/WILDCARD.md and docs/MULTIRULESET_PORTABLE_AUDIT.md regarding simultaneous execution, distinct ports, and current vs historical baseline.
2026-10-22 18:10:49 +05:00

12 KiB

Multi-Ruleset Realms & Portable Characters: Architectural Audit

This audit evaluates the architecture to support three independent, strictly isolated gameplay rulesets:

  1. Conquest of Azeroth (coa)
  2. Wildcard (wildcard)
  3. Warcraft Reborn (reborn)

Date: October 2026
Status: Updated for MR2 Gate (Wildcard Vertical Slice Completed)


1. Executive Summary: Baseline vs Implemented vs Planned

1.1 Baseline Discovered Before Implementation (v0.7.0 Master)

  • realms::Mode defined Coa, Wildcard, and Reborn for local realm profiles and database switching (acore_characters, acore_characters_wildcard, acore_characters_reborn).
  • The Portable Characters and Public Realm Registry subsystems were designed almost entirely around coa, with experimental/preliminary partial awareness of wildcard, and an explicit blocking error for reborn (ruleset_of: "Portable characters are not supported on Warcraft Reborn realms yet").
  • SQLite character table had CHECK (ruleset IN ('coa', 'wildcard')), which hard-failed on any reborn row.
  • SQLite collection table was keyed by (profile_id, kind) without ruleset, causing cross-ruleset collision.
  • Request::TransferOffer, PortableSessionStarted, PortableCheckpoint, OwnerAck, CollectionObserved, CollectionState, and CollectionAck lacked explicit protocol-level ruleset fields or version negotiation.
  • Collection validation used unsafe prefix checks (kind.starts_with(ruleset)), permitting prefix confusion attacks.
  • Ruleset::schema(kind) contained a fallback _ => "acore_characters", routing unknown database kinds to CoA.

1.2 Implemented in MR1, MR1.1, and MR2

  • Authoritative Ruleset Enum: Ruleset (Coa, Wildcard, Reborn) unified across coa-core, coa-registry-proto, coa-control-proto, and frontend models.
  • Transactional SQLite Migration 009: Migrates released v0.7.x databases by recreating both collection (composite key profile_id, ruleset, kind) and character (CHECK constraint allowing 'coa', 'wildcard', 'reborn') with FK toggles ensuring zero child row loss.
  • Fail-Closed Realm Backend: Removed unsafe unwrap_or(Ruleset::Coa) in LocalBackend::info(). Unreadable, unknown, or broken realms fail closed immediately with error rather than falling back to CoA.
  • Control Protocol 2 & Strict Envelopes:
    • CONTROL_PROTOCOL_VERSION = 2.
    • Request::TransferOffer requires explicit ruleset: String.
    • Response::Claimed returns explicit ruleset: String.
    • Claiming and commit verify that the claimed envelope ruleset matches the decoded payload ruleset and matches target realm ruleset.
    • HostTransfer stores ruleset in SQLite; transfer_commit verifies that canonical JSON hash and ruleset match the offer and destination realm before writing to disk.
  • Session Protocol 3 & Ruleset Enforcement:
    • SESSION_PROTOCOL_VERSION = 3 and COLLECTION_PROTOCOL_VERSION = 2.
    • SessionOffer, PortableSessionStarted, PortableCheckpoint, and OwnerAck require explicit ruleset.
    • Any mismatch between character ruleset, offer ruleset, session ruleset, or checkpoint ruleset rejects immediately with zero DB mutation and zero canonical revision advance.
  • Wildcard Collections Isolation:
    • wildcard:appearance and wildcard:vanity isolated from coa:appearance and coa:vanity.
    • Cross-ruleset collection merges strictly rejected by carried_kind_for(kind, ruleset).
  • Database Routing & Three-Space Isolation:
    • Canonical SQL routes through Db::query() and realm_schema to acore_characters_wildcard and acore_world_wildcard.
    • Multiple characters sharing local GUIDs on distinct server IDs (srv-1:coa, srv-1:wildcard, srv-1:reborn) coexist with zero collision in character mappings and item mappings.
    • Mutating Wildcard character state, revisions, or collections leaves CoA and Reborn states 100% byte-for-byte untouched.
  • Direct & Relay Routing for Wildcard:
    • world_port_for_mode dynamically determines active world port (8085 for primary CoA, 8086 for secondary Wildcard in simultaneous mode).
    • Direct Ingress proxy and Relay link dynamically route to the correct realm world port.
    • Direct Ingress Auth rewrite replaces internal realm list address with external mapped Wildcard port (e.g. 48086) and never advertises CoA port 8085.

1.3 Still Planned (Subsequent Milestones)

  • MR3 (Warcraft Reborn Vertical Slice): Unlocking ruleset_of for Reborn, import/export adapters, and live verification.
  • MR4 (Multi-Realm Publication UI & Registry): Simultaneous publication of multiple RealmIds from a single Manager host under distinct identities and keypairs.

2. Current Implementation Architecture & Historical Baseline Inventory

2.1 Current Implementation State (As of MR1, MR1.1, MR2, MR2.1)

  • Authoritative Ruleset Representation:
    • crates/coa-core/src/portable/model.rs: enum Ruleset { Coa, Wildcard, Reborn } (strict parsing and schema routing without fallbacks).
    • crates/coa-registry-proto/src/caps.rs: enum Ruleset { Coa, Wildcard, Reborn }.
    • services/coa-registry/src/pg.rs: ruleset: match ruleset.as_str() { "coa" => Ruleset::Coa, "wildcard" => Ruleset::Wildcard, "reborn" => Ruleset::Reborn, ... }.
    • src/lib/browse.ts: export type Ruleset = "coa" | "wildcard" | "reborn";.
    • crates/coa-core/src/realms.rs: enum Mode { Coa, Wildcard, Reborn }.
  • Wire Protocols & Ruleset Requirements:
    • Control Protocol 2: CONTROL_PROTOCOL_VERSION = 2. Request::TransferOffer requires explicit, non-default ruleset: String. Response::Claimed returns explicit ruleset: String. HostTransfer records ruleset.
    • Session Protocol 3: SESSION_PROTOCOL_VERSION = 3. SessionOffer, PortableSessionStarted, PortableCheckpoint, and OwnerAck require explicit, mandatory ruleset: Ruleset.
    • Collection Protocol 2: COLLECTION_PROTOCOL_VERSION = 2. CollectionObserved, CollectionState, and CollectionAck require explicit, mandatory ruleset: Ruleset.
  • Database Routing & Fail-Closed Invariants:
    • LocalBackend::info() and LocalBackend::access() strictly enforce: \text{local\_id ruleset} == \text{RealmAccess.mode} == \text{Db.realm()} == \text{RealmInfo.ruleset} Any mismatch or malformed/unknown ruleset suffix returns an immediate error.
    • LocalBackend::world_port() and crates/coa-core/src/realms::world_port_for_mode() return fallible Result<u16> without silent fallbacks to 8085. If a realm is not running or not simultaneous, port resolution fails closed and disables Direct and Relay routing for that realm.
  • Canonical Storage (portable.db):
    • Transactional SQLite Migration 009 upgraded character table constraint to CHECK (ruleset IN ('coa', 'wildcard', 'reborn')) while preserving rows byte-for-byte.
    • collection table is partitioned by (profile_id, ruleset, kind).
    • Mappings (character_server_mapping, item_mapping, pet_mapping, sessions) isolate distinct server IDs (srv-X:coa, srv-X:wildcard, srv-X:reborn).

2.2 Historical Baseline Inventory (Pre-Implementation State as of v0.7.0 Master)

Note

The following findings reflect the legacy v0.7.0 baseline discovered before MR1/MR2 implementation and are preserved for historical reference:

  • Historical: Ruleset enum in model.rs and caps.rs lacked Reborn.
  • Historical: character table had CHECK (ruleset IN ('coa', 'wildcard')), causing SQLite constraint failures on Reborn.
  • Historical: collection table was keyed only by (profile_id, kind) without ruleset.
  • Historical: TransferOffer, PortableSessionStarted, PortableCheckpoint, and CollectionState lacked explicit protocol-level ruleset fields.
  • Historical: LocalBackend::info() had an unsafe fallback ruleset_of(db).unwrap_or(Ruleset::Coa).
  • Historical: world_port_for_mode() fell back to ports.world (8085) even when Wildcard was inactive.
  • Historical: Ruleset::schema(kind) had _ => "acore_characters".

2.3 Realm Profiles & Databases (crates/coa-core/src/realms.rs, db.rs)

Ruleset / Mode Realm ID Character Database World Database Auth Database Configuration Profile
CoA 1 acore_characters acore_world acore_auth Settings/realm-profiles/coa.json
Wildcard 2 acore_characters_wildcard acore_world_wildcard acore_auth Settings/realm-profiles/wildcard.json
Warcraft Reborn 3 acore_characters_reborn acore_world_reborn acore_auth Settings/realm-profiles/reborn.json
  • Simultaneous Startup Policy:
    • CoA + Wildcard simultaneous is supported via secondary_world_port and secondary_ra_port (CoA on primary world port 8085, Wildcard on secondary e.g. 8086).
    • Warcraft Reborn simultaneous startup is strictly unsupported (s.simultaneous && s.active == Mode::Reborn returns Error::Invalid("Simultaneous startup supports CoA and Wildcard only.")).
  • Worldserver Capability Detection:
    • Executable inspected directly (Core/worldserver.exe on Windows repack, Core/worldserver on Linux Docker).
    • Wildcard detected by byte pattern: b"Wildcard synergy settings".
    • Reborn detected by byte pattern: b"Warcraft Reborn class spells are unavailable".

2.4 Public Registry Model & Multi-Realm Publication

  • crates/coa-core/src/realm_registry/settings.rs: RegistrySettings.realms is a BTreeMap<String, PublishConfig>.
  • src/screens/PublishCard.tsx: Uses localId = 'srv-' + serverId.
  • Multi-Realm Publication on One Host: Each published realm possesses its own distinct local realm identity (srv-<id>:<ruleset>), unique RealmId (UUIDv7), and independent Ed25519 signing key in KeyStore. Direct Ingress proxy and Relay links dynamically route to the respective realm's active world port.

3. Strict Isolation Invariants

The fundamental architectural invariant is:

\text{portable\_character.ruleset} == \text{target\_realm.ruleset}

On mismatch:

  1. Zero DB Mutation: No rows written to acore_characters*, item_instance, or modules.
  2. Zero Session Creation: No host_session or owner_session record opened or armed.
  3. Zero Mapping Creation: No entry in character_server_mapping, item_mapping, or pet mapping.
  4. Zero Collection Merge: No union into collections of a different ruleset.
  5. Zero Canonical Revision Change: Canonical revision remains unchanged; reject with explicit mismatch error.
  6. No Implicit Conversion: Never attempt conversion, level projection across rulesets, or guessing missing rulesets.

4. Execution Plan & Phasing

  1. Authoritative RulesetId Abstraction (Section 3):
    • Normalize RulesetId / unified enum across coa-core, coa-registry-proto, coa-control-proto, and TypeScript models.
    • Values: coa, wildcard, reborn.
  2. Partitioning Collections & Canonical Storage (Sections 8, 11):
    • Add SQLite migration 009_multiruleset_collections.sql partitioning collections by (profile_id, ruleset, kind) and expanding character table ruleset constraint to allow 'reborn'.
    • Update Store APIs to accept ruleset: Ruleset on character operations and collection operations.
  3. Registry & Multi-Realm Publication on One Host (Sections 5, 6, 26):
    • Partition published realm keys: srv-<serverId>:<ruleset>.
    • Each published realm receives its own RealmId, Ed25519 key, heartbeat, status, and capabilities.
    • Registry PostgreSQL migration for reborn ruleset check.
  4. Remote Transfer Envelope & Session Binding (Sections 14, 22):
    • Add ruleset to TransferOffer, PortableSessionStarted, PortableCheckpoint.
    • Enforce 4-way equality: envelope ruleset == payload ruleset == published realm ruleset == host target DB ruleset.
  5. Wildcard Vertical Slice (Section 15):
    • End-to-end testing of Wildcard claiming, transfer, session, checkpoint, and collection partitioning.
    • Verify negative cross-ruleset attack scenarios.
  6. Warcraft Reborn Audit & Vertical Slice (Sections 18, 19):
    • Complete docs/REBORN_PORTABLE_AUDIT.md.
    • Wire Reborn adapter into the unified engine and verify vertical slice.
  7. UI Multi-Ruleset Filtering (Sections 7, 27):
    • Server browser ruleset tabs/filters (All, Conquest of Azeroth, Wildcard, Warcraft Reborn).
    • Portable character picker filtered by target realm ruleset.
  8. Regression & Cross-Ruleset Attack Test Suite (Section 29):
    • Comprehensive unit and integration attack tests ensuring strict isolation.