sashite-ggn 0.6.0 → 0.8.0

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

@@ -1,97 +1,64 @@
 # frozen_string_literal: true
 
-require_relative File.join("..", "move_validator")
-require_relative File.join("source", "destination")
+require_relative "source/destination"
 
 module Sashite
   module Ggn
     class Ruleset
-      # Represents the possible source positions for a specific piece type.
+      # Represents movement possibilities for a piece type
       #
-      # A Source instance contains all the starting positions from which
-      # a piece can move on the board. Since GGN focuses exclusively on
-      # board-to-board transformations, all source positions are regular
-      # board squares.
-      #
-      # @example Basic usage with chess king
-      #   piece_data = Sashite::Ggn.load_file('chess.json')
-      #   source = piece_data.select('CHESS:K')
-      #   destinations = source.from('e1')
-      #
-      # @example Complete move evaluation workflow
-      #   piece_data = Sashite::Ggn.load_file('chess.json')
-      #   king_source = piece_data.select('CHESS:K')
-      #   destinations = king_source.from('e1')
-      #   engine = destinations.to('e2')
-      #
-      #   board_state = { 'e1' => 'CHESS:K', 'e2' => nil }
-      #   transitions = engine.where(board_state, 'CHESS')
-      #
-      #   if transitions.any?
-      #     puts "King can move from e1 to e2"
-      #   end
+      # @see https://sashite.dev/specs/ggn/1.0.0/
       class Source
-        include MoveValidator
+        # @return [String] The QPI piece identifier
+        attr_reader :piece
 
-        # Creates a new Source instance from movement data.
-        #
-        # @param data [Hash] The movement data where keys are source positions
-        #   (square labels) and values contain destination data.
-        # @param actor [String] The GAN identifier for this piece type
-        #
-        # @raise [ArgumentError] If data is not a Hash
-        #
-        # @example Creating a Source instance
-        #   source_data = {
-        #     "e1" => { "e2" => [...], "f1" => [...] },
-        #     "d4" => { "d5" => [...], "e5" => [...] }
-        #   }
-        #   source = Source.new(source_data, actor: "CHESS:K")
-        def initialize(data, actor:)
-          raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
+        # @return [Hash] The sources data
+        attr_reader :data
 
+        # Create a new Source
+        #
+        # @param piece [String] QPI piece identifier
+        # @param data [Hash] Sources data structure
+        def initialize(piece, data)
+          @piece = piece
           @data = data
-          @actor = actor
 
           freeze
         end
 
-        # Retrieves possible destinations from a specific source position.
+        # Specify the source location for the piece
         #
-        # @param origin [String] The source position label. Must be a regular
-        #   square label (e.g., 'e1', '5i', 'a1').
+        # @param source [String] Source location (CELL coordinate or HAND "*")
+        # @return [Destination] Destination selector object
+        # @raise [KeyError] If source not found for this piece
         #
-        # @return [Destination] A Destination instance containing all possible
-        #   target squares and their movement conditions from this origin.
+        # @example
+        #   destination = source.from("e1")
+        def from(source)
+          raise ::KeyError, "Source not found: #{source}" unless source?(source)
+
+          Destination.new(piece, source, data.fetch(source))
+        end
+
+        # Return all valid source locations for this piece
         #
-        # @raise [KeyError] If the origin position is not found in the data
+        # @return [Array<String>] Source locations
         #
-        # @example Getting moves from a specific square
-        #   destinations = source.from('e1')
-        #   engine = destinations.to('e2')
+        # @example
+        #   source.sources # => ["e1", "d1", "*"]
+        def sources
+          data.keys
+        end
+
+        # Check if location is a valid source for this piece
         #
-        # @example Handling missing origins
-        #   begin
-        #     destinations = source.from('invalid_square')
-        #   rescue KeyError => e
-        #     puts "No moves from this position: #{e.message}"
-        #   end
+        # @param location [String] Source location
+        # @return [Boolean]
         #
