test(scratch-vm): 甲子園 実サーバーのゴールデン記録 + 契約テスト基盤

[takaokouji]

Summary

過去にゲームサーバー再実装が「仕様が不明確」で頓挫した反省を踏まえ、実ゲームサーバーの挙動をゴールデン JSON として記録し、クライアントが従うべき契約をテストで固定する基盤を追加します。Epic #738 / #740。

どうやって記録したか

tmp/smalruby-koshien/game_server（実ゲームサーバー, Ruby）の in-process API ドライバ（サーバー自身の RSpec が使う SpecHelper::Server）を流用し、決定的シナリオ（SK_RANDOM_SEED=1）を実行して各 API の返り値を JSON 化しました。レガシーな Windows 向けコードを Ruby 3.1 で動かすための移植手順・記録ドライバはプロジェクトノート（git 管理外）に整備済みです。

Changes Made

• test/fixtures/koshien/golden/*.json — 実サーバーのゴールデン記録:
  • move_basic: move_to は予約で、座標は turnTransition 後に確定（before [1,1] → after [2,1]）
  • get_map_area: getMapArea は 15x15 の自分マップ（未探索 -1）+ enemy + other_player を返す（※5x5 ではない、という実挙動を記録）
  • two_actions: 1 ターン 2 行動（move_to + getMapArea）
• test/fixtures/koshien/golden/README.md — 出自・再生成方法・実挙動メモ
• test/unit/extensions/koshien_golden_contract.js（tap）— ゴールデンの実挙動を検証（構造の健全性 + 移動の予約セマンティクス + マップ形状）。将来の RemoteClient（feat(scratch-vm): 甲子園 実ゲームサーバー通信モード（RemoteClient） #741）が replay する契約の基盤。

なぜ MockClient と比較しないのか

MockClient（#739）は未接続時用に固定値を返すため、実サーバーのシナリオ応答とは一致しません（意図的）。本 PR は 実挙動を検証済み fixture として固定し、RemoteClient（#741）実装時にそれへの一致を assert できるようにする基盤です。

Test Coverage

• koshien_golden_contract.js: tap 51 assertions pass。
• lint 緑（eslint 0 errors、prettier OK。既存の無関係な warning のみ）。

Definition of Done

• 実サーバーをローカル（Ruby 3.1）で起動し spec を実行できる（手順を notes に整備）
• 主要シナリオのゴールデン fixture を生成（再生成スクリプトあり）
• 契約テスト（tap）が緑
• CI green
• （後続）コーナーケース（水たまり・行動数上限・無効移動・タイムアウト・ゴール後）の fixture 追加
• （後続 feat(scratch-vm): 甲子園 実ゲームサーバー通信モード（RemoteClient） #741）RemoteClient をゴールデンに対して検証

Related Issues

Refs #740 / Epic #738

🤖 Generated with Claude Code

[github-actions]

🚀 Preview deployed: https://smalruby.jp/smalruby3-editor/feature/issue-740-koshien-golden-contract/