sashite-pmn 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ebaf0b731c5fa324e1515369a8a98bc3fc4a6a8094d67023728a04c650a963
-  data.tar.gz: 6a4e1ba06a8afd9015ae8dcc89795fa9f28a7b573d4502b13e52d5ed380c3630
+  metadata.gz: bbe033acc463b83e9ed43201cb847a8c960f6dd662644b5f4f524691a52f0dae
+  data.tar.gz: ca9cd6b39a1738e44459e8609a38647045634bd8aa5d765b925ce8f790ccab75
 SHA512:
-  metadata.gz: c6624a7cb869903504622c7a7a34f9a5a73a3c63967ed6c7d0ff89e9e4fe8782e806b94742ea3156fd41b54159cc81c5921e59e5cd27c97bf076ca90482148d2
-  data.tar.gz: 7d871f7cdc7509b9c8ec3ea77c0375652423940be53f157e60e4debebc604ed2a10558ecc7d0a9e6e7a892e9a771bbabab0151d2929127de87d81ee2ac5c332f
+  metadata.gz: f4bb7166a1d52ed805b3910da56f32f44dcbe8326e194f1663f79aef1b8eb2fe5279832f818153ac8fed391d3d82235f8ddcc067764bd7c30fc909d4b77bc5d1
+  data.tar.gz: fec38eece56648760fac10727af116007373e085d2d7d069b4441e77a5f6598d2851076ecea86931ecdd1baf11b87e089c12e902ad532779363db108400dc32b

data/README.md

@@ -52,6 +52,7 @@ move.to_a                                     # => ["e2", "e4", "C:P"]
 # Validate PMN arrays
 Sashite::Pmn.valid?(["e2", "e4", "C:P"])     # => true
 Sashite::Pmn.valid?(%w[e2 e4])               # => true (inferred piece)
+Sashite::Pmn.valid?([])                      # => true (pass move)
 Sashite::Pmn.valid?(["e2"])                  # => false (incomplete)
 
 # Create moves programmatically
@@ -60,6 +61,29 @@ move = Sashite::Pmn.from_actions([
                                  ])
 ```
 
+### Pass Moves
+
+A **pass move** is represented by an empty array `[]`, allowing a player to voluntarily conclude their turn without performing any displacement or mutation.
+
+```ruby
+# Parse a pass move
+pass = Sashite::Pmn.parse([])
+pass.valid?                                   # => true
+pass.pass?                                    # => true
+pass.empty?                                   # => true
+pass.actions                                  # => []
+pass.to_a                                     # => []
+
+# Create a pass move directly
+pass = Sashite::Pmn::Move.new
+pass.pass? # => true
+
+# Validate pass moves
+Sashite::Pmn.valid?([]) # => true
+```
+
+**Important**: According to the Sashité Protocol, a pass move that results in a position identical to a previous position violates the uniqueness constraint. Game engines must enforce this constraint.
+
 ### Action Decomposition
 
 ```ruby
@@ -78,9 +102,12 @@ action.piece                                  # => nil
 action.piece_specified?                       # => false
 action.inferred?                              # => true
 
-# Pass moves (source == destination) are allowed
-pass = Sashite::Pmn.parse(["e4", "e4", "C:P"])
-pass.valid? # => true
+# In-place transformations (source == destination)
+transform = Sashite::Pmn.parse(["e4", "e4", "C:+P"])
+transform.valid?                              # => true
+action = transform.actions.first
+action.in_place?                              # => true
+action.transformation?                        # => true
 
 # Reserve operations
 drop = Sashite::Pmn.parse(["*", "e5", "S:P"]) # Drop from reserve
@@ -96,32 +123,17 @@ castling = Sashite::Pmn.parse([
                                 "h1", "f1", "C:R"
                               ])
 castling.compound?                            # => true
+castling.simple?                              # => false
+castling.pass?                                # => false
 castling.actions.size                         # => 2
 
-# En passant (explicit + inferred variant)
+# En passant
 en_passant = Sashite::Pmn.parse([
                                   "e5", "f6", "C:P",
                                   "f5", "*", "c:p"
                                 ])
