Port the Smart AI effect handlers (#28)

Translate every AI_Smart_EffectHandlers entry, so trainers with the Smart layer are no longer refused. The AI's type checks keep the CheckTypeMatchup bug: they read the move type and Foresight flag through hBattleTurn, and Conversion2's write to the player's move type persists.

The reference emulator runs the unmodified AI_Smart routine over 6,024 states per browser, comparing scores, Random consumption, hBattleTurn and the player's move type. Validated with 579 unit tests, 151 browser tests, native/reference builds and reference/vendor/release checks. Kurt's balls, Park and Safari balls and special battle types remain on #28.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/NATIVE_PORT.md

@@ -98,7 +98,7 @@ Native saves are version 3. Version 2 added scene values by owning map, phone co
 
 `game/rom/trainers.ts` decodes `TrainerGroups`, `TrainerClassAttributes`, `TrainerClassNames`, `TrainerClassDVs` and map trainer headers. Tests cover all 542 ROM records across 67 classes; CAL2 construction refuses its SRAM-dependent Mystery Gift party.
 
-`game/battle/ai.ts` translates `AIChooseMove`, `AI_Redundant` and the Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky layers. It preserves the original random tie selection, known redundancy quirks, HP thresholds, exclusions and the deterministic pre-variation damage estimate used by Aggressive and Risky. Smart runs only for move effects that have no `AI_Smart_EffectHandlers` entry (Normal Hit, Attack Down, Defense Down; enough for the first rival). Other effects are refused before any random draw. Synthetic scoring vectors establish the tested branches; original-engine AI execution parity is still pending.
+`game/battle/ai.ts` translates `AIChooseMove`, `AI_Redundant` and the Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky layers. It preserves the original random tie selection, known redundancy quirks, HP thresholds, exclusions and the deterministic pre-variation damage estimate used by Aggressive and Risky. `game/battle/smart-ai.ts` translates every `AI_Smart_EffectHandlers` entry, including its random thresholds, byte score wrapping and the `CheckTypeMatchup` bug: the AI's type checks read the move struct and Foresight flag through `hBattleTurn`, so they can use the player's struct, and Conversion2's write to it persists. `tests/reference-smart-ai.spec.ts` runs the unmodified `AI_Smart` routine in the reference emulator for all 251 moves, comparing scores, Random consumption, `hBattleTurn` and the player's move type. Synthetic scoring vectors cover the other layers.
 
 `loadtrainer`, `winlosstext` and `startbattle` run scripted trainer battles through the existing battle UI. Tests cover Joey's ROM party/text/reward, RUN refusal, trainer experience, Amulet Coin, CANLOSE behavior, money limits, transactional rollback and midbattle restore. Chromium and WebKit exercise the UI with a test-only script.
 

docs/PLAN.md

@@ -297,7 +297,14 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Exp. Share halves experience and stat-experience bytes before splitting the participant and holder pools. Healthy holders receive the second pool, including a holder that also fought; fainted holders are excluded. Existing traded, trainer, Lucky Egg and Pokérus modifiers still apply to each award.
 - Traded Pokémon obey according to the world's Johto badges. Disobedience preserves the original random draws and can ignore orders, nap, hurt itself or use another move; it spends only the alternate move's PP and breaks Encore where the original does.
 - Consumed healing and confusion berries are removed from a trainer's stored party too, so switching cannot restore them.
-- Local-ROM regressions cover these paths; the reference emulator compares Metal Powder over 320 cases in each browser. The other new routines have source review and unit coverage, without a direct emulator comparison yet. Smart AI handlers remain unfinished; card #28 is still in progress.
+- Local-ROM regressions cover these paths; the reference emulator compares Metal Powder over 320 cases in each browser. The other new routines have source review and unit coverage, without a direct emulator comparison yet.
+
+## Implemented: Smart AI
+
+- Every `AI_Smart_EffectHandlers` entry is translated, so trainers with the Smart layer are no longer refused. The handlers read battle history, stat levels, both parties' reserves, the switch score and the weather.
+- The AI's type checks keep the original `CheckTypeMatchup` bug: the move type and Foresight flag come from whichever side `hBattleTurn` names, so Encore and the switch score can read the player's move struct. Conversion2's write to the player's move type persists, as in the original.
+- `tests/reference-smart-ai.spec.ts` runs the unmodified `AI_Smart` routine in the reference emulator over 6,024 states (all 251 moves, random battle state, either starting turn), comparing scores, Random consumption, `hBattleTurn` and the player's move type. A one-off run over 18,072 more states also matched in both browsers.
+- Card #28 stays in progress for Kurt's balls, the Park and Safari balls and the special battle types.
 
 ## Native battles: current state
 
@@ -381,7 +388,7 @@ Introduce native player, party, Pokémon, inventory, money and quest models. Rea
 
 Expand script calls, choices, scene state, inventory commands and native special handlers. Translate routines reached through assembly calls into explicit native services; never fall back to emulator execution in the shipping game.
 
-Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, the options, Fly, Dig, Teleport and the Escape Rope, and Headbutt and Rock Smash with their encounters, every remaining field item, the fishing rods, MAIL, moving items with Select and the MOVE screen's other Pokémon. Next: the remaining battle commands, move effects and Smart AI handlers (board #28).
+Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, the options, Fly, Dig, Teleport and the Escape Rope, and Headbutt and Rock Smash with their encounters, every remaining field item, the fishing rods, MAIL, moving items with Select and the MOVE screen's other Pokémon. Next: Kurt's balls, the Park and Safari balls and the special battle types (board #28).
 
 Complete and validate the native battle engine: deterministic randomness, stats, move selection, accuracy/critical checks, damage, status, turn order, switching, fainting, experience, capture and rewards. Compare controlled seeds and states with the original, including integer rounding and overflow behavior.
 

docs/SESSION_HANDOFF.md

@@ -1224,3 +1224,29 @@ move list or loop indefinitely. Johto badge stat boosts are still absent;
 the new badge option implements obedience only. Do not claim the battle
 engine or the full card is complete. Delivery is tracked by the commits
 referencing card #28; its commit list includes the recovered groups above.
+
+## Smart AI handlers: 2026-10-03
+
+Codex resumed card #28 after `32d736e` and stopped at its usage limit at
+13:21 UTC with an uncommitted Smart AI translation (`smart-ai.ts`), partial
+battle wiring and a failing emulator spec. Claude Code took it over.
+
+- The spec showed 35 of 6,024 states differing, in five handlers. Encore,
+  Roar/Whirlwind, Baton Pass and Perish Song came from `CheckTypeMatchup`
+  ignoring the type in `a`: it reads the move type and Foresight flag through
+  `hBattleTurn`. The AI now tracks the turn and both move structs' types;
+  `checkPlayerMoveTypeMatchups` takes the type and flag. Conversion2's write
+  to the player's move type persists in the battle.
+- Psych Up sums `NUM_LEVEL_STATS` (8) bytes. The eighth is only ever reset to
+  7 or copied, so the 7-entry sum is equivalent; the spec now writes it as 7.
+- The spec randomizes the starting turn and the player's move type and also
+  compares them afterwards. It passes 6,024 states per browser; a one-off
+  run with another seed passed 18,072 per browser.
+
+Validation: 579 unit tests passed (3 skipped); without the ROM 138 passed,
+444 skipped. Browser suite: 151 passed, 19 intentional skips. Both builds,
+reference/release/vendor checks and `git diff --check` passed. No CI or
+physical-device validation.
+
+Next on #28: Kurt's balls, Park and Safari balls, and special battle types.
+Other boundaries listed in the previous section are unchanged.