-        # @example Iterating through all possible origins
-        #   # Assuming you have access to the source data keys
-        #   available_origins = ['e1', 'd1', 'f1']  # example origins
-        #   available_origins.each do |pos|
-        #     begin
-        #       destinations = source.from(pos)
-        #       puts "Piece can move from #{pos}"
-        #       # Process destinations...
-        #     rescue KeyError
-        #       puts "No moves available from #{pos}"
-        #     end
-        #   end
-        def from(origin)
-          data = @data.fetch(origin)
-          Destination.new(data, actor: @actor, origin: origin)
+        # @example
+        #   source.source?("e1") # => true
+        def source?(location)
+          data.key?(location)
         end
       end
     end

data/lib/sashite/ggn/ruleset.rb

@@ -1,310 +1,248 @@
 # frozen_string_literal: true
 
-require_relative "move_validator"
-require_relative File.join("ruleset", "source")
+require "sashite/cell"
+require "sashite/hand"
+require "sashite/lcn"
+require "sashite/qpi"
+require "sashite/stn"
+
+require_relative "ruleset/source"
 
 module Sashite
   module Ggn
-    # Represents a collection of piece definitions from a GGN document.
-    #
-    # A Ruleset instance contains all the pseudo-legal move definitions for
-    # various game pieces, organized by their GAN (General Actor Notation)
-    # identifiers. This class provides the entry point for querying specific
-    # piece movement rules and generating all possible transitions for a given
-    # game state.
-    #
-    # The class uses functional programming principles throughout, leveraging
-    # Ruby's Enumerable methods (flat_map, filter_map, select) to create
-    # efficient, readable, and maintainable code that avoids mutation and
-    # side effects.
-    #
-    # GGN focuses exclusively on board-to-board transformations. All moves
-    # represent pieces moving, capturing, or transforming on the game board.
-    #
-    # @example Basic usage
-    #   piece_data = Sashite::Ggn.load_file('chess.json')
-    #   chess_king = piece_data.select('CHESS:K')
-    #   shogi_pawn = piece_data.select('SHOGI:P')
-    #
-    # @example Complete workflow
-    #   piece_data = Sashite::Ggn.load_file('game_moves.json')
-    #
-    #   # Query specific piece moves
-    #   begin
-    #     king_source = piece_data.select('CHESS:K')
-    #     puts "Found chess king movement rules"
-    #   rescue KeyError
-    #     puts "Chess king not found in this dataset"
-    #   end
-    #
-    # @example Finding all possible moves in a position
-    #   board_state = { 'e1' => 'CHESS:K', 'e2' => 'CHESS:P', 'd1' => 'CHESS:Q' }
-    #   all_moves = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
-    #   puts "Found #{all_moves.size} possible moves"
+    # Immutable container for GGN movement rules
     #
-    # @see https://sashite.dev/documents/gan/ GAN Specification
-    # @see https://sashite.dev/documents/ggn/ GGN Specification
+    # @see https://sashite.dev/specs/ggn/1.0.0/
     class Ruleset
-      include MoveValidator
+      # @return [Hash] The underlying GGN data structure
+      attr_reader :data
 
-      # Creates a new Ruleset instance from GGN data.
+      # Create a new Ruleset from GGN data structure
       #
-      # @param data [Hash] The parsed GGN JSON data structure, where keys are
-      #   GAN identifiers and values contain the movement definitions.
-      #
-      # @raise [ArgumentError] If data is not a Hash
-      #
-      # @example Creating from parsed JSON data
-      #   ggn_data = JSON.parse(File.read('chess.json'))
-      #   ruleset = Ruleset.new(ggn_data)
+      # @param data [Hash] GGN data structure
+      # @raise [ArgumentError] If data structure is invalid
+      # @example With invalid structure
+      #   begin
+      #     Sashite::Ggn::Ruleset.new({ "invalid" => "data" })
+      #   rescue ArgumentError => e
+      #     puts e.message # => "Invalid QPI format: invalid"
+      #   end
       def initialize(data)
-        raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
-
+        validate_structure!(data)
         @data = data
 
         freeze
       end
 