-Sashite::Pmn.parse(%w[e5 f6]).valid? # => true (context-dependent)
-```
-
-### Action Analysis
-
-```ruby
-action = move.actions.first
-
-# Location predicates
-action.board_to_board?                        # => true
-action.from_reserve?                          # => false
-action.to_reserve?                            # => false
-action.drop?                                  # => false
-action.capture?                               # => false
-action.board_move?                            # => true
-
-# Validation predicates
-action.valid?                                 # => true
-action.piece_valid?                           # => true or false depending on piece
+en_passant.has_captures?                      # => true
+en_passant.board_moves.size                   # => 1
 ```
 
 ### Move Analysis
@@ -133,6 +145,7 @@ move = Sashite::Pmn.parse([
                           ])
 
 # Structure analysis
+move.pass?                                    # => false
 move.simple?                                  # => false
 move.compound?                                # => true
 move.size                                     # => 2
@@ -143,44 +156,67 @@ move.has_drops?                               # => false
 move.has_captures?                            # => false
 move.board_moves.size                         # => 2
 
-# Extract info
+# Extract information
 move.sources                                  # => ["e1", "h1"]
 move.destinations                             # => ["g1", "f1"]
 move.pieces                                   # => ["C:K", "C:R"]
 move.has_inferred?                            # => false
 ```
 
+### Action Predicates
+
+```ruby
+action = move.actions.first
+
+# Location predicates
+action.board_to_board?                        # => true
+action.from_reserve?                          # => false
+action.to_reserve?                            # => false
+action.drop?                                  # => false
+action.capture?                               # => false
+action.board_move?                            # => true
+action.in_place?                              # => false (source != destination)
+action.transformation?                        # => false (not in-place with state change)
+
+# Validation predicates
+action.valid?                                 # => true
+action.piece_valid?                           # => true or false depending on piece
+```
+
 ### Error Handling
 
 ```ruby
 # Invalid action built directly raises action-level errors
 begin
   Sashite::Pmn::Action.new("invalid", "e4", "C:P")
-rescue Sashite::Pmn::InvalidLocationError => e
+rescue Sashite::Pmn::Error::Location => e
   puts e.message
 end
 
 begin
   Sashite::Pmn::Action.new("e2", "e4", "InvalidPiece")
-rescue Sashite::Pmn::InvalidPieceError => e
+rescue Sashite::Pmn::Error::Piece => e
   puts e.message
 end
 
-# Parsing a move wraps action-level errors as InvalidMoveError
+# Parsing a move wraps action-level errors as Error::Move
 begin
-  Sashite::Pmn.parse(["e2"])                  # Incomplete action
-rescue Sashite::Pmn::InvalidMoveError => e
-  puts e.message                              # => "Invalid PMN array length: 1", etc.
+  Sashite::Pmn.parse(["e2"]) # Incomplete action
+rescue Sashite::Pmn::Error::Move => e
+  puts e.message
 end
+
+# Pass moves are always valid structurally
+Sashite::Pmn.parse([]).valid? # => true (never raises)
 ```
 
 ## API Reference
 
 ### Main Module Methods
 
-* `Sashite::Pmn.parse(array)` — Parse a PMN array into a `Move` object.
-* `Sashite::Pmn.valid?(array)` — Check if an array is valid PMN notation (non-raising).
-* `Sashite::Pmn.from_actions(actions)` — Build a `Move` from `Action` objects.
+* `Sashite::Pmn.parse(array)` — Parse a PMN array into a `Move` object. Accepts empty arrays `[]` for pass moves.
+* `Sashite::Pmn.valid?(array)` — Check if an array is valid PMN notation (non-raising). Returns `true` for `[]`.
+* `Sashite::Pmn.from_actions(actions)` — Build a `Move` from `Action` objects. Pass empty array for pass moves.
 * `Sashite::Pmn.valid_location?(location)` — Check if a location is valid (CELL or `"*"`).
 * `Sashite::Pmn.valid_piece?(piece)` — Check if a piece is valid QPI.
 
@@ -188,28 +224,31 @@ end
 
 #### Creation
 
-* `Sashite::Pmn::Move.new(*elements)` — Create from PMN elements (variadic).
-  *Note*: `Move.new(["e2","e4","C:P"])` is **not** accepted; pass individual arguments.
-* `Sashite::Pmn::Move.from_actions(actions)` — Create from `Action` objects.
+* `Sashite::Pmn::Move.new(*elements)` — Create from PMN elements (variadic). Call with no arguments for pass move.
+  * `Move.new("e2", "e4", "C:P")` — Standard move
+  * `Move.new` — Pass move (empty)
+  * **Note**: `Move.new(["e2","e4","C:P"])` is **not** accepted; pass individual arguments.
+* `Sashite::Pmn::Move.from_actions(actions)` — Create from `Action` objects. Pass `[]` for pass move.
 
 #### Validation & Data
 
 * `#valid?` — Check overall validity.
