# Classic migration staging

Target: CMaNGOS Classic, client 1.12.1 build 5875, with CMaNGOS Playerbots.
This directory contains the staged adapter and migration helpers. A successful
build is not a completed migration or permission to bypass gameplay validation.

`stage-data.py --root /path/to/isolated/migration` observes an existing
`azerothai-classic-build` container, verifies the transferred MPQs against
`client-manifest.json`, and runs the upstream extractor with two worker threads.
The manifest maps relative MPQ paths to `size` and `sha256`. Checksums verify
transfer integrity against the supplied client manifest, not publisher authenticity.
The Docker builder image must be named `azerothai-classic-builder:local`; the
installed extractor must be under `run/bin/tools`. The staging directory and
container files belong to UID/GID 1000. Containers have a two-core/four-GiB limit.

Progress and failures are written to `prerequisites-status.json`. A successful
extraction is only a prerequisite: database import, the Classic control adapter,
the 50-character roster, account protection, and gameplay validation remain.
The script never starts the new realm, changes the old realm, or deletes bots.

`install-native.py SOURCE` installs the native adapter and version-checked hooks.
The adapter provides identity-bound snapshots, typed intentions, guarded native
party/guild invitations, bot-to-bot speech, durable command receipts, and Zaku's
damage floor. `AzerothAI.RestrictBotLogin=1` restricts native bot logins to an
explicit roster of at most 50 identities. `AzerothAI.Enable=1` enables observations
and managed login maintenance. Both settings default off in upstream builds.

`plan-roster.py ACTIVE_JSON OUTPUT_JSON` maps exactly 50 saved identities to
valid Vanilla combinations without changing faction. Death Knights become
Warriors, Alliance Shamans become Paladins, and Horde Paladins become Shamans.
Names remain stable; all characters are created at level 1 using native creation.

`bootstrap.py --root ROOT` waits for successful extraction and native compilation,
configures the isolated Classic world/database, starts a localhost-only game
port, creates the planned characters through the native console, and validates
all 50 identities and levels. It leaves those characters **offline**, writes
`classic-roster-bound.json`, and records progress in `bootstrap-status.json`.
It does not start authentication, change client configuration, or stop Wrath.

`prepare-state.py --root ROOT --live LIVE_REPO` prepares a separate dashboard
database from a consistent SQLite backup. It preserves active personalities and
labels older memories as historical, rebinds native IDs, and resets current-world
observations, command queues, and the population plan. It refuses to overwrite
an existing staging database. Run before starting the staging web runtime.

The staging app requires `GAME_BACKEND=cmangos-classic`. `relay.py --root ROOT
--url http://127.0.0.1:8791 --env-file ROOT/app-staging/.dev.vars` transfers only
validated typed commands into the Classic character database. It never executes
Lua or arbitrary game commands. Native receipts distinguish accepted intentions
from observed gameplay outcomes; interrupted commands are not replayed.

Remaining cutover gates include live quest/training/survival observations,
event telemetry and human-player conversation parity, dashboard/operator actions,
normal resurrection, actual party acceptance and speech, authentication/client
configuration, and a verified rollback route. Human-player chat delivery is
explicitly disabled in the staged Classic adapter until implemented and tested.

Migration safeguards:

- Preserve the verified Wrath backup and the active-50 identity export.
- Maintain 25 Alliance and 25 Horde. Use valid Vanilla race/class combinations.
- Start new Vanilla characters at level 1; do not directly import Wrath inventory,
  talent, spell, or quest tables. Blood Elves, Draenei, Death Knights, Alliance
  Shamans, and Horde Paladins need explicit compatible replacements.
- Retain personalities and historical memories; reset live observations, GUIDs,
  action queues, and progress baselines when binding the new characters.
- Protect human/GM accounts. Inactive managed profiles are cleanup candidates,
  not proof that corresponding game characters can safely be deleted.
- Test native bot login, progress, resurrection, safety rules, read-only visitor
  access, and current observations before switching the live dashboard or client.