fix: restrict riichi_stage discards to tenpai-maintaining tiles

[smly]

Fixes #196.

The original report attached a game log (game_0033_seed_50.zip, East 2nd / step 260) where this manifested as a riichi declared on a hand whose shape was no longer tenpai.

Fix

• Drop declaration_turn and rewrite the discard / riichi branch in state/legal_actions.rs and state_3p/legal_actions.rs into three explicit cases on the two flags:
  • riichi_declared → tsumogiri only.
  • riichi_stage → only discards that keep the hand tenpai, checked via HandEvaluator::is_tenpai (HandEvaluator3P for 3P). forbidden_discards is still respected.
  • otherwise → normal discards plus the Riichi option when the eligibility conditions are met.
• Add !riichi_stage to the inner check of the ActionType::Riichi branch in state/mod.rs and state_3p/mod.rs so the handler's precondition matches the legal-actions guard, even on paths that bypass step() validation.
• Add doc comments to riichi_declared and riichi_stage on PlayerState and PlayerState3P describing the mutual exclusion and the legal-action restrictions that must hold while riichi_stage is set.

[Copilot]

Pull request overview

Fixes a riichi state-machine bug where a Riichi action with tile = None (e.g. mjai reach) could be followed by a discard that breaks tenpai, by tightening legal-action generation and aligning handler-side preconditions.

Changes:

• Reworks 4P/3P legal_actions discard/riichi logic into explicit cases for riichi_declared vs riichi_stage, restricting riichi_stage discards to tenpai-maintaining tiles.
• Adds !riichi_stage to the ActionType::Riichi handler guards in both 4P/3P to prevent double-riichi while mid-declaration.
• Adds a regression test and documents riichi_declared/riichi_stage invariants on player state structs.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
riichienv-core/src/tests.rs	Adds regression test ensuring riichi_stage only offers tenpai-maintaining discards and does not re-offer Riichi.
riichienv-core/src/state/legal_actions.rs	Implements three-case discard/riichi branching; enforces tenpai-maintaining discards during riichi_stage and tsumogiri-only after riichi_declared.
riichienv-core/src/state/mod.rs	Adds !riichi_stage precondition to the Riichi action handler to prevent re-entrant riichi declarations.
riichienv-core/src/state/player.rs	Documents riichi_declared/riichi_stage meaning and constraints for 4P player state.
riichienv-core/src/state_3p/legal_actions.rs	Mirrors the 4P legal-actions rewrite for 3P using HandEvaluator3P::is_tenpai.
riichienv-core/src/state_3p/mod.rs	Adds !riichi_stage guard to the 3P Riichi action handler.
riichienv-core/src/state_3p/player.rs	Documents riichi_declared/riichi_stage meaning and constraints for 3P player state.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.