sashite-ggn 0.7.0 → 0.8.0

data/lib/sashite/ggn/ruleset.rb

@@ -1,468 +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.
-    #
-    # = Validation Behavior
-    #
-    # When `validate: true` (default), performs:
-    # - Logical contradiction detection in require/prevent conditions
-    # - Implicit requirement duplication detection
-    #
-    # When `validate: false`, skips all internal validations for maximum performance.
-    #
-    # @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.
-      # @param validate [Boolean] Whether to perform internal validations (default: true).
-      #   When false, skips logical contradiction and implicit requirement checks
-      #   for maximum performance.
-      #
-      # @raise [ArgumentError] If data is not a Hash
-      # @raise [ValidationError] If validation is enabled and logical issues are found
-      #
-      # @example Creating from parsed JSON data with full validation
-      #   ggn_data = JSON.parse(File.read('chess.json'))
-      #   ruleset = Ruleset.new(ggn_data)  # validate: true by default
-      #
-      # @example Creating without validation for performance
-      #   ggn_data = JSON.parse(File.read('large_dataset.json'))
-      #   ruleset = Ruleset.new(ggn_data, validate: false)
-      def initialize(data, validate: true)
-        raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
-
+      # @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)
+        validate_structure!(data)
         @data = data
 
-        if validate
-          # Perform enhanced validations for logical consistency
-          validate_no_implicit_requirement_duplications!
-          validate_no_logical_contradictions!
-        end
-
         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: 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.
-      #
-      # 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).
-      #
-      # 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 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
-      #
-      # @raise [ArgumentError] If any parameter is invalid or malformed
-      #
-      # @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 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
+      # Generate all pseudo-legal moves for the given position
       #
-      # @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 }
+      # @note This method evaluates all possible moves in the ruleset.
+      #   For large rulesets, consider filtering by active pieces first.
       #
-      #   # 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 }
-      #     }
+      # @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
       #
-      # @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)
+      # @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)
 
-        # 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)
+            destination.destinations.flat_map do |dest|
+              engine = destination.to(dest)
+              transitions = engine.where(feen)
 
-          # Process all source positions for this actor using functional decomposition
-          process_actor_transitions(actor, source_data, board_state, active_game)
+              transitions.empty? ? [] : [[piece, src, dest, transitions]]
+            end
+          end
         end
       end
 
-      private
-
-      # Processes all possible transitions for a single actor (piece type).
+      # Check if ruleset contains movement rules for specified piece
       #
-      # 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 piece [String] QPI piece identifier
+      # @return [Boolean]
       #
-      # @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
-      #
-      # @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)
-
-          # Process all destination squares for this origin
-          process_origin_transitions(actor, origin, destination_data, board_state, active_game)
-        end
+      # @example
+      #   ruleset.piece?("C:K") # => true
+      def piece?(piece)
+        data.key?(piece)
       end
 
-      # Processes all possible transitions from a single origin square.
-      #
-      # 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.
+      # Return all piece identifiers in ruleset
       #
-      # @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<String>] QPI piece identifiers
       #
-      # @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)
-
-          # 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)
-
-          # Only return successful moves (with at least one valid transition)
-          # filter_map automatically filters out nil values
-          [actor, origin, target, transitions] unless transitions.empty?
-        end
+      # @example
+      #   ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
+      def pieces
+        data.keys
       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
+      # Convert ruleset to hash representation
       #
-      # @raise [ArgumentError] If any parameter is invalid
+      # @return [Hash] GGN data 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
+      # @example
+      #   ruleset.to_h # => { "C:K" => { "e1" => { "e2" => [...] } } }
+      def to_h
+        data
+      end
 
-        unless active_game.is_a?(::String)
-          raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
-        end
+      private
 
-        # Content validation - ensures meaningful data
-        if active_game.empty?
-          raise ::ArgumentError, "active_game cannot be empty"
-        end
+      # Validate GGN data structure
+      #
+      # @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)
 
-        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')."
+        data.each do |piece, sources|
+          validate_piece!(piece)
+          validate_sources!(sources, piece)
         end
-
-        # Validate board_state structure
-        validate_board_state_structure!(board_state)
       end
 
-      # Validates board_state structure.
-      #
-      # Ensures all square labels are valid strings and all pieces are either nil
-      # or valid strings. This validation helps catch common integration errors
-      # where malformed board states are passed to the GGN engine.
-      #
-      # @param board_state [Hash] Board state to validate
-      #
-      # @raise [ArgumentError] If board_state contains invalid data
+      # Validate QPI piece identifier using sashite-qpi
       #
-      # @example Valid board state
-      #   { "e1" => "CHESS:K", "e2" => nil, "d1" => "CHESS:Q" }
-      #
-      # @example Invalid board states (would raise ArgumentError)
-      #   { 123 => "CHESS:K" }           # Invalid square label
-      #   { "e1" => "" }                 # Empty piece string
-      #   { "e1" => 456 }                # Non-string piece
-      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}. Must be a non-empty String."
-          end
-
-          if piece && (!piece.is_a?(::String) || piece.empty?)
-            raise ::ArgumentError, "Invalid piece at #{square}: #{piece.inspect}. Must be a String or nil."
-          end
-        end
+      # @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
 
-      # Validates that transitions don't duplicate implicit requirements in the require field.
+      # Validate sources hash structure
       #
