test: 甲子園クライアント契約テスト基盤（実サーバーのゴールデン記録 + jest）

[takaokouji]

Epic: #738 / Phase P0.5 + P2

ゴール

過去にゲームサーバー再実装が「仕様不明確」で頓挫した反省を踏まえ、実ゲームサーバーの挙動を
ゴールデン記録し、JS クライアントの整合性を jest で継続検証できる基盤を作る。コーナーケース
（水たまり・行動数上限・無効移動・タイムアウト・ゴール後・アイテム折半 等）を網羅する。

P0.5: ローカルで実サーバーを動かす

tmp/smalruby-koshien/game_server を devpod 環境で動かす。現状の課題:

• Ruby/bundler 未インストール。
• 古い構成: RSpec 3.2.0 / BUNDLED WITH 1.10.0.rc / PLATFORMS x86-mingw32（Windows 向け）/
  Encoding は binary・Windows-31J 前提。→ 現代 Ruby + UTF-8 で動かすための調整が要りそう。
• RSpec は HTTP を介さず API オブジェクトを直接 in-process で呼ぶ
  （spec/spec_helper.rb の SpecHelper::Server）。ゴールデン記録もこの方式を流用するのが堅い。

作業:

• Ruby（適切なバージョン）+ 必要 gem を install、bundle exec rspec を緑にする
• 起動・テスト手順を notes/koshien/ に整備（再現可能なスクリプト含む）

P2: ゴールデン記録 + jest 契約テスト

1. ゴールデン記録ドライバ（Ruby）: SpecHelper::Server を流用し、台本化したシナリオ
   （connect → 各種行動 → turnTransition …）を実行して、各 API の 入力 → JSON 返り値 を
   fixture（JSON）として書き出す。コーナーケースも台本に含める。
   • 出力先（案）: packages/scratch-vm/test/fixtures/koshien/golden/*.json
2. jest 契約テスト: 同じシナリオを JS クライアント（MockClient/将来の RemoteClient）に
   流し、出力がゴールデンに一致することを検証。
   • 置き場（案）: packages/scratch-vm/test/unit/koshien/contract/*.test.js（jest 化要検討。
     vm は通常 tap だが契約テストは jest でも可。要方針確認）

記録すべき挙動カタログ（game_server/spec/ 由来）

• 移動: 隣接のみ・斜め不可・無効座標でも行動消費・turnTransition 後に座標確定
• 水たまり: 進入で in_water、次 move は消費するが進まず flag 解除
• 行動数上限 2/ターン、move は 1/ターン、setMessage は数えない
• タイムアウト（10秒超過で行動破棄）、ゴール後 already_finished
• 採点: アイテム加減点・折半・歩行ボーナス・ゴールボーナス減衰・敵接触/撃破
• getMapArea 5×5・端クリップ・enemy は範囲外でも取得
• calc_route（client 側重み: BLANK=1/WATER=2/未探索=4/その他=3、既知空間優先）
• locate_objects（y→x 昇順、未探索除外）

Definition of Done

• ローカルで実サーバー（少なくとも in-process API 駆動）が動き、手順が notes に整備されている
• 主要シナリオ + コーナーケースのゴールデン fixture が生成できる（再生成スクリプトつき）
• jest 契約テストが MockClient に対して緑（一致 or 既知の差分を明示）
• CI で契約テストが回る
• notes/koshien/protocol.md の ❗（要検証）項目を実挙動で確認・更新

依存

• #A（MockClient）の存在を前提に契約テストを書く（並行着手は可、結合は #A 後）。