-      # Retrieves movement rules for a specific piece type.
-      #
-      # @param actor [String] The GAN identifier for the piece type
-      #   (e.g., 'CHESS:K', 'SHOGI:P', 'chess:q'). Must match exactly
-      #   including case sensitivity.
-      #
-      # @return [Source] A Source instance containing all movement rules
-      #   for this piece type from different board positions.
-      #
-      # @raise [KeyError] If the actor is not found in the GGN data
+      # Select movement rules for a specific piece type
       #
-      # @example Fetching chess king moves
-      #   source = piece_data.select('CHESS:K')
-      #   destinations = source.from('e1')
-      #   engine = destinations.to('e2')
+      # @param piece [String] QPI piece identifier
+      # @return [Source] Source selector object
+      # @raise [KeyError] If piece not found in ruleset
       #
-      # @example Handling missing pieces
-      #   begin
-      #     moves = piece_data.select('NONEXISTENT:X')
-      #   rescue KeyError => e
-      #     puts "Piece not found: #{e.message}"
-      #   end
-      #
-      # @note The actor format must follow GAN specification:
-      #   GAME:piece (e.g., CHESS:K, shogi:p, XIANGQI:E)
-      def select(actor)
-        data = @data.fetch(actor)
-        Source.new(data, actor:)
+      # @example
+      #   source = ruleset.select("C:K")
+      def select(piece)
+        raise ::KeyError, "Piece not found: #{piece}" unless piece?(piece)
+
+        Source.new(piece, data.fetch(piece))
       end
 
-      # Returns all pseudo-legal move transitions for the given position.
+      # Generate all pseudo-legal moves for the given position
       #
-      # This method traverses all actors defined in the GGN data using a functional
-      # approach with flat_map and filter_map to efficiently process and filter
-      # valid moves. Each result contains the complete transition information
-      # including all variants for moves with multiple outcomes (e.g., promotion choices).
+      # @note This method evaluates all possible moves in the ruleset.
+      #   For large rulesets, consider filtering by active pieces first.
       #
-      # The implementation uses a three-level functional decomposition:
-      # 1. Process each actor (piece type) that belongs to current player
-      # 2. Process each valid origin position for that actor
-      # 3. Process each destination and evaluate transition rules
+      # @param feen [String] Position in FEEN format
+      # @return [Array<Array(String, String, String, Array<Sashite::Stn::Transition>)>]
+      #   Array of tuples containing:
+      #   - piece (String): QPI identifier
+      #   - source (String): CELL coordinate or HAND "*"
+      #   - destination (String): CELL coordinate or HAND "*"
+      #   - transitions (Array<Sashite::Stn::Transition>): Valid state transitions
       #
-      # @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<Array>] List of move transitions, where each element is:
-      #   [actor, origin, target, transitions]
-      #   - actor [String]: GAN identifier of the moving piece
-      #   - origin [String]: Source square
-      #   - target [String]: Destination square
-      #   - transitions [Array<Transition>]: All valid transition variants
+      # @example
+      #   moves = ruleset.pseudo_legal_transitions(feen)
+      def pseudo_legal_transitions(feen)
+        pieces.flat_map do |piece|
+          source = select(piece)
+
+          source.sources.flat_map do |src|
+            destination = source.from(src)
+
+            destination.destinations.flat_map do |dest|
+              engine = destination.to(dest)
+              transitions = engine.where(feen)
+
+              transitions.empty? ? [] : [[piece, src, dest, transitions]]
+            end
+          end
+        end
+      end
+
+      # Check if ruleset contains movement rules for specified piece
       #
-      # @raise [ArgumentError] If any parameter is invalid or malformed
+      # @param piece [String] QPI piece identifier
+      # @return [Boolean]
       #
-      # @example Getting all possible transitions including promotion variants
-      #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
-      #   transitions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
-      #   # => [
-      #   #   ["CHESS:P", "e7", "e8", [
-      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:Q"}>,
-      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:R"}>,
-      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:B"}>,
-      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:N"}>
-      #   #   ]]
-      #   # ]
+      # @example
+      #   ruleset.piece?("C:K") # => true
+      def piece?(piece)
+        data.key?(piece)
+      end
+
+      # Return all piece identifiers in ruleset
       #