-      # According to GGN specification, implicit requirements (like the source piece
-      # being present at the source square) should NOT be explicitly specified in
-      # the require field, as this creates redundancy and potential inconsistency.
-      #
-      # @raise [ValidationError] If any transition duplicates implicit requirements
-      #
-      # @example Invalid GGN that would be rejected
-      #   {
-      #     "CHESS:K": {
-      #       "e1": {
-      #         "e2": [{
-      #           "require": { "e1": "CHESS:K" },  # ❌ Redundant implicit requirement
-      #           "perform": { "e1": null, "e2": "CHESS:K" }
-      #         }]
-      #       }
-      #     }
-      #   }
-      def validate_no_implicit_requirement_duplications!
-        @data.each do |actor, source_data|
-          source_data.each do |origin, destination_data|
-            destination_data.each do |target, transition_list|
-              transition_list.each_with_index do |transition, index|
-                validate_single_transition_implicit_requirements!(
-                  transition, actor, origin, target, index
-                )
-              end
-            end
-          end
+      # @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)
+
+        sources.each do |source, destinations|
+          validate_location!(source, piece)
+          validate_destinations!(destinations, piece, source)
         end
       end
 
-      # Validates a single transition for implicit requirement duplication.
-      #
-      # @param transition [Hash] The transition rule to validate
-      # @param actor [String] GAN identifier of the piece
-      # @param origin [String] Source square
-      # @param target [String] Destination square
-      # @param index [Integer] Index of transition for error reporting
+      # Validate destinations hash structure
       #
-      # @raise [ValidationError] If implicit requirements are duplicated
-      def validate_single_transition_implicit_requirements!(transition, actor, origin, target, index)
-        return unless transition.is_a?(::Hash) && transition["require"].is_a?(::Hash)
+      # @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)
 
-        require_conditions = transition["require"]
-
-        # Check if the source square requirement is explicitly specified
-        if require_conditions.key?(origin) && require_conditions[origin] == actor
-          raise ValidationError,
-            "Implicit requirement duplication detected in #{actor} from #{origin} to #{target} " \
-            "(transition #{index}): 'require' field explicitly specifies that #{origin} contains #{actor}, " \
-            "but this is already implicit from the move structure. Remove this redundant requirement."
+        destinations.each do |destination, possibilities|
+          validate_location!(destination, piece)
+          validate_possibilities!(possibilities, piece, source, destination)
         end
       end
 
-      # Validates that transitions don't contain logical contradictions between require and prevent.
-      #
-      # A logical contradiction occurs when the same square is required to be in
-      # the same state in both require and prevent fields. This creates an impossible
-      # condition that can never be satisfied.
-      #
-      # @raise [ValidationError] If any transition contains logical contradictions
+      # Validate possibilities array structure
       #
-      # @example Invalid GGN that would be rejected
-      #   {
-      #     "CHESS:B": {
-      #       "c1": {
-      #         "f4": [{
-      #           "require": { "d2": "empty" },
-      #           "prevent": { "d2": "empty" },  # ❌ Logical contradiction
-      #           "perform": { "c1": null, "f4": "CHESS:B" }
-      #         }]
-      #       }
-      #     }
-      #   }
-      def validate_no_logical_contradictions!
-        @data.each do |actor, source_data|
-          source_data.each do |origin, destination_data|
-            destination_data.each do |target, transition_list|
-              transition_list.each_with_index do |transition, index|
-                validate_single_transition_logical_consistency!(
-                  transition, actor, origin, target, index
-                )
-              end
-            end
-          end
+      # @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)
+
+        possibilities.each do |possibility|
+          validate_possibility!(possibility, piece, source, destination)
         end
       end
 
-      # Validates a single transition for logical contradictions.
-      #
-      # @param transition [Hash] The transition rule to validate
-      # @param actor [String] GAN identifier of the piece
-      # @param origin [String] Source square
-      # @param target [String] Destination square
-      # @param index [Integer] Index of transition for error reporting
-      #
-      # @raise [ValidationError] If logical contradictions are found
-      def validate_single_transition_logical_consistency!(transition, actor, origin, target, index)
-        return unless transition.is_a?(::Hash)
-
-        require_conditions = transition["require"]
-        prevent_conditions = transition["prevent"]
+      # 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
 
-        # Skip if either field is missing or not a hash
-        return unless require_conditions.is_a?(::Hash) && prevent_conditions.is_a?(::Hash)
+      # 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
 
-        # Find squares that appear in both require and prevent
-        conflicting_squares = require_conditions.keys & prevent_conditions.keys
+      # 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
 
-        # Check each conflicting square for state contradictions
-        conflicting_squares.each do |square|
-          required_state = require_conditions[square]
-          prevented_state = prevent_conditions[square]
+      # Validate location format using CELL and HAND gems
+      #
+      # @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)
 
-          # Logical contradiction: same state required and prevented
-          if required_state == prevented_state
-            raise ValidationError,
-              "Logical contradiction detected in #{actor} from #{origin} to #{target} " \
-              "(transition #{index}): square #{square} cannot simultaneously " \
-              "require state '#{required_state}' and prevent state '#{prevented_state}'. " \
-              "This creates an impossible condition that can never be satisfied."
-          end
-        end
+        valid = Cell.valid?(location) || Hand.reserve?(location)
+        raise ::ArgumentError, "Invalid location format: #{location}" unless valid
       end
     end
   end