-* `#actions` — Ordered array of `Action` objects (frozen).
-* `#pmn_array` — Original PMN elements (frozen).
-* `#to_a` — Copy of the PMN elements.
+* `#actions` — Ordered array of `Action` objects (frozen). Empty for pass moves.
+* `#pmn_array` — Original PMN elements (frozen). Empty for pass moves.
+* `#to_a` — Copy of the PMN elements. Returns `[]` for pass moves.
 
 #### Structure & Queries
 
-* `#size` / `#length` — Number of actions.
-* `#empty?` — No actions?
-* `#simple?` — Exactly one action?
-* `#compound?` — Multiple actions?
-* `#first_action` / `#last_action` — Convenience accessors.
-* `#has_drops?` / `#has_captures?` — Presence of drops/captures.
-* `#board_moves` — Actions that are board-to-board.
-* `#sources` / `#destinations` / `#pieces` — Unique lists.
-* `#has_inferred?` — Any action with inferred piece?
+* `#size` / `#length` — Number of actions. Returns `0` for pass moves.
+* `#empty?` — No actions? Returns `true` for pass moves.
+* `#pass?` — Is this a pass move? Returns `true` only for empty moves.
+* `#simple?` — Exactly one action? Returns `false` for pass moves.
+* `#compound?` — Multiple actions? Returns `false` for pass moves.
+* `#first_action` / `#last_action` — Convenience accessors. Return `nil` for pass moves.
+* `#has_drops?` / `#has_captures?` — Presence of drops/captures. Return `false` for pass moves.
+* `#board_moves` — Actions that are board-to-board. Returns `[]` for pass moves.
+* `#sources` / `#destinations` / `#pieces` — Unique lists. Return `[]` for pass moves.
+* `#has_inferred?` — Any action with inferred piece? Returns `false` for pass moves.
 
 ### Action Class
 
@@ -229,26 +268,39 @@ end
 * `#from_reserve?`, `#to_reserve?`
 * `#reserve_to_board?` (drop), `#board_to_reserve?` (capture), `#board_to_board?`
 * `#drop?` (alias), `#capture?` (alias), `#board_move?`
+* `#in_place?` — Source equals destination?
+* `#transformation?` — In-place with state change?
 * `#valid?`
 
 ### Exceptions
 
 * `Sashite::Pmn::Error` — Base error class
-* `Sashite::Pmn::InvalidMoveError` — Invalid PMN sequence / parsing failure
-* `Sashite::Pmn::InvalidActionError` — Invalid atomic action
-* `Sashite::Pmn::InvalidLocationError` — Invalid location (not CELL or HAND)
-* `Sashite::Pmn::InvalidPieceError` — Invalid piece (not QPI format)
+* `Sashite::Pmn::Error::Move` — Invalid PMN sequence / parsing failure
+* `Sashite::Pmn::Error::Action` — Invalid atomic action
+* `Sashite::Pmn::Error::Location` — Invalid location (not CELL or HAND)
+* `Sashite::Pmn::Error::Piece` — Invalid piece (not QPI format)
 
 ## Format Specification (Summary)
 
 ### Structure
 
-PMN moves are flat **arrays** containing action sequences:
+PMN moves are flat **arrays** containing action sequences or empty for pass moves:
 
 ```
-[<element-1>, <element-2>, <element-3>, <element-4>, <element-5>, <element-6>, ...]
+[]                                            # Pass move
+[<element-1>, <element-2>, <element-3>, ...] # Action sequence
 ```
 
+### Pass Move Format
+
+A **pass move** is represented by an empty array:
+
+```json
+[]
+```
+
+This indicates that the active player concludes their turn without performing any action. The resulting position must respect the position uniqueness constraint defined in the Sashité Protocol.
+
 ### Action Format
 
 Each action consists of 2 or 3 consecutive elements:
@@ -263,18 +315,32 @@ Each action consists of 2 or 3 consecutive elements:
 
 ### Array Length Rules
 
-* Minimum: 2 elements (one action with inferred piece)
-* Valid lengths: multiple of 3, **or** multiple of 3 plus 2
+* **Pass move**: 0 elements (empty array)
+* **Action moves**: Minimum 2 elements (one action with inferred piece)
+* Valid non-empty lengths: multiple of 3, **or** multiple of 3 plus 2
 
-### Pass & Same-Location Actions
+### In-Place Actions
 
 Actions where **source == destination** are allowed, enabling:
 