-      # @example Processing grouped transitions
-      #   transitions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
-      #   transitions.each do |actor, origin, target, variants|
-      #     puts "#{actor} from #{origin} to #{target}:"
-      #     variants.each_with_index do |transition, i|
-      #       puts "  Variant #{i + 1}: #{transition.diff}"
-      #     end
-      #   end
+      # @return [Array<String>] QPI piece identifiers
       #
-      # @example Filtering for specific move types
-      #   # Find all promotion moves
-      #   promotions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
-      #     .select { |actor, origin, target, variants| variants.size > 1 }
+      # @example
+      #   ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
+      def pieces
+        data.keys
+      end
+
+      # Convert ruleset to hash representation
       #
-      #   # Find all multi-square moves (like castling)
-      #   complex_moves = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
-      #     .select { |actor, origin, target, variants|
-      #       variants.any? { |t| t.diff.keys.size > 2 }
-      #     }
+      # @return [Hash] GGN data structure
       #
-      # @example Performance considerations
-      #   # For large datasets, consider filtering by piece type first
-      #   specific_piece_moves = piece_data.select('CHESS:Q')
-      #     .from('d1').to('d8').where(board_state, 'CHESS')
-      def pseudo_legal_transitions(board_state, active_game)
-        validate_pseudo_legal_parameters!(board_state, active_game)
-
-        # Use flat_map to process all actors and flatten the results in one pass
-        # This functional approach avoids mutation and intermediate arrays
-        @data.flat_map do |actor, source_data|
-          # Early filter: only process pieces belonging to current player
-          # This optimization significantly reduces processing time
-          next [] unless piece_belongs_to_current_player?(actor, active_game)
-
-          # Process all source positions for this actor using functional decomposition
-          process_actor_transitions(actor, source_data, board_state, active_game)
-        end
+      # @example
+      #   ruleset.to_h # => { "C:K" => { "e1" => { "e2" => [...] } } }
+      def to_h
+        data
       end
 
       private
 
-      # Processes all possible transitions for a single actor (piece type).
-      #
-      # This method represents the second level of functional decomposition,
-      # handling all source positions (origins) for a given piece type.
-      # It uses flat_map to efficiently process each origin and flatten the results.
-      #
-      # @param actor [String] GAN identifier of the piece type
-      # @param source_data [Hash] Movement data for this piece type, mapping
-      #   origin squares to destination data
-      # @param board_state [Hash] Current board state
-      # @param active_game [String] Current player identifier
-      #
-      # @return [Array] Array of valid transition tuples for this actor
+      # Validate GGN data structure
       #
-      # @example Source data structure
-      #   {
-      #     "e1" => { "e2" => [...], "f1" => [...] }  # Regular moves
-      #   }
-      def process_actor_transitions(actor, source_data, board_state, active_game)
-        source_data.flat_map do |origin, destination_data|
-          # Early filter: check piece presence at origin square
-          # Piece must be present at origin square for the move to be valid
-          next [] unless piece_on_board_at_origin?(actor, origin, board_state)
+      # @param data [Hash] Data to validate
+      # @raise [ArgumentError] If structure is invalid
+      # @return [void]
+      def validate_structure!(data)
+        raise ::ArgumentError, "GGN data must be a Hash" unless data.is_a?(::Hash)
 
-          # Process all destination squares for this origin
-          process_origin_transitions(actor, origin, destination_data, board_state, active_game)
+        data.each do |piece, sources|
+          validate_piece!(piece)
+          validate_sources!(sources, piece)
         end
       end
 
-      # Processes all possible transitions from a single origin square.
+      # Validate QPI piece identifier using sashite-qpi
       #
