[Roxas2712]

Depends on #105 and its API prerequisites; merge those first and rebase before merging this PR. The focused change is commit 602302a8362cea3e0238b4cf7d53b5226f72f269 (implementation-only diff). No shader dependency.

API-3 mods can start a wild encounter through mod.world:startWildBattle(species, level, onDone?) on generations 1–3. Validate canonical species, whole levels 1–100, optional callbacks, healthy non-egg party and idle-world ownership before native construction. Use the native BattleState constructor and overworld pushBattle/afterBattle entries rather than constructing a replacement battle flow. Gen4/5 and API-1/2 behavior remain unchanged.

Completion is one-shot, attributed, error-isolated and deferred past admission for synchronous native completion. Observed session changes and mod rollback/reload/unload permanently retire stale mod callbacks. An admitted battle retains its native cleanup after mod unload; late results cannot mutate a replaced save. Share the synchronous mutation guard with NPC/object/block actions.

Public contract and reproduction.

Validation

• 135/135 targeted checks, including actual host BattleState/Pokemon construction and Pokedex seen changes on synthetic data for Red, Gold, Crystal, FireRed and Emerald; busy/malformed requests, session replacement, unload, callback replay/errors, synchronous completion and failure/guard release.
• 56 cross-engine comparisons / 112 isolated loader runs at the clean committed feature head against clean pinned Gen1 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36. Same public-only mod on both production loaders for Red, Blue, Yellow, Gold, Silver, Crystal, FireRed and Emerald. Native battle construction/transition/cleanup timing are instrumented driver seams; this does not establish retail-ROM battle, evolution, blackout or rendered-transition equivalence.
• Full ROM-free run: 80/90 engine, 3/3 mod-SDK, B30 PASS. Fresh Add API 3 public NPC actions with cross-engine contracts #105 baseline: 79/89 engine, SDK/B30 passing. All 27 full FAIL lines are unchanged, exactly and in order.
• All-PR integration through Add API 3 public NPC actions with cross-engine contracts #105 plus this commit: 85/95 engine, SDK3/3, B30 PASS; same exact baseline failures. All 56 comparisons /112 runs pass on that clean integration tree too.
• Lua formatting and diff checks pass. Existing API-3 CI automatically includes the new wild_battle mode.

Unchanged failing suites: gate_fingerprint, gate_meta_coverage, quit_thread_shutdown, rebind_capture_bug510, rebind_swap_clear_bug589, soft_reset_bug563, tool_mod_hooks, update_check_tests, update_tests, wide_battle_layout. Full test entry remains nonzero because of these baseline failures. Native effects after entering construction are not transactionally rolled back.

Hosted CI

Published open/non-draft at the tested commit; GitHub reports no merge conflicts. API 3 contracts and ci currently conclude action_required pending maintainer approval for the fork workflows. Hosted CI is not green; the validation above ran locally.