sashite-ggn 0.3.0 → 0.6.0

data/lib/sashite/ggn/move_validator.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    # Centralized module for move condition validation.
+    # Contains shared logic for validating piece ownership and board positions
+    # in GGN move evaluation.
+    #
+    # This module focuses exclusively on board-based validation since GGN
+    # only handles board-to-board transformations. All methods work with
+    # pieces on the board and use GAN (General Actor Notation) identifiers.
+    module MoveValidator
+      # Separator in GAN (General Actor Notation) identifiers.
+      # Used to split game identifiers from piece identifiers.
+      #
+      # @example GAN format
+      #   "CHESS:K"  # game: "CHESS", piece: "K"
+      #   "shogi:+p" # game: "shogi", piece: "+p"
+      GAN_SEPARATOR = ":"
+
+      private
+
+      # Checks if the correct piece is present at the origin square on the board.
+      #
+      # This method validates that the expected piece is actually present at the
+      # specified origin square, which is a fundamental requirement for any move.
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param origin [String] Origin square
+      # @param board_state [Hash] Current board state
+      #
+      # @return [Boolean] true if the piece is at the correct position
+      #
+      # @example Valid piece placement
+      #   board_state = { "e1" => "CHESS:K", "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => true
+      #
+      # @example Invalid piece placement
+      #   board_state = { "e1" => "CHESS:Q", "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => false (wrong piece at e1)
+      #
+      # @example Empty square
+      #   board_state = { "e1" => nil, "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => false (no piece at e1)
+      def piece_on_board_at_origin?(actor, origin, board_state)
+        return false unless valid_gan_format?(actor)
+        return false unless origin.is_a?(String) && !origin.empty?
+        return false unless board_state.is_a?(Hash)
+
+        board_state[origin] == actor
+      end
+
+      # Checks if the piece belongs to the current player based on case matching.
+      #
+      # This method implements the corrected ownership logic based on FEEN specification:
+      # - Ownership is determined by case correspondence, not exact string matching
+      # - If active_game is uppercase, the player owns uppercase-cased pieces
+      # - If active_game is lowercase, the player owns lowercase-cased pieces
+      # - This allows for hybrid games where a player may control pieces from different games
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param active_game [String] Current player's game identifier
+      #
+      # @return [Boolean] true if the piece belongs to the current player
+      #
+      # @example Same game, same case (typical scenario)
+      #   piece_belongs_to_current_player?("CHESS:K", "CHESS")
+      #   # => true (both uppercase)
+      #
+      # @example Different games, same case (hybrid scenario)
+      #   piece_belongs_to_current_player?("MAKRUK:K", "CHESS")
+      #   # => true (both uppercase, player controls both)
+      #
+      # @example Same game, different case
+      #   piece_belongs_to_current_player?("chess:k", "CHESS")
+      #   # => false (different players)
+      #
+      # @example Mixed case active_game (invalid)
+      #   piece_belongs_to_current_player?("CHESS:K", "Chess")
+      #   # => false (invalid active_game format)
+      def piece_belongs_to_current_player?(actor, active_game)
+        return false unless valid_gan_format?(actor)
+        return false unless valid_game_identifier?(active_game)
+
+        game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
+
+        # Determine player ownership based on case correspondence
+        # If active_game is uppercase, player owns uppercase pieces
+        # If active_game is lowercase, player owns lowercase pieces
+        case active_game
+        when active_game.upcase
+          # Current player is the uppercase one
+          game_part == game_part.upcase && piece_part.match?(/\A[-+]?[A-Z]'?\z/)
+        when active_game.downcase
+          # Current player is the lowercase one
+          game_part == game_part.downcase && piece_part.match?(/\A[-+]?[a-z]'?\z/)
+        else
+          # active_game is neither entirely uppercase nor lowercase
+          false
+        end
+      end
+
+      # Validates the GAN format of an identifier.
+      #
+      # A valid GAN identifier must:
+      # - Be a string containing exactly one colon separator
+      # - Have a valid game identifier before the colon
+      # - Have a valid piece identifier after the colon
+      # - Maintain case consistency between game and piece parts
+      #
+      # @param actor [String] Identifier to validate
+      #
+      # @return [Boolean] true if the format is valid
+      #
+      # @example Valid GAN identifiers
+      #   valid_gan_format?("CHESS:K")     # => true
+      #   valid_gan_format?("shogi:+p")    # => true
+      #   valid_gan_format?("MAKRUK:R'")   # => true
+      #
+      # @example Invalid GAN identifiers
+      #   valid_gan_format?("CHESS")       # => false (no colon)
+      #   valid_gan_format?("chess:K")     # => false (case mismatch)
+      #   valid_gan_format?("CHESS:")      # => false (no piece part)
+      def valid_gan_format?(actor)
+        return false unless actor.is_a?(String)
+        return false unless actor.include?(GAN_SEPARATOR)
+
+        parts = actor.split(GAN_SEPARATOR, 2)
+        return false unless parts.length == 2
+
+        game_part, piece_part = parts
+
+        return false unless valid_game_identifier?(game_part)
+        return false unless valid_piece_identifier?(piece_part)
+
+        # Case consistency verification between game and piece
+        game_is_upper = game_part == game_part.upcase
+        piece_match = piece_part.match(/\A[-+]?([A-Za-z])'?\z/)
+        return false unless piece_match
+
+        piece_char = piece_match[1]
+        piece_is_upper = piece_char == piece_char.upcase
+
+        game_is_upper == piece_is_upper
+      end
+
+      # Validates a game identifier.
+      #
+      # Game identifiers must be non-empty strings containing only
+      # alphabetic characters, either all uppercase or all lowercase.
+      # Mixed case is not allowed as it breaks the player distinction.
+      #
+      # @param game_id [String] Game identifier to validate
+      #
+      # @return [Boolean] true if the identifier is valid
+      #
+      # @example Valid game identifiers
+      #   valid_game_identifier?("CHESS")   # => true
+      #   valid_game_identifier?("shogi")   # => true
+      #   valid_game_identifier?("XIANGQI") # => true
+      #
+      # @example Invalid game identifiers
+      #   valid_game_identifier?("Chess")   # => false (mixed case)
+      #   valid_game_identifier?("")        # => false (empty)
+      #   valid_game_identifier?("CHESS1")  # => false (contains digit)
+      def valid_game_identifier?(game_id)
+        return false unless game_id.is_a?(String)
+        return false if game_id.empty?
+
+        # Must be either entirely uppercase or entirely lowercase
+        game_id.match?(/\A[A-Z]+\z/) || game_id.match?(/\A[a-z]+\z/)
+      end
+
+      # Validates a piece identifier (part after the colon).
+      #
+      # Piece identifiers follow the pattern: [optional prefix][letter][optional suffix]
+      # Where:
+      # - Optional prefix: + or -
+      # - Letter: A-Z or a-z (must match game part case)
+      # - Optional suffix: ' (apostrophe)
+      #
+      # @param piece_id [String] Piece identifier to validate
+      #
+      # @return [Boolean] true if the identifier is valid
+      #
+      # @example Valid piece identifiers
+      #   valid_piece_identifier?("K")      # => true
+      #   valid_piece_identifier?("+p")     # => true
+      #   valid_piece_identifier?("R'")     # => true
+      #   valid_piece_identifier?("-Q'")    # => true
+      #
+      # @example Invalid piece identifiers
+      #   valid_piece_identifier?("")       # => false (empty)
+      #   valid_piece_identifier?("++K")    # => false (double prefix)
+      #   valid_piece_identifier?("K''")    # => false (double suffix)
+      def valid_piece_identifier?(piece_id)
+        return false unless piece_id.is_a?(String)
+        return false if piece_id.empty?
+
+        # Format: [optional prefix][letter][optional suffix]
+        piece_id.match?(/\A[-+]?[A-Za-z]'?\z/)
+      end
+    end
+  end
+end

data/lib/sashite/ggn/ruleset/source/destination/engine/transition.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    class Ruleset
+      class Source
+        class Destination
+          class Engine
+            # Represents the result of a valid pseudo-legal move evaluation.
+            #
+            # A Transition encapsulates the changes that occur when a move is executed
+            # on the game board. Since GGN focuses exclusively on board-to-board
+            # transformations, a Transition only contains board state changes: pieces
+            # moving, appearing, or disappearing on the board.
+            #
+            # @example Basic move (pawn advance)
+            #   transition = Transition.new("e2" => nil, "e4" => "CHESS:P")
+            #   transition.diff  # => { "e2" => nil, "e4" => "CHESS:P" }
+            #
+            # @example Capture (piece takes enemy piece)
+            #   transition = Transition.new("d4" => nil, "e5" => "CHESS:P")
+            #   transition.diff  # => { "d4" => nil, "e5" => "CHESS:P" }
+            #
+            # @example Complex move (castling with king and rook)
+            #   transition = Transition.new(
+            #     "e1" => nil, "f1" => "CHESS:R", "g1" => "CHESS:K", "h1" => nil
+            #   )
+            #   transition.diff  # => { "e1" => nil, "f1" => "CHESS:R", "g1" => "CHESS:K", "h1" => nil }
+            #
+            # @example Promotion (pawn becomes queen)
+            #   transition = Transition.new("e7" => nil, "e8" => "CHESS:Q")
+            #   transition.diff  # => { "e7" => nil, "e8" => "CHESS:Q" }
+            class Transition
+              # @return [Hash<String, String|nil>] Board state changes after the move.
+              #   Keys are square labels, values are piece identifiers or nil for empty squares.
+              attr_reader :diff
+
+              # Creates a new Transition with the specified board changes.
+              #
+              # @param diff [Hash] Board state changes as keyword arguments.
+              #   Keys should be square labels, values should be piece identifiers or nil.
+              #
+              # @example Creating a simple move transition
+              #   Transition.new("e2" => nil, "e4" => "CHESS:P")
+              #
+              # @example Creating a capture transition
+              #   Transition.new("d4" => nil, "e5" => "CHESS:P")
+              #
+              # @example Creating a complex multi-square transition (castling)
+              #   Transition.new(
+              #     "e1" => nil,        # King leaves e1
+              #     "f1" => "CHESS:R",  # Rook moves to f1
+              #     "g1" => "CHESS:K",  # King moves to g1
+              #     "h1" => nil         # Rook leaves h1
+              #   )
+              #
+              # @example Creating a promotion transition
+              #   Transition.new("e7" => nil, "e8" => "CHESS:Q")
+              #
+              # @example Creating an en passant capture
+              #   Transition.new(
+              #     "d5" => nil,        # Attacking pawn leaves d5
+              #     "e5" => nil,        # Captured pawn removed from e5
+              #     "e6" => "CHESS:P"   # Attacking pawn lands on e6
+              #   )
+              def initialize(**diff)
+                @diff = diff
+
+                freeze
+              end
+
+              # This class remains intentionally simple and rule-agnostic.
+              # Any interpretation of what constitutes a "capture" or "promotion"
+              # is left to higher-level game logic, maintaining GGN's neutrality.
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sashite/ggn/ruleset/source/destination/engine.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require_relative File.join("..", "..", "..", "move_validator")
+require_relative File.join("engine", "transition")
+
+module Sashite
+  module Ggn
+    class Ruleset
+      class Source
+        class Destination
+          # Evaluates pseudo-legal move conditions for a specific source-destination pair.
+          #
+          # The Engine is the core logic component that determines whether a move
+          # is valid under the basic movement constraints defined in GGN. It evaluates
+          # require/prevent conditions and returns the resulting board transformation.
+          #
+          # Since GGN focuses exclusively on board-to-board transformations, the Engine
+          # only handles pieces moving, capturing, or transforming on the game board.
+          #
+          # The class uses a functional approach with filter_map for optimal performance
+          # and clean, readable code that avoids mutation of external variables.
+          #
+          # @example Evaluating a simple move
+          #   engine = destinations.to('e4')
+          #   transitions = engine.where(board_state, 'CHESS')
+          #   puts "Move valid!" if transitions.any?
+          #
+          # @example Handling promotion choices
+          #   engine = destinations.to('e8')  # pawn promotion
+          #   transitions = engine.where(board_state, 'CHESS')
+          #   transitions.each_with_index do |t, i|
+          #     puts "Choice #{i + 1}: promotes to #{t.diff['e8']}"
+          #   end
+          class Engine
+            include MoveValidator
+
+            # Creates a new Engine with conditional transition rules.
+            #
+            # @param transitions [Array] Transition rules as individual arguments,
+            #   each containing require/prevent conditions and perform actions.
+            # @param actor [String] GAN identifier of the piece being moved
+            # @param origin [String] Source square
+            # @param target [String] Destination square
+            #
+            # @raise [ArgumentError] If parameters are invalid
+            #
+            # @example Creating an engine for a pawn move
+            #   transition_rules = [
+            #     {
+            #       "require" => { "e4" => "empty", "e3" => "empty" },
+            #       "perform" => { "e2" => nil, "e4" => "CHESS:P" }
+            #     }
+            #   ]
+            #   engine = Engine.new(*transition_rules, actor: "CHESS:P", origin: "e2", target: "e4")
+            def initialize(*transitions, actor:, origin:, target:)
+              raise ::ArgumentError, "actor must be a String" unless actor.is_a?(::String)
+              raise ::ArgumentError, "origin must be a String" unless origin.is_a?(::String)
+              raise ::ArgumentError, "target must be a String" unless target.is_a?(::String)
+
+              @transitions = transitions
+              @actor = actor
+              @origin = origin
+              @target = target
+
+              freeze
+            end
+
+            # Evaluates move validity and returns all resulting transitions.
+            #
+            # Uses a functional approach with filter_map to process transitions efficiently.
+            # This method checks each conditional transition and returns all that match the
+            # current board state, supporting multiple promotion choices and optional
+            # transformations as defined in the GGN specification.
+            #
+            # @param board_state [Hash] Current board state mapping square labels
+            #   to piece identifiers (nil for empty squares)
+            # @param active_game [String] Current player's game identifier (e.g., 'CHESS', 'shogi').
+            #   This corresponds to the first element of the GAMES-TURN field in FEEN notation.
+            #
+            # @return [Array<Transition>] Array of Transition objects for all valid variants,
+            #   empty array if no valid transitions exist
+            #
+            # @raise [ArgumentError] If any parameter is invalid or malformed
+            #
+            # @example Single valid move
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => nil, 'e4' => nil }
+            #   transitions = engine.where(board_state, 'CHESS')
+            #   transitions.size  # => 1
+            #   transitions.first.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
+            #
+            # @example Multiple promotion choices
+            #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
+            #   transitions = engine.where(board_state, 'CHESS')
+            #   transitions.size  # => 4 (Queen, Rook, Bishop, Knight)
+            #   transitions.map { |t| t.diff['e8'] }  # => ['CHESS:Q', 'CHESS:R', 'CHESS:B', 'CHESS:N']
+            #
+            # @example Invalid move (wrong piece)
+            #   board_state = { 'e2' => 'CHESS:Q', 'e3' => nil, 'e4' => nil }
+            #   transitions = engine.where(board_state, 'CHESS')  # => []
+            #
+            # @example Invalid move (blocked path)
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => 'CHESS:N', 'e4' => nil }
+            #   transitions = engine.where(board_state, 'CHESS')  # => []
+            def where(board_state, active_game)
+              # Validate all input parameters before processing
+              validate_parameters!(board_state, active_game)
+
+              # Early return if basic move context is invalid (wrong piece, wrong player, etc.)
+              return [] unless valid_move_context?(board_state, active_game)
+
+              # Use filter_map for functional approach: filter valid transitions and map to Transition objects
+              # This avoids mutation and is more performant than select + map for large datasets
+              @transitions.filter_map do |transition|
+                # Only create Transition objects for transitions that match current board state
+                create_transition(transition) if transition_matches?(transition, board_state, active_game)
+              end
+            end
+
+            private
+
+            # Validates the move context before checking pseudo-legality.
+            # Uses the shared MoveValidator module for consistency across the codebase.
+            #
+            # This method performs essential pre-checks:
+            # - Ensures the piece is at the expected origin square
+            # - Ensures the piece belongs to the current player
+            #
+            # @param board_state [Hash] Current board state
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if the move context is valid
+            def valid_move_context?(board_state, active_game)
+              # For all moves, piece must be on the board at origin square
+              return false unless piece_on_board_at_origin?(@actor, @origin, board_state)
+
+              # Verify piece ownership - only current player can move their pieces
+              piece_belongs_to_current_player?(@actor, active_game)
+            end
+
+            # Creates a new Transition object from a transition rule.
+            # Extracted to improve readability and maintainability of the main logic.
+            #
+            # Note: GGN no longer supports gain/drop fields, so Transition creation
+            # is simplified to only handle board transformations.
+            #
+            # @param transition [Hash] The transition rule containing perform data
+            #
+            # @return [Transition] A new immutable Transition object
+            def create_transition(transition)
+              Transition.new(**transition["perform"])
+            end
+
+            # Validates all parameters in one consolidated method.
+            # Provides comprehensive validation with clear error messages for debugging.
+            #
+            # @param board_state [Object] Should be a Hash
+            # @param active_game [Object] Should be a String
+            #
+            # @raise [ArgumentError] If any parameter is invalid
+            def validate_parameters!(board_state, active_game)
+              # Type validation with clear error messages
+              unless board_state.is_a?(::Hash)
+                raise ::ArgumentError, "board_state must be a Hash, got #{board_state.class}"
+              end
+
+              unless active_game.is_a?(::String)
+                raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
+              end
+
+              # Content validation - ensures data integrity
+              validate_board_state!(board_state)
+              validate_active_game!(active_game)
+            end
+
+            # Validates board_state structure and content.
+            # Ensures all square labels and piece identifiers are properly formatted.
+            #
+            # @param board_state [Hash] Board state to validate
+            #
+            # @raise [ArgumentError] If board_state contains invalid data
+            def validate_board_state!(board_state)
+              board_state.each do |square, piece|
+                validate_square_label!(square)
+                validate_board_piece!(piece, square)
+              end
+            end
+
+            # Validates a square label according to GGN requirements.
+            # Square labels must be non-empty strings.
+            #
+            # @param square [Object] Square label to validate
+            #
+            # @raise [ArgumentError] If square label is invalid
+            def validate_square_label!(square)
+              unless square.is_a?(::String) && !square.empty?
+                raise ::ArgumentError, "Invalid square label: #{square.inspect}. Must be a non-empty String."
+              end
+            end
+
+            # Validates a piece on the board.
+            # Pieces can be nil (empty square) or valid GAN identifiers.
+            #
+            # @param piece [Object] Piece to validate
+            # @param square [String] Square where piece is located (for error context)
+            #
+            # @raise [ArgumentError] If piece is invalid
+            def validate_board_piece!(piece, square)
+              return if piece.nil? # Empty squares are valid
+
+              unless piece.is_a?(::String)
+                raise ::ArgumentError, "Invalid piece at square #{square}: #{piece.inspect}. Must be a String or nil."
+              end
+
+              unless valid_gan_identifier?(piece)
+                raise ::ArgumentError, "Invalid GAN identifier at square #{square}: #{piece.inspect}. Must follow GAN format (e.g., 'CHESS:P', 'shogi:+k')."
+              end
+            end
+
+            # Validates active_game format according to GAN specification.
+            # Active game must be a non-empty alphabetic game identifier.
+            #
+            # @param active_game [String] Active game identifier to validate
+            #
+            # @raise [ArgumentError] If active game format is invalid
+            def validate_active_game!(active_game)
+              if active_game.empty?
+                raise ::ArgumentError, "active_game cannot be empty"
+              end
+
+              unless valid_game_identifier?(active_game)
+                raise ::ArgumentError, "Invalid active_game format: #{active_game.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
+              end
+            end
+
+            # Validates if a string is a valid GAN identifier with casing consistency.
+            # Ensures game part and piece part have consistent casing (both upper or both lower).
+            #
+            # @param identifier [String] GAN identifier to validate
+            #
+            # @return [Boolean] true if valid GAN format
+            def valid_gan_identifier?(identifier)
+              return false unless identifier.include?(':')
+
+              game_part, piece_part = identifier.split(':', 2)
+
+              return false unless valid_game_identifier?(game_part)
+              return false if piece_part.empty?
+              return false unless /\A[-+]?[A-Za-z]'?\z/.match?(piece_part)
+
+              # Extract base letter and check casing consistency
+              base_letter = piece_part.gsub(/\A[-+]?([A-Za-z])'?\z/, '\1')
+
+              # Ensure consistent casing between game and piece parts
+              if game_part == game_part.upcase
+                base_letter == base_letter.upcase
+              else
+                base_letter == base_letter.downcase
+              end
+            end
+
+            # Checks if a transition matches the current board state.
+            # Evaluates both require conditions (must be true) and prevent conditions (must be false).
+            #
+            # @param transition [Hash] The transition rule to evaluate
+            # @param board_state [Hash] Current board state
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if the transition is valid for current state
+            def transition_matches?(transition, board_state, active_game)
+              # Ensure transition is properly formatted
+              return false unless transition.is_a?(::Hash) && transition.key?("perform")
+
+              # Check require conditions (all must be satisfied - logical AND)
+              return false if has_require_conditions?(transition) && !check_require_conditions(transition["require"], board_state, active_game)
+
+              # Check prevent conditions (none must be satisfied - logical NOR)
+              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, active_game)
+
+              true
+            end
+
+            # Checks if transition has require conditions that need validation.
+            #
+            # @param transition [Hash] The transition rule
+            #
+            # @return [Boolean] true if require conditions exist
+            def has_require_conditions?(transition)
+              transition["require"]&.is_a?(::Hash) && !transition["require"].empty?
+            end
+
+            # Checks if transition has prevent conditions that need validation.
+            #
+            # @param transition [Hash] The transition rule
+            #
+            # @return [Boolean] true if prevent conditions exist
+            def has_prevent_conditions?(transition)
+              transition["prevent"]&.is_a?(::Hash) && !transition["prevent"].empty?
+            end
+
+            # Verifies all require conditions are satisfied (logical AND).
+            # All specified conditions must be true for the move to be valid.
+            #
+            # @param require_conditions [Hash] Square -> required state mappings
+            # @param board_state [Hash] Current board state
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if all conditions are satisfied
+            def check_require_conditions(require_conditions, board_state, active_game)
+              require_conditions.all? do |square, required_state|
+                actual_piece = board_state[square]
+                matches_state?(actual_piece, required_state, active_game)
+              end
+            end
+
+            # Verifies none of the prevent conditions are satisfied (logical NOR).
+            # If any prevent condition is true, the move is invalid.
+            #
+            # @param prevent_conditions [Hash] Square -> forbidden state mappings
+            # @param board_state [Hash] Current board state
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if no forbidden conditions are satisfied
+            def check_prevent_conditions(prevent_conditions, board_state, active_game)
+              prevent_conditions.none? do |square, forbidden_state|
+                actual_piece = board_state[square]
+                matches_state?(actual_piece, forbidden_state, active_game)
+              end
+            end
+
+            # Determines if a piece matches a required/forbidden state.
+            # Handles special states ("empty", "enemy") and exact piece matching.
+            #
+            # @param actual_piece [String, nil] The piece currently on the square
+            # @param expected_state [String] The expected/forbidden state
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if the piece matches the expected state
+            def matches_state?(actual_piece, expected_state, active_game)
+              case expected_state
+              when "empty"
+                actual_piece.nil?
+              when "enemy"
+                actual_piece && enemy_piece?(actual_piece, active_game)
+              else
+                # Exact piece match
+                actual_piece == expected_state
+              end
+            end
+
+            # Determines if a piece belongs to the opposing player.
+            # Uses GAN casing conventions to determine ownership based on case correspondence.
+            #
+            # @param piece [String] The piece identifier to check (must be GAN format)
+            # @param active_game [String] Current player identifier
+            #
+            # @return [Boolean] true if piece belongs to opponent
+            def enemy_piece?(piece, active_game)
+              return false if piece.nil? || piece.empty?
+              return false unless piece.include?(':')
+
+              # Use GAN format for ownership determination
+              game_part = piece.split(':', 2).fetch(0)
+              piece_is_uppercase_player = game_part == game_part.upcase
+              current_is_uppercase_player = active_game == active_game.upcase
+
+              # Enemy if players have different casing
+              piece_is_uppercase_player != current_is_uppercase_player
+            end
+          end
+        end
+      end
+    end
+  end
+end