-      # This method represents the third level of functional decomposition,
-      # handling all destination squares from a given origin. It creates
-      # engines to evaluate each move and uses filter_map to efficiently
-      # combine filtering and transformation operations.
-      #
-      # @param actor [String] GAN identifier of the piece
-      # @param origin [String] Source square
-      # @param destination_data [Hash] Available destinations and their transition rules
-      # @param board_state [Hash] Current board state
-      # @param active_game [String] Current player identifier
-      #
-      # @return [Array] Array of valid transition tuples for this origin
-      #
-      # @example Destination data structure
-      #   {
-      #     "e4" => [
-      #       { "require" => { "e4" => "empty" }, "perform" => { "e2" => nil, "e4" => "CHESS:P" } }
-      #     ],
-      #     "f3" => [
-      #       { "require" => { "f3" => "enemy" }, "perform" => { "e2" => nil, "f3" => "CHESS:P" } }
-      #     ]
-      #   }
-      def process_origin_transitions(actor, origin, destination_data, board_state, active_game)
-        destination_data.filter_map do |target, transition_rules|
-          # Create engine to evaluate this specific source-destination pair
-          # Each engine encapsulates the conditional logic for one move
-          engine = Source::Destination::Engine.new(*transition_rules, actor: actor, origin: origin, target: target)
+      # @param piece [String] Piece identifier to validate
+      # @raise [ArgumentError] If piece identifier is invalid
+      # @return [void]
+      def validate_piece!(piece)
+        raise ::ArgumentError, "Invalid piece identifier: #{piece}" unless piece.is_a?(::String)
+        raise ::ArgumentError, "Invalid QPI format: #{piece}" unless Qpi.valid?(piece)
+      end
 
-          # Get all valid transitions for this move (supports multiple variants)
-          # The engine handles require/prevent conditions and returns Transition objects
-          transitions = engine.where(board_state, active_game)
+      # Validate sources hash structure
+      #
+      # @param sources [Hash] Sources hash to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @raise [ArgumentError] If sources structure is invalid
+      # @return [void]
+      def validate_sources!(sources, piece)
+        raise ::ArgumentError, "Sources for #{piece} must be a Hash" unless sources.is_a?(Hash)
 
-          # Only return successful moves (with at least one valid transition)
-          # filter_map automatically filters out nil values
-          [actor, origin, target, transitions] unless transitions.empty?
+        sources.each do |source, destinations|
+          validate_location!(source, piece)
+          validate_destinations!(destinations, piece, source)
         end
       end
 
-      # Validates parameters for pseudo_legal_transitions method.
-      #
-      # Provides comprehensive validation with clear error messages for debugging.
-      # This method ensures data integrity and helps catch common usage errors
-      # early in the processing pipeline.
-      #
-      # @param board_state [Object] Should be a Hash mapping squares to pieces
-      # @param active_game [Object] Should be a String representing current player's game
-      #
-      # @raise [ArgumentError] If any parameter is invalid
+      # Validate destinations hash structure
       #
-      # @example Valid parameters
-      #   validate_pseudo_legal_parameters!(
-      #     { "e1" => "CHESS:K", "e2" => nil },
-      #     "CHESS"
-      #   )
-      #
-      # @example Invalid parameters (raises ArgumentError)
-      #   validate_pseudo_legal_parameters!("invalid", "CHESS")
-      #   validate_pseudo_legal_parameters!({}, 123)
-      #   validate_pseudo_legal_parameters!({}, "")
-      def validate_pseudo_legal_parameters!(board_state, active_game)
-        # Type validation with clear, specific error messages
-        unless board_state.is_a?(::Hash)
-          raise ::ArgumentError, "board_state must be a Hash, got #{board_state.class}"
-        end
+      # @param destinations [Hash] Destinations hash to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @param source [String] Source location (for error messages)
+      # @raise [ArgumentError] If destinations structure is invalid
+      # @return [void]
+      def validate_destinations!(destinations, piece, source)
+        raise ::ArgumentError, "Destinations for #{piece} from #{source} must be a Hash" unless destinations.is_a?(::Hash)
 
-        unless active_game.is_a?(::String)
-          raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
+        destinations.each do |destination, possibilities|
+          validate_location!(destination, piece)
+          validate_possibilities!(possibilities, piece, source, destination)
         end
+      end
 
-        # Content validation - ensures meaningful data
-        if active_game.empty?
-          raise ::ArgumentError, "active_game cannot be empty"
-        end
+      # Validate possibilities array structure
+      #
+      # @param possibilities [Array] Possibilities array to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @param source [String] Source location (for error messages)
+      # @param destination [String] Destination location (for error messages)
+      # @raise [ArgumentError] If possibilities structure is invalid
+      # @return [void]
+      def validate_possibilities!(possibilities, piece, source, destination)
+        raise ::ArgumentError, "Possibilities for #{piece} #{source}→#{destination} must be an Array" unless possibilities.is_a?(::Array)
 
