sashite-pmn 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3ebaf0b731c5fa324e1515369a8a98bc3fc4a6a8094d67023728a04c650a963
+  data.tar.gz: 6a4e1ba06a8afd9015ae8dcc89795fa9f28a7b573d4502b13e52d5ed380c3630
+SHA512:
+  metadata.gz: c6624a7cb869903504622c7a7a34f9a5a73a3c63967ed6c7d0ff89e9e4fe8782e806b94742ea3156fd41b54159cc81c5921e59e5cd27c97bf076ca90482148d2
+  data.tar.gz: 7d871f7cdc7509b9c8ec3ea77c0375652423940be53f157e60e4debebc604ed2a10558ecc7d0a9e6e7a892e9a771bbabab0151d2929127de87d81ee2ac5c332f

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License
+
+Copyright (c) 2019-2025 Sashité
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,409 @@
+# Pmn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/pmn.rb?label=Version\&logo=github)](https://github.com/sashite/pmn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pmn.rb/main)
+![Ruby](https://github.com/sashite/pmn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/pmn.rb?label=License\&logo=github)](https://github.com/sashite/pmn.rb/raw/main/LICENSE.md)
+
+> **PMN** (Portable Move Notation) implementation for the Ruby language.
+
+## What is PMN?
+
+PMN (Portable Move Notation) is a rule-agnostic, **array-based** format for describing the mechanical decomposition of moves in abstract strategy board games. PMN breaks down complex movements into sequences of atomic actions, revealing the underlying mechanics while remaining completely independent of specific game rules, validation logic, or gameplay concepts.
+
+This gem implements the [PMN Specification v1.0.0](https://sashite.dev/specs/pmn/1.0.0/), providing a small, functional Ruby interface for working with mechanical move decomposition across any board game system.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-pmn"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-pmn
+```
+
+## Dependencies
+
+PMN builds upon three foundational Sashité specifications:
+
+```ruby
+gem "sashite-cell"  # Multi-dimensional coordinate encoding
+gem "sashite-hand"  # Reserve location notation
+gem "sashite-qpi"   # Qualified Piece Identifier
+```
+
+## Usage
+
+### Basic Operations
+
+```ruby
+require "sashite/pmn"
+
+# Parse PMN arrays into move objects
+move = Sashite::Pmn.parse(["e2", "e4", "C:P"])
+move.valid?                                   # => true
+move.actions                                  # => [#<Sashite::Pmn::Action ...>]
+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?(["e2"])                  # => false (incomplete)
+
+# Create moves programmatically
+move = Sashite::Pmn.from_actions([
+                                   Sashite::Pmn::Action.new("e2", "e4", "C:P")
+                                 ])
+```
+
+### Action Decomposition
+
+```ruby
+# Simple move with explicit piece
+move = Sashite::Pmn.parse(["e2", "e4", "C:P"])
+action = move.actions.first
+action.source                                 # => "e2"
+action.destination                            # => "e4"
+action.piece                                  # => "C:P"
+action.piece_specified?                       # => true
+
+# Move with inferred piece
+move = Sashite::Pmn.parse(%w[e2 e4])
+action = move.actions.first
+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
+
+# Reserve operations
+drop = Sashite::Pmn.parse(["*", "e5", "S:P"]) # Drop from reserve
+capture = Sashite::Pmn.parse(["e4", "*"])     # Capture to reserve (inferred piece)
+```
+
+### Complex Moves
+
+```ruby
+# Multi-action move (castling)
+castling = Sashite::Pmn.parse([
+                                "e1", "g1", "C:K",
+                                "h1", "f1", "C:R"
+                              ])
+castling.compound?                            # => true
+castling.actions.size                         # => 2
+
+# En passant (explicit + inferred variant)
+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
+```
+
+### Move Analysis
+
+```ruby
+move = Sashite::Pmn.parse([
+                            "e1", "g1", "C:K",
+                            "h1", "f1", "C:R"
+                          ])
+
+# Structure analysis
+move.simple?                                  # => false
+move.compound?                                # => true
+move.size                                     # => 2
+move.empty?                                   # => false
+
+# Drop/capture checks
+move.has_drops?                               # => false
+move.has_captures?                            # => false
+move.board_moves.size                         # => 2
+
+# Extract info
+move.sources                                  # => ["e1", "h1"]
+move.destinations                             # => ["g1", "f1"]
+move.pieces                                   # => ["C:K", "C:R"]
+move.has_inferred?                            # => false
+```
+
+### 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
+  puts e.message
+end
+
+begin
+  Sashite::Pmn::Action.new("e2", "e4", "InvalidPiece")
+rescue Sashite::Pmn::InvalidPieceError => e
+  puts e.message
+end
+
+# Parsing a move wraps action-level errors as InvalidMoveError
+begin
+  Sashite::Pmn.parse(["e2"])                  # Incomplete action
+rescue Sashite::Pmn::InvalidMoveError => e
+  puts e.message                              # => "Invalid PMN array length: 1", etc.
+end
+```
+
+## 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.valid_location?(location)` — Check if a location is valid (CELL or `"*"`).
+* `Sashite::Pmn.valid_piece?(piece)` — Check if a piece is valid QPI.
+
+### Move Class
+
+#### 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.
+
+#### 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.
+
+#### 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?
+
+### Action Class
+
+#### Creation
+
+* `Sashite::Pmn::Action.new(source, destination, piece = nil)`
+
+#### Data & Conversion
+
+* `#source`, `#destination`, `#piece`
+* `#to_a` — `["src", "dst"]` or `["src", "dst", "piece"]`
+* `#to_h` — `{ source:, destination:, piece: }` (piece omitted if `nil`)
+
+#### Predicates
+
+* `#inferred?`, `#piece_specified?`, `#piece_valid?`
+* `#from_reserve?`, `#to_reserve?`
+* `#reserve_to_board?` (drop), `#board_to_reserve?` (capture), `#board_to_board?`
+* `#drop?` (alias), `#capture?` (alias), `#board_move?`
+* `#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)
+
+## Format Specification (Summary)
+
+### Structure
+
+PMN moves are flat **arrays** containing action sequences:
+
+```
+[<element-1>, <element-2>, <element-3>, <element-4>, <element-5>, <element-6>, ...]
+```
+
+### Action Format
+
+Each action consists of 2 or 3 consecutive elements:
+
+```
+[<source>, <destination>, <piece>?]
+```
+
+* **Source**: CELL coordinate or `"*"` (reserve)
+* **Destination**: CELL coordinate or `"*"` (reserve)
+* **Piece**: QPI string (optional; may be inferred)
+
+### Array Length Rules
+
+* Minimum: 2 elements (one action with inferred piece)
+* Valid lengths: multiple of 3, **or** multiple of 3 plus 2
+
+### Pass & Same-Location Actions
+
+Actions where **source == destination** are allowed, enabling:
+
+* Pass moves (turn-only or rule-driven)
+* In-place transformations (e.g., promotions specified with QPI)
+
+## Game Examples
+
+### Western Chess
+
+```ruby
+# Pawn move
+pawn_move = Sashite::Pmn.parse(["e2", "e4", "C:P"])
+
+# Castling kingside
+castling = Sashite::Pmn.parse([
+                                "e1", "g1", "C:K",
+                                "h1", "f1", "C:R"
+                              ])
+
+# En passant
+en_passant = Sashite::Pmn.parse([
+                                  "e5", "f6", "C:P",
+                                  "f5", "*", "c:p"
+                                ])
+
+# Promotion
+promotion = Sashite::Pmn.parse(["e7", "e8", "C:Q"])
+```
+
+### Japanese Shōgi
+
+```ruby
+# Drop piece from hand
+drop = Sashite::Pmn.parse(["*", "e5", "S:P"])
+
+# Capture and convert
+capture = Sashite::Pmn.parse([
+                               "a1", "*", "S:L",
+                               "b2", "a1", "S:S"
+                             ])
+
+# Promotion
+promotion = Sashite::Pmn.parse(["h8", "i8", "S:+S"])
+```
+
+### Chinese Xiangqi
+
+```ruby
+# General move
+general_move = Sashite::Pmn.parse(["e1", "e2", "X:G"])
+
+# Cannon capture (jumping)
+cannon_capture = Sashite::Pmn.parse([
+                                      "b3", "*", "x:s",
+                                      "b1", "b9", "X:C"
+                                    ])
+```
+
+## Advanced Usage
+
+### Move Composition
+
+```ruby
+actions = []
+actions << Sashite::Pmn::Action.new("e2", "e4", "C:P")
+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"]
+```
+
+### Integration with Game Engines
+
+```ruby
+class GameEngine
+  def execute_move(pmn_array)
+    move = Sashite::Pmn.parse(pmn_array)
+
+    move.actions.each do |action|
+      if action.from_reserve?
+        place_piece(action.destination, action.piece)
+      elsif action.to_reserve?
+        capture_piece(action.source)
+      else
+        move_piece(action.source, action.destination, action.piece)
+      end
+    end
+  end
+
+  # ...
+end
+```
+
+## Design Properties
+
+* **Rule-agnostic**: Independent of specific game mechanics
+* **Mechanical decomposition**: Breaks complex moves into atomic actions
+* **Array-based**: Simple, interoperable structure
+* **Sequential execution**: Actions execute in array order
+* **Piece inference**: Optional piece specification when context is clear
+* **Universal applicability**: Works across board game systems
+* **Functional design**: Immutable data structures
+* **Dependency integration**: CELL, HAND, and QPI specs
+
+## Mechanical Semantics (Recap)
+
+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
+
+3. **Piece transformation**: Final state (specified or inferred)
+
+4. **Atomic commitment**: Each action applies atomically
+
+## License
+
+Available as open source under the [MIT License](https://github.com/sashite/pmn.rb/raw/main/LICENSE.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/sashite/pmn.rb](https://github.com/sashite/pmn.rb).
+
+## See Also
+
+* [PMN Specification v1.0.0](https://sashite.dev/specs/pmn/1.0.0/)
+* [PMN Examples](https://sashite.dev/specs/pmn/1.0.0/examples/)
+* [CELL Specification](https://sashite.dev/specs/cell/)
+* [HAND Specification](https://sashite.dev/specs/hand/)
+* [QPI Specification](https://sashite.dev/specs/qpi/)
+
+## About
+
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/pmn/action.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "sashite/cell"
+require "sashite/hand"
+require "sashite/qpi"
+require_relative "error"
+
+module Sashite
+  module Pmn
+    # Represents an atomic action within a PMN move.
+    #
+    # Each action encodes a single transformation:
+    #   [source, destination]            # inferred piece
+    #   [source, destination, piece]     # explicit QPI piece
+    #
+    # Locations are either CELL coordinates or HAND ("*").
+    # Actions where source == destination are allowed (pass / in-place).
+    class Action
+      # @return [String] the source location (CELL or "*")
+      attr_reader :source
+
+      # @return [String] the destination location (CELL or "*")
+      attr_reader :destination
+
+      # @return [String, nil] the piece in QPI format, or nil if inferred
+      attr_reader :piece
+
+      # Create an immutable action.
+      #
+      # @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
+      def initialize(source, destination, piece = nil)
+        validate_source!(source)
+        validate_destination!(destination)
+        validate_piece!(piece) if piece
+
+        @source = source.freeze
+        @destination = destination.freeze
+        @piece = piece&.freeze
+
+        freeze
+      end
+
+      # ---------- Predicates -------------------------------------------------
+
+      # @return [Boolean] true if piece is not explicitly specified
+      def inferred?
+        piece.nil?
+      end
+
+      # @return [Boolean] true if a piece string is explicitly specified
+      def piece_specified?
+        !piece.nil?
+      end
+
+      # @return [Boolean] true if a specified piece is valid QPI (false if none)
+      def piece_valid?
+        return false if piece.nil?
+
+        Qpi.valid?(piece)
+      end
+
+      # @return [Boolean] true if source is HAND ("*")
+      def from_reserve?
+        Hand.reserve?(source)
+      end
+
+      # @return [Boolean] true if destination is HAND ("*")
+      def to_reserve?
+        Hand.reserve?(destination)
+      end
+
+      # @return [Boolean] true if both endpoints are board locations
+      def board_to_board?
+        Cell.valid?(source) && Cell.valid?(destination)
+      end
+
+      # @return [Boolean] true if the action places from reserve to board
+      def drop?
+        from_reserve? && Cell.valid?(destination)
+      end
+
+      # @return [Boolean] true if the action takes from board to reserve
+      def capture?
+        Cell.valid?(source) && to_reserve?
+      end
+
+      # @return [Boolean] true when neither drop nor capture
+      def board_move?
+        !drop? && !capture?
+      end
+
+      # ---------- Conversions -----------------------------------------------
+
+      # @return [Array<String>] 2 elems if inferred, 3 if explicit
+      def to_a
+        inferred? ? [source, destination] : [source, destination, piece]
+      end
+
+      # @return [Hash] { source:, destination:, piece: } (piece omitted if nil)
+      def to_h
+        { source: source, destination: destination, piece: piece }.compact
+      end
+
+      # ---------- Validation & Equality -------------------------------------
+
+      # @return [Boolean] true if all components are valid
+      def valid?
+        valid_location?(source) &&
+          valid_location?(destination) &&
+          (piece.nil? || Qpi.valid?(piece))
+      end
+
+      # @param other [Object]
+      # @return [Boolean] equality by {source, destination, piece}
+      def ==(other)
+        return false unless other.is_a?(Action)
+
+        source == other.source &&
+          destination == other.destination &&
+          piece == other.piece
+      end
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        [source, destination, piece].hash
+      end
+
+      # @return [String]
+      def inspect
+        attrs = ["source=#{source.inspect}", "destination=#{destination.inspect}"]
+        attrs << "piece=#{piece.inspect}" if piece
+        "#<#{self.class.name} #{attrs.join(' ')}>"
+      end
+
+      # ---------- Factories --------------------------------------------------
+
+      # Build from a hash with keys :source, :destination, optional :piece.
+      #
+      # @param hash [Hash]
+      # @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)
+
+        new(hash[:source], hash[:destination], hash[:piece])
+      end
+
+      private
+
+      # ---------- Internal validation helpers -------------------------------
+
+      # @param src [String]
+      # @raise [InvalidLocationError]
+      def validate_source!(src)
+        return if valid_location?(src)
+
+        raise InvalidLocationError, "Invalid source location: #{src.inspect}"
+      end
+
+      # @param dst [String]
+      # @raise [InvalidLocationError]
+      def validate_destination!(dst)
+        return if valid_location?(dst)
+
+        raise InvalidLocationError, "Invalid destination location: #{dst.inspect}"
+      end
+
+      # @param qpi [String, nil]
+      # @raise [InvalidPieceError]
+      def validate_piece!(qpi)
+        return if qpi.nil?
+        return if Qpi.valid?(qpi)
+
+        raise InvalidPieceError, "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)
+      end
+    end
+  end
+end

data/lib/sashite/pmn/error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pmn
+    # Base class for all PMN-related errors
+    class Error < StandardError; 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
+    class InvalidActionError < Error; 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
+  end
+end

data/lib/sashite/pmn/move.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "action"
+require_relative "error"
+
+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:
+    #   [source, destination]            # inferred piece
+    #   [source, destination, piece]     # explicit QPI piece
+    #
+    # Valid lengths: multiple of 3 OR multiple of 3 + 2 (minimum 2).
+    class Move
+      # @return [Array<Action>] ordered sequence of actions
+      attr_reader :actions
+
+      # @return [Array<String>] original PMN elements (frozen)
+      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
+      #
+      # @example
+      #   Move.new("e2","e4","C:P")
+      #   Move.new("e2","e4")
+      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,
+                'PMN must be passed as individual arguments, e.g. Move.new("e2","e4","C:P")'
+        end
+
+        validate_array!(pmn_elements)
+        @pmn_array = pmn_elements.dup.freeze
+        @actions   = parse_actions(@pmn_array).freeze
+        validate_actions!
+        freeze
+      end
+
+      # @return [Boolean] true if PMN length is valid and all actions are valid
+      def valid?
+        valid_length? && actions.all?(&:valid?)
+      rescue StandardError
+        false
+      end
+
+      # Shape / structure -----------------------------------------------------
+
+      # @return [Boolean] exactly one action?
+      def simple?
+        actions.size == 1
+      end
+
+      # @return [Boolean] multiple actions?
+      def compound?
+        actions.size > 1
+      end
+
+      # @return [Action, nil]
+      def first_action
+        actions.first
+      end
+
+      # @return [Action, nil]
+      def last_action
+        actions.last
+      end
+
+      # @return [Integer] number of actions
+      def size
+        actions.size
+      end
+      alias length size
+
+      # @return [Boolean] true if no actions
+      def empty?
+        actions.empty?
+      end
+
+      # Content helpers -------------------------------------------------------
+
+      # @return [Boolean] any drop?
+      def has_drops?
+        actions.any?(&:drop?)
+      end
+
+      # @return [Boolean] any capture?
+      def has_captures?
+        actions.any?(&:capture?)
+      end
+
+      # @return [Array<Action>] only board-to-board actions
+      def board_moves
+        actions.select(&:board_to_board?)
+      end
+
+      # @return [Array<String>] unique sources
+      def sources
+        actions.map(&:source).uniq
+      end
+
+      # @return [Array<String>] unique destinations
+      def destinations
+        actions.map(&:destination).uniq
+      end
+
+      # @return [Array<String>] unique specified pieces (excludes inferred)
+      def pieces
+        actions.filter_map(&:piece).uniq
+      end
+
+      # @return [Boolean] true if any action has inferred piece
+      def has_inferred?
+        actions.any?(&:inferred?)
+      end
+
+      # Conversion ------------------------------------------------------------
+
+      # @return [Array<String>] copy of original PMN elements
+      def to_a
+        pmn_array.dup
+      end
+
+      # Equality / hashing / debug -------------------------------------------
+
+      # @param other [Object]
+      # @return [Boolean] equality by original PMN elements
+      def ==(other)
+        return false unless other.is_a?(Move)
+
+        pmn_array == other.pmn_array
+      end
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        pmn_array.hash
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} actions=#{actions.size} pmn=#{pmn_array.inspect}>"
+      end
+
+      # Functional composition -----------------------------------------------
+
+      # @param actions_to_add [Array<Action>] actions to append
+      # @return [Move] new Move with appended actions
+      def with_actions(actions_to_add)
+        combined = pmn_array + actions_to_add.flat_map(&:to_a)
+        self.class.new(*combined)
+      end
+
+      # Build a move from Action objects.
+      #
+      # @param actions [Array<Action>]
+      # @return [Move]
+      def self.from_actions(actions)
+        pmn = actions.flat_map(&:to_a)
+        new(*pmn)
+      end
+
+      private
+
+      # 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 InvalidMoveError, "All PMN elements must be strings" unless array.all?(String)
+
+        return if valid_length?(array)
+
+        raise InvalidMoveError, "Invalid PMN array length: #{array.size}"
+      end
+
+      # Valid lengths: (size % 3 == 0) OR (size % 3 == 2), minimum 2.
+      def valid_length?(array = pmn_array)
+        return false if array.size < 2
+
+        r = array.size % 3
+        [0, 2].include?(r)
+      end
+
+      # Parsing ---------------------------------------------------------------
+
+      def parse_actions(array)
+        actions = []
+        index = 0
+
+        while index < array.size
+          remaining = array.size - index
+
+          if remaining == 2
+            actions << Action.new(array[index], array[index + 1])
+            index += 2
+          elsif remaining >= 3
+            actions << Action.new(array[index], array[index + 1], array[index + 2])
+            index += 3
+          else
+            raise InvalidMoveError, "Invalid action group at index #{index}"
+          end
+        end
+
+        actions
+      rescue InvalidActionError => e
+        # Normalize action-level errors as move-level errors during parsing
+        raise InvalidMoveError, "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}"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/pmn.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "sashite/cell"
+require "sashite/hand"
+require "sashite/qpi"
+
+require_relative "pmn/action"
+require_relative "pmn/move"
+require_relative "pmn/error"
+
+module Sashite
+  # PMN (Portable Move Notation) implementation for Ruby
+  #
+  # PMN is an array-based, rule-agnostic format that decomposes a move into a
+  # sequence of atomic actions. Each action is 2 or 3 elements:
+  #   [source, destination]            # inferred piece
+  #   [source, destination, piece]     # explicit piece (QPI)
+  #
+  # Valid PMN arrays have length:
+  #   - multiple of 3, or
+  #   - multiple of 3 + 2
+  # with a minimum of 2.
+  #
+  # See specs: https://sashite.dev/specs/pmn/1.0.0/
+  module Pmn
+    # Parse a PMN array into a Move object.
+    #
+    # @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
+    #
+    # @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)
+
+      Move.new(*pmn_array)
+    end
+
+    # Check if an array is valid PMN notation (non-raising).
+    #
+    # @param pmn_array [Array]
+    # @return [Boolean] true if valid, false otherwise
+    #
+    # @example
+    #   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?
+
+      move = Move.new(*pmn_array)
+      move.valid?
+    rescue Error
+      false
+    end
+
+    # Create a Move from Action objects.
+    #
+    # @param actions [Array<Sashite::Pmn::Action>]
+    # @return [Sashite::Pmn::Move]
+    # @raise [ArgumentError] if actions is not an Array
+    #
+    # @example
+    #   a1 = Sashite::Pmn::Action.new("e2","e4","C:P")
+    #   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)
+
+      pmn_array = actions.flat_map(&:to_a)
+      Move.new(*pmn_array)
+    end
+
+    # Validate a location string (CELL or HAND "*").
+    #
+    # @param location [String]
+    # @return [Boolean]
+    #
+    # @api public
+    def self.valid_location?(location)
+      return false unless location.is_a?(String)
+
+      Cell.valid?(location) || Hand.reserve?(location)
+    end
+
+    # Validate a QPI piece string.
+    #
+    # @param piece [String]
+    # @return [Boolean]
+    #
+    # @api public
+    def self.valid_piece?(piece)
+      return false unless piece.is_a?(String)
+
+      Qpi.valid?(piece)
+    end
+  end
+end

data/lib/sashite-pmn.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/pmn"
+
+# Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Sashité Protocol specifications.
+#
+# @see https://sashite.dev/protocol/ Sashité Protocol
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
+module Sashite
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: sashite-pmn
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sashite-cell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sashite-hand
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sashite-qpi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  PMN (Portable Move Notation) provides a rule-agnostic, JSON-based format for describing
+  the mechanical decomposition of moves in abstract strategy board games. This gem implements
+  the PMN Specification v1.0.0 with a functional Ruby interface, breaking down complex movements
+  into sequences of atomic actions while remaining completely independent of specific game rules.
+  PMN reveals the underlying mechanics of any board game move through sequential action
+  decomposition, supporting both explicit and inferred piece specifications. Built on CELL
+  (coordinate encoding), HAND (reserve notation), and QPI (piece identification) specifications,
+  it enables universal move representation across chess variants, shōgi, xiangqi, and any
+  abstract strategy game. Perfect for game engines, move validators, and board game analysis tools.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-pmn.rb
+- lib/sashite/pmn.rb
+- lib/sashite/pmn/action.rb
+- lib/sashite/pmn/error.rb
+- lib/sashite/pmn/move.rb
+homepage: https://github.com/sashite/pmn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/pmn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/pmn.rb/main
+  homepage_uri: https://github.com/sashite/pmn.rb
+  source_code_uri: https://github.com/sashite/pmn.rb
+  specification_uri: https://sashite.dev/specs/pmn/1.0.0/
+  wiki_uri: https://sashite.dev/specs/pmn/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: PMN (Portable Move Notation) implementation for Ruby with functional decomposition
+test_files: []