AzerothAI/deploy/classic/README.md

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.

Before cutover, verify fresh 50-character observations, quest and spell outcomes, normal resurrection, actual party receipts, native GM commands, authentication, and rollback. Human player replies require an actual in-game session for an end-to-end acceptance check. Lua/ALE reflection remains a Wrath-only capability.

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.

Native outcome hooks now report quest completion/rewards, loot item counts, looted copper, deaths, resurrection and learned spells. These are separate from accepted intentions. The configured native auto-learn policy is invoked on managed level changes; this is not a claim of trainer purchases. Player say and whisper events bind the sender's native character/account identity and replies revalidate that identity. Basic GM commands use Classic's own SOAP namespace; Wrath-only Lua operator calls are rejected explicitly.

prepare-auth.py --root ROOT prepares a private Classic service GM account, copies only ENDAMI's existing SRP credentials into the isolated authentication database, and disables upstream sample logins. check-auth.py --root ROOT verifies a complete SRP handshake and realm listing without entering the game. health.py --root ROOT --url URL reports host health without Wrath SQL.

cutover.py --root ROOT requires a passing build and all 50 fresh staging bots, backs up stopped Wrath accounts/characters, switches the existing endpoints, and automatically restores Wrath endpoints if login or population verification fails. Miniflare metadata databases are excluded from game-state backup selection.