-* Pass moves (turn-only or rule-driven)
-* In-place transformations (e.g., promotions specified with QPI)
+* In-place transformations with state change (e.g., `["e4", "e4", "C:+P"]`)
+* Context-dependent mutations specified by game rules
+
+**Important**: Actions without observable effect (same location, same piece state) should be avoided. Use pass moves `[]` instead for turn-only actions.
 
 ## Game Examples
 
+### Pass Moves
+
+```ruby
+# Player passes their turn
+pass = Sashite::Pmn.parse([])
+pass.pass? # => true
+
+# In games where passing is strategic (e.g., Go, some variants)
+game_engine.execute_move([]) # Pass turn to opponent
+```
+
 ### Western Chess
 
 ```ruby
@@ -295,6 +361,9 @@ en_passant = Sashite::Pmn.parse([
 
 # Promotion
 promotion = Sashite::Pmn.parse(["e7", "e8", "C:Q"])
+
+# In-place promotion (variant rule)
+in_place_promotion = Sashite::Pmn.parse(["e8", "e8", "C:Q"])
 ```
 
 ### Japanese Shōgi
@@ -311,6 +380,9 @@ capture = Sashite::Pmn.parse([
 
 # Promotion
 promotion = Sashite::Pmn.parse(["h8", "i8", "S:+S"])
+
+# Pass (uncommon in Shōgi but structurally valid)
+pass = Sashite::Pmn.parse([])
 ```
 
 ### Chinese Xiangqi
@@ -326,6 +398,20 @@ cannon_capture = Sashite::Pmn.parse([
                                     ])
 ```
 
+### Go
+
+```ruby
+# Place stone
+place_stone = Sashite::Pmn.parse(["*", "d4", "G:B"])
+
+# Pass (very common in Go)
+pass = Sashite::Pmn.parse([])
+pass.pass? # => true
+
+# Consecutive passes typically end the game in Go
+end_game_and_score if last_move.pass? && current_move.pass?
+```
+
 ## Advanced Usage
 
 ### Move Composition
@@ -337,6 +423,10 @@ actions << Sashite::Pmn::Action.new("d7", "d5", "c:p")
 
 move = Sashite::Pmn.from_actions(actions)
 move.to_a # => ["e2", "e4", "C:P", "d7", "d5", "c:p"]
+
+# Create pass move
+pass = Sashite::Pmn.from_actions([])
+pass.pass? # => true
 ```
 
 ### Integration with Game Engines
@@ -346,26 +436,76 @@ class GameEngine
   def execute_move(pmn_array)
     move = Sashite::Pmn.parse(pmn_array)
 
+    # Handle pass moves
+    if move.pass?
+      handle_pass_move
+      switch_active_player
+      return
+    end
+
+    # Execute each action
     move.actions.each do |action|
       if action.from_reserve?
         place_piece(action.destination, action.piece)
       elsif action.to_reserve?
         capture_piece(action.source)
+      elsif action.in_place?
+        transform_piece(action.source, action.piece)
       else
         move_piece(action.source, action.destination, action.piece)
       end
     end
+
+    switch_active_player
+  end
+
+  private
+
+  def handle_pass_move
+    # Check position uniqueness constraint
+    raise "Pass move creates repeated position (protocol violation)" if position_seen_before?(current_position)
+
+    # Record pass in game history
+    record_move([])
   end
 
   # ...
 end
 ```
 
+### Position Tracking with Pass Moves
+
+```ruby
+class PositionTracker
+  def initialize
+    @seen_positions = Set.new
+    @position_history = []
+  end
+
+  def record_move(pmn_array, resulting_position)
+    move = Sashite::Pmn.parse(pmn_array)
+
+    # For pass moves, verify uniqueness constraint
+    if move.pass? && @seen_positions.include?(resulting_position)
+      raise "Pass move violates position uniqueness constraint"
+    end
+
+    @seen_positions.add(resulting_position)
+    @position_history << { move: pmn_array, position: resulting_position }
+  end
+
+  def position_seen?(position)
+    @seen_positions.include?(position)
+  end
+end
+```
+
 ## Design Properties
 
 * **Rule-agnostic**: Independent of specific game mechanics
 * **Mechanical decomposition**: Breaks complex moves into atomic actions
 * **Array-based**: Simple, interoperable structure
+* **Pass move support**: Empty arrays `[]` for voluntary turn conclusion
 * **Sequential execution**: Actions execute in array order
 * **Piece inference**: Optional piece specification when context is clear
 * **Universal applicability**: Works across board game systems
@@ -374,13 +514,23 @@ end
 
 ## Mechanical Semantics (Recap)
 
-1. **Source state change**:
+### Pass Moves
+
+Pass moves (`[]`) indicate:
+* No piece displacement occurs
+* No piece mutation occurs
+* The active player voluntarily concludes their turn
+* The resulting position must be unique according to protocol constraints
 
+### Action Execution
+
+For non-pass moves, each action applies atomically:
+
+1. **Source state change**:
    * CELL → becomes empty
    * HAND `"*"` → remove piece from reserve
 
 2. **Destination state change**:
-
    * CELL → contains final piece
    * HAND `"*"` → add piece to reserve
 
@@ -388,6 +538,28 @@ end
 
 4. **Atomic commitment**: Each action applies atomically
 
+## Protocol Compliance
+
+### Position Uniqueness Constraint
+
+According to the Sashité Protocol, all positions within a match must be unique. This applies to pass moves:
+
+* A pass move that results in a position identical to any previous position **violates** the constraint
+* Game engines must track position history and enforce this rule
+* However, if the position after a pass move is unique (due to time-sensitive state or other factors), the pass is valid
+
+### Authorized Operations
+
+PMN supports all protocol-authorized operations:
+
+* **Board-to-board**: Standard piece movement
+* **Board-to-hand**: Captures to reserve
+* **Hand-to-board**: Drops from reserve
+* **In-place transformations**: State changes without displacement
+* **Pass moves**: Voluntary turn conclusion
+
+**Prohibited**: Hand-to-hand transfers are not allowed by the protocol.
+
 ## License
 
 Available as open source under the [MIT License](https://github.com/sashite/pmn.rb/raw/main/LICENSE.md).
@@ -403,6 +575,8 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/sashi
 * [CELL Specification](https://sashite.dev/specs/cell/)
 * [HAND Specification](https://sashite.dev/specs/hand/)
 * [QPI Specification](https://sashite.dev/specs/qpi/)
+* [Sashité Protocol](https://sashite.dev/protocol/)
+* [Glossary](https://sashite.dev/glossary/)
 
 ## About
 

data/lib/sashite/pmn/action.rb

@@ -3,6 +3,7 @@
 require "sashite/cell"
 require "sashite/hand"
 require "sashite/qpi"
+
 require_relative "error"
 
 module Sashite
@@ -30,8 +31,8 @@ module Sashite
       # @param source [String] CELL or "*"
       # @param destination [String] CELL or "*"
       # @param piece [String, nil] QPI string (optional)
-      # @raise [InvalidLocationError] if source/destination are invalid
-      # @raise [InvalidPieceError] if piece is provided but invalid
+      # @raise [Error::Location] if source/destination are invalid
+      # @raise [Error::Piece] if piece is provided but invalid
       def initialize(source, destination, piece = nil)
         validate_source!(source)
         validate_destination!(destination)
@@ -60,32 +61,32 @@ module Sashite
       def piece_valid?
         return false if piece.nil?
 
-        Qpi.valid?(piece)
+        ::Sashite::Qpi.valid?(piece)
       end
 
       # @return [Boolean] true if source is HAND ("*")
       def from_reserve?
-        Hand.reserve?(source)
+        ::Sashite::Hand.reserve?(source)
       end
 
       # @return [Boolean] true if destination is HAND ("*")
       def to_reserve?
-        Hand.reserve?(destination)
+        ::Sashite::Hand.reserve?(destination)
       end
 
       # @return [Boolean] true if both endpoints are board locations
       def board_to_board?
-        Cell.valid?(source) && Cell.valid?(destination)
+        ::Sashite::Cell.valid?(source) && ::Sashite::Cell.valid?(destination)
       end
 
       # @return [Boolean] true if the action places from reserve to board
       def drop?
-        from_reserve? && Cell.valid?(destination)
+        from_reserve? && ::Sashite::Cell.valid?(destination)
       end
 
       # @return [Boolean] true if the action takes from board to reserve
       def capture?
-        Cell.valid?(source) && to_reserve?
+        ::Sashite::Cell.valid?(source) && to_reserve?
       end
 
       # @return [Boolean] true when neither drop nor capture
@@ -111,11 +112,11 @@ module Sashite
       def valid?
         valid_location?(source) &&
           valid_location?(destination) &&
-          (piece.nil? || Qpi.valid?(piece))
+          (piece.nil? || ::Sashite::Qpi.valid?(piece))
       end
 
       # @param other [Object]
-      # @return [Boolean] equality by {source, destination, piece}
+      # @return [Boolean] equality by source, destination, piece
       def ==(other)
         return false unless other.is_a?(Action)
 
@@ -145,8 +146,8 @@ module Sashite
       # @return [Action]
       # @raise [ArgumentError] if required keys are missing
       def self.from_hash(hash)
-        raise ArgumentError, "Hash must include :source" unless hash.key?(:source)
-        raise ArgumentError, "Hash must include :destination" unless hash.key?(:destination)
+        raise ::ArgumentError, "Hash must include :source" unless hash.key?(:source)
+        raise ::ArgumentError, "Hash must include :destination" unless hash.key?(:destination)
 
         new(hash[:source], hash[:destination], hash[:piece])
       end
@@ -156,34 +157,34 @@ module Sashite
       # ---------- Internal validation helpers -------------------------------
 
       # @param src [String]
-      # @raise [InvalidLocationError]
+      # @raise [Error::Location]
       def validate_source!(src)
         return if valid_location?(src)
 
-        raise InvalidLocationError, "Invalid source location: #{src.inspect}"
+        raise Error::Location, "Invalid source location: #{src.inspect}"
       end
 
       # @param dst [String]
-      # @raise [InvalidLocationError]
+      # @raise [Error::Location]
       def validate_destination!(dst)
         return if valid_location?(dst)
 
-        raise InvalidLocationError, "Invalid destination location: #{dst.inspect}"
+        raise Error::Location, "Invalid destination location: #{dst.inspect}"
       end
 
       # @param qpi [String, nil]
-      # @raise [InvalidPieceError]
+      # @raise [Error::Piece]
       def validate_piece!(qpi)
         return if qpi.nil?
-        return if Qpi.valid?(qpi)
+        return if ::Sashite::Qpi.valid?(qpi)
 
-        raise InvalidPieceError, "Invalid piece QPI format: #{qpi.inspect}"
+        raise Error::Piece, "Invalid piece QPI format: #{qpi.inspect}"
       end
 
       # @param location [String]
       # @return [Boolean] true if CELL or HAND ("*")
       def valid_location?(location)
-        Cell.valid?(location) || Hand.reserve?(location)
+        ::Sashite::Cell.valid?(location) || ::Sashite::Hand.reserve?(location)
       end
     end
   end

data/lib/sashite/pmn/error.rb

@@ -2,19 +2,52 @@
 
 module Sashite
   module Pmn
-    # Base class for all PMN-related errors
-    class Error < StandardError; end
+    # Base error namespace for PMN.
+    #
+    # Usage patterns:
+    #   rescue Sashite::Pmn::Error => e
+    #   rescue Sashite::Pmn::Error::Move
+    #   rescue Sashite::Pmn::Error::Location, Sashite::Pmn::Error::Piece
+    class Error < ::StandardError
+      # Raised when a PMN move (sequence) is malformed or invalid.
+      #
+      # @example
+      #   begin
+      #     Sashite::Pmn::Move.new("e2")  # Incomplete action
+      #   rescue Sashite::Pmn::Error::Move => e
+      #     warn "Invalid move sequence: #{e.message}"
+      #   end
+      class Move < Error; end
 
-    # Raised when a PMN move (sequence) is malformed or invalid
-    class InvalidMoveError < Error; end
+      # Raised when an atomic action is malformed or fails validation.
+      #
+      # @example
+      #   begin
+      #     Sashite::Pmn::Action.new("invalid", "e4", "C:P")
+      #   rescue Sashite::Pmn::Error::Action => e
+      #     warn "Invalid atomic action: #{e.message}"
+      #   end
+      class Action < Error; end
 
-    # Raised when an atomic action is malformed or fails validation
-    class InvalidActionError < Error; end
+      # Raised when a location is neither a valid CELL coordinate nor HAND ("*").
+      #
+      # @example
+      #   begin
+      #     Sashite::Pmn::Action.new("ZZ99", "e4", "C:P")
+      #   rescue Sashite::Pmn::Error::Location => e
+      #     warn "Invalid location: #{e.message}"
+      #   end
+      class Location < Action; end
 
-    # Raised when a location is neither a valid CELL coordinate nor HAND ("*")
-    class InvalidLocationError < InvalidActionError; end
-
-    # Raised when a piece identifier is not valid QPI
-    class InvalidPieceError < InvalidActionError; end
+      # Raised when a piece identifier is not valid QPI format.
+      #
+      # @example
+      #   begin
+      #     Sashite::Pmn::Action.new("e2", "e4", "NotQPI")
+      #   rescue Sashite::Pmn::Error::Piece => e
+      #     warn "Invalid piece QPI: #{e.message}"
+      #   end
+      class Piece < Action; end
+    end
   end
 end

data/lib/sashite/pmn/move.rb

@@ -7,31 +7,35 @@ module Sashite
   module Pmn
     # Represents a complete move in PMN notation.
     #
-    # A Move is a sequence of one or more atomic actions described by a flat list
-    # of elements. Every 2 or 3 consecutive elements form an action:
+    # A Move is a sequence of zero or more atomic actions described by a flat list
+    # of elements:
+    #   []                               # pass move (empty array)
     #   [source, destination]            # inferred piece
     #   [source, destination, piece]     # explicit QPI piece
     #
-    # Valid lengths: multiple of 3 OR multiple of 3 + 2 (minimum 2).
+    # Valid lengths:
+    #   - 0 (pass move)
+    #   - multiple of 3 OR multiple of 3 + 2 (minimum 2 for non-pass moves)
     class Move
-      # @return [Array<Action>] ordered sequence of actions
+      # @return [Array<Action>] ordered sequence of actions (empty for pass moves)
       attr_reader :actions
 
-      # @return [Array<String>] original PMN elements (frozen)
+      # @return [Array<String>] original PMN elements (frozen, empty for pass moves)
       attr_reader :pmn_array
 
       # Create a Move from PMN elements (variadic only).
       #
       # @param pmn_elements [Array<String>] passed as individual args
-      # @raise [InvalidMoveError] if called with a single Array or if invalid
+      # @raise [Error::Move] if called with a single Array or if invalid
       #
       # @example
-      #   Move.new("e2","e4","C:P")
-      #   Move.new("e2","e4")
+      #   Move.new("e2","e4","C:P")    # Standard move
+      #   Move.new("e2","e4")          # Inferred piece
+      #   Move.new                     # Pass move (no arguments)
       def initialize(*pmn_elements)
         # single-array form is intentionally not supported (entropy reduction)
-        if pmn_elements.size == 1 && pmn_elements.first.is_a?(Array)
-          raise InvalidMoveError,
+        if pmn_elements.size == 1 && pmn_elements.first.is_a?(::Array)
+          raise Error::Move,
                 'PMN must be passed as individual arguments, e.g. Move.new("e2","e4","C:P")'
         end
 
@@ -45,12 +49,17 @@ module Sashite
       # @return [Boolean] true if PMN length is valid and all actions are valid
       def valid?
         valid_length? && actions.all?(&:valid?)
-      rescue StandardError
+      rescue ::StandardError
         false
       end
 
       # Shape / structure -----------------------------------------------------
 
+      # @return [Boolean] is this a pass move (no actions)?
+      def pass?
+        actions.empty?
+      end
+
       # @return [Boolean] exactly one action?
       def simple?
         actions.size == 1
@@ -71,13 +80,13 @@ module Sashite
         actions.last
       end
 
-      # @return [Integer] number of actions
+      # @return [Integer] number of actions (0 for pass moves)
       def size
         actions.size
       end
       alias length size
 
-      # @return [Boolean] true if no actions
+      # @return [Boolean] true if no actions (pass move)
       def empty?
         actions.empty?
       end
@@ -121,7 +130,7 @@ module Sashite
 
       # Conversion ------------------------------------------------------------
 
-      # @return [Array<String>] copy of original PMN elements
+      # @return [Array<String>] copy of original PMN elements (empty array for pass moves)
       def to_a
         pmn_array.dup
       end
@@ -144,7 +153,11 @@ module Sashite
 
       # @return [String]
       def inspect
-        "#<#{self.class.name} actions=#{actions.size} pmn=#{pmn_array.inspect}>"
+        if pass?
+          "#<#{self.class.name} pass=true>"
+        else
+          "#<#{self.class.name} actions=#{actions.size} pmn=#{pmn_array.inspect}>"
+        end
       end
 
       # Functional composition -----------------------------------------------
@@ -170,18 +183,23 @@ module Sashite
       # Validation ------------------------------------------------------------
 
       def validate_array!(array)
-        raise InvalidMoveError, "PMN must be an array, got #{array.class}" unless array.is_a?(Array)
-        raise InvalidMoveError, "PMN array cannot be empty" if array.empty?
+        raise Error::Move, "PMN must be an array, got #{array.class}" unless array.is_a?(::Array)
+
+        # Empty arrays are valid (pass moves)
+        return if array.empty?
 
-        raise InvalidMoveError, "All PMN elements must be strings" unless array.all?(String)
+        raise Error::Move, "All PMN elements must be strings" unless array.all?(::String)
 
         return if valid_length?(array)
 
-        raise InvalidMoveError, "Invalid PMN array length: #{array.size}"
+        raise Error::Move, "Invalid PMN array length: #{array.size}"
       end
 
-      # Valid lengths: (size % 3 == 0) OR (size % 3 == 2), minimum 2.
+      # Valid lengths:
+      #   - 0 (pass move)
+      #   - (size % 3 == 0) OR (size % 3 == 2), minimum 2
       def valid_length?(array = pmn_array)
+        return true if array.empty? # Pass move
         return false if array.size < 2
 
         r = array.size % 3
@@ -191,6 +209,8 @@ module Sashite
       # Parsing ---------------------------------------------------------------
 
       def parse_actions(array)
+        return [] if array.empty? # Pass move has no actions
+
         actions = []
         index = 0
 
@@ -204,21 +224,21 @@ module Sashite
             actions << Action.new(array[index], array[index + 1], array[index + 2])
             index += 3
           else
-            raise InvalidMoveError, "Invalid action group at index #{index}"
+            raise Error::Move, "Invalid action group at index #{index}"
           end
         end
 
         actions
-      rescue InvalidActionError => e
+      rescue Error::Action => e
         # Normalize action-level errors as move-level errors during parsing
-        raise InvalidMoveError, "Invalid action while parsing move at index #{index}: #{e.message}"
+        raise Error::Move, "Invalid action while parsing move at index #{index}: #{e.message}"
       end
 
       def validate_actions!
         actions.each_with_index do |action, i|
           next if action.valid?
 
-          raise InvalidMoveError, "Invalid action at position #{i}: #{action.inspect}"
+          raise Error::Move, "Invalid action at position #{i}: #{action.inspect}"
         end
       end
     end

data/lib/sashite/pmn.rb

@@ -27,12 +27,12 @@ module Sashite
     #
     # @param pmn_array [Array<String>] flat array of PMN elements
     # @return [Sashite::Pmn::Move]
-    # @raise [Sashite::Pmn::InvalidMoveError] if the array or any action is invalid
+    # @raise [Sashite::Pmn::Error::Move] if the array or any action is invalid
     #
     # @example
     #   Sashite::Pmn.parse(["e2","e4","C:P"]).actions.size # => 1
     def self.parse(pmn_array)
-      raise InvalidMoveError, "PMN must be an array, got #{pmn_array.class}" unless pmn_array.is_a?(Array)
+      raise Error::Move, "PMN must be an array, got #{pmn_array.class}" unless pmn_array.is_a?(::Array)
 
       Move.new(*pmn_array)
     end
@@ -46,8 +46,7 @@ module Sashite
     #   Sashite::Pmn.valid?(["e2","e4","C:P"]) # => true
     #   Sashite::Pmn.valid?(["e2"])            # => false
     def self.valid?(pmn_array)
-      return false unless pmn_array.is_a?(Array)
-      return false if pmn_array.empty?
+      return false unless pmn_array.is_a?(::Array)
 
       move = Move.new(*pmn_array)
       move.valid?
@@ -66,7 +65,7 @@ module Sashite
     #   a2 = Sashite::Pmn::Action.new("d7","d5","c:p")
     #   move = Sashite::Pmn.from_actions([a1,a2])
     def self.from_actions(actions)
-      raise ArgumentError, "Actions must be an array" unless actions.is_a?(Array)
+      raise ::ArgumentError, "Actions must be an array" unless actions.is_a?(::Array)
 
       pmn_array = actions.flat_map(&:to_a)
       Move.new(*pmn_array)
@@ -79,9 +78,9 @@ module Sashite
     #
     # @api public
     def self.valid_location?(location)
-      return false unless location.is_a?(String)
+      return false unless location.is_a?(::String)
 
-      Cell.valid?(location) || Hand.reserve?(location)
+      ::Sashite::Cell.valid?(location) || ::Sashite::Hand.reserve?(location)
     end
 
     # Validate a QPI piece string.
@@ -91,9 +90,9 @@ module Sashite
     #
     # @api public
     def self.valid_piece?(piece)
-      return false unless piece.is_a?(String)
+      return false unless piece.is_a?(::String)
 
-      Qpi.valid?(piece)
+      ::Sashite::Qpi.valid?(piece)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pmn
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Cyril Kato