# 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.

`install-staging-services.py --root ROOT` installs isolated user services for
port 8791, the native relay, and autonomy. Stop manually launched staging
processes first. Services restart on failure and leave the live Wrath services
unchanged. The worker credential file is private to the owner.

The rebuildable item-info cache uses InnoDB with a dynamic row format so the
upstream builder's transaction batches writes with full database durability.
The bootstrap records the existing native bot account range for login
registration and enables activity even when no human player is present.
Automatic population creation remains disabled; the native identity allowlist
still limits managed login to the planned 50.

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.