-        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')."
+        possibilities.each do |possibility|
+          validate_possibility!(possibility, piece, source, destination)
         end
+      end
 
-        # Validate board_state structure (optional deep validation)
-        validate_board_state_structure!(board_state) if ENV['GGN_STRICT_VALIDATION']
+      # Validate individual possibility structure using LCN and STN gems
+      #
+      # @param possibility [Hash] Possibility to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @param source [String] Source location (for error messages)
+      # @param destination [String] Destination location (for error messages)
+      # @raise [ArgumentError] If possibility structure is invalid
+      # @return [void]
+      def validate_possibility!(possibility, piece, source, destination)
+        raise ::ArgumentError, "Possibility for #{piece} #{source}→#{destination} must be a Hash" unless possibility.is_a?(::Hash)
+        raise ::ArgumentError, "Possibility must have 'must' field" unless possibility.key?("must")
+        raise ::ArgumentError, "Possibility must have 'deny' field" unless possibility.key?("deny")
+        raise ::ArgumentError, "Possibility must have 'diff' field" unless possibility.key?("diff")
+
+        validate_lcn_conditions!(possibility["must"], "must", piece, source, destination)
+        validate_lcn_conditions!(possibility["deny"], "deny", piece, source, destination)
+        validate_stn_transition!(possibility["diff"], piece, source, destination)
       end
 
-      # Validates board_state structure in strict mode.
-      #
-      # This optional validation can be enabled via environment variable
-      # to catch malformed board states during development and testing.
-      #
-      # @param board_state [Hash] Board state to validate
+      # Validate LCN conditions using sashite-lcn
+      #
+      # @param conditions [Hash] Conditions to validate
+      # @param field_name [String] Field name for error messages
+      # @param piece [String] Piece identifier (for error messages)
+      # @param source [String] Source location (for error messages)
+      # @param destination [String] Destination location (for error messages)
+      # @raise [ArgumentError] If conditions are invalid
+      # @return [void]
+      def validate_lcn_conditions!(conditions, field_name, piece, source, destination)
+        Lcn.parse(conditions)
+      rescue ArgumentError => e
+        raise ::ArgumentError, "Invalid LCN format in '#{field_name}' for #{piece} #{source}→#{destination}: #{e.message}"
+      end
+
+      # Validate STN transition using sashite-stn
+      #
+      # @param transition [Hash] Transition to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @param source [String] Source location (for error messages)
+      # @param destination [String] Destination location (for error messages)
+      # @raise [ArgumentError] If transition is invalid
+      # @return [void]
+      def validate_stn_transition!(transition, piece, source, destination)
+        Stn.parse(transition)
+      rescue StandardError => e
+        raise ::ArgumentError, "Invalid STN format in 'diff' for #{piece} #{source}→#{destination}: #{e.message}"
+      end
+
+      # Validate location format using CELL and HAND gems
       #
-      # @raise [ArgumentError] If board_state contains invalid data
-      def validate_board_state_structure!(board_state)
-        board_state.each do |square, piece|
-          unless square.is_a?(::String) && !square.empty?
-            raise ::ArgumentError, "Invalid square label: #{square.inspect}"
-          end
+      # @param location [String] Location to validate
+      # @param piece [String] Piece identifier (for error messages)
+      # @raise [ArgumentError] If location format is invalid
+      # @return [void]
+      def validate_location!(location, piece)
+        raise ::ArgumentError, "Location for #{piece} must be a String" unless location.is_a?(::String)
 
-          if piece && (!piece.is_a?(::String) || piece.empty?)
-            raise ::ArgumentError, "Invalid piece at #{square}: #{piece.inspect}"
-          end
-        end
+        valid = Cell.valid?(location) || Hand.reserve?(location)
+        raise ::ArgumentError, "Invalid location format: #{location}" unless valid
       end
     end
   end