sashite-pin 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e469a5469a29de49338f5066b5b5743860459709ab2e771209d1c55ab7e7ff0d
-  data.tar.gz: 680f65379ee7ea0ead2238ed646a29ee54d673a80de7f0c54f1c56a11cf8f98f
+  metadata.gz: 5f278c657907ec277b42f6c5f7b22b5df56d6cb57bd6438eeda33c3c847294f9
+  data.tar.gz: 96e8c58b731ea334214aa5803e27a7fdd629f17df38b1eb55ddf8654397bd5f5
 SHA512:
-  metadata.gz: 1a4b4ce38433cdf1cd9a26baaba13fa8e48ff21676976287422ac917d3a41bc67e7eb688bf347a94cefb294542e98fa7d2bd292f923b7a8c6b66d73edfaebdd2
-  data.tar.gz: 5da68a02154b85ab6a9b1070954f14be0a4f79e11e07c54448c0aae40772e4664c2b3368067a44c8fdef5a43b122a3c868e2cc8c6df5ed52f46afa2a2b65f021
+  metadata.gz: d451a383989a72da646522113f4ece370b88d57edc940c932cc238311dde1d3f52e477858a1dabba6ff7ee2b9d1a2ee561c9827230ecc3986c421ded53814634
+  data.tar.gz: 74cf7b9dd82202b8999951d42ae44bac1cd84cc286819268732070cc8b0bde769984de64a374bcd72ab1e5eaa803dd84e452e85f657163d5bd8d8512c978318b

data/README.md

@@ -32,19 +32,28 @@ gem install sashite-pin
 require "sashite/pin"
 
 # Parse PIN strings into identifier objects
-identifier = Sashite::Pin.parse("K")          # => #<Pin::Identifier type=:K side=:first state=:normal>
+identifier = Sashite::Pin.parse("K")          # => #<Pin::Identifier type=:K side=:first state=:normal terminal=false>
 identifier.to_s                               # => "K"
 identifier.type                               # => :K
 identifier.side                               # => :first
 identifier.state                              # => :normal
+identifier.terminal?                          # => false
+
+# Parse terminal pieces (e.g., kings in chess)
+terminal_king = Sashite::Pin.parse("K^")      # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
+terminal_king.to_s                            # => "K^"
+terminal_king.terminal?                       # => true
 
 # Create identifiers directly
-identifier = Sashite::Pin.identifier(:K, :first, :normal)    # => #<Pin::Identifier type=:K side=:first state=:normal>
+identifier = Sashite::Pin.identifier(:K, :first, :normal)                    # => #<Pin::Identifier type=:K side=:first state=:normal>
+terminal_king = Sashite::Pin.identifier(:K, :first, :normal, terminal: true) # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
 identifier = Sashite::Pin::Identifier.new(:R, :second, :enhanced)  # => #<Pin::Identifier type=:R side=:second state=:enhanced>
 
 # Validate PIN strings
 Sashite::Pin.valid?("K")                 # => true
 Sashite::Pin.valid?("+R")                # => true
+Sashite::Pin.valid?("K^")                # => true
+Sashite::Pin.valid?("+K^")               # => true
 Sashite::Pin.valid?("invalid")           # => false
 
 # State manipulation (returns new immutable instances)
@@ -53,6 +62,11 @@ enhanced.to_s                                 # => "+K"
 diminished = identifier.diminish              # => #<Pin::Identifier type=:K side=:first state=:diminished>
 diminished.to_s                               # => "-K"
 
+# Terminal marker manipulation
+normal_king = Sashite::Pin.parse("K")
+terminal_king = normal_king.mark_terminal     # => "K^"
+back_to_normal = terminal_king.unmark_terminal # => "K"
+
 # Side manipulation
 flipped = identifier.flip                     # => #<Pin::Identifier type=:K side=:second state=:normal>
 flipped.to_s                                  # => "k"
@@ -74,6 +88,7 @@ flipped.second_player?                        # => true
 identifier.letter                             # => "K"
 enhanced.prefix                               # => "+"
 identifier.prefix                             # => ""
+terminal_king.suffix                          # => "^"
 
 # Type and side comparison
 king1 = Sashite::Pin.parse("K")
@@ -87,6 +102,10 @@ king1.same_type?(queen)                       # => false (different types)
 # Functional transformations can be chained
 pawn = Sashite::Pin.parse("P")
 enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted pawn)
+
+# Transformations preserve terminal status
+terminal_piece = Sashite::Pin.parse("K^")
+enhanced_terminal = terminal_piece.enhance    # => "+K^"
 ```
 
 ## Format Specification
@@ -94,7 +113,7 @@ enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted
 ### Structure
 
 ```
-[<state>]<letter>
+[<state-modifier>]<letter>[<terminal-marker>]
 ```
 
 ### Components
@@ -103,23 +122,30 @@ enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted
 
   * Uppercase: First player pieces
   * Lowercase: Second player pieces
-* **State** (optional prefix):
+* **State Modifier** (optional prefix):
 
   * `+`: Enhanced state (promoted, upgraded, empowered)
   * `-`: Diminished state (weakened, restricted, temporary)
   * No prefix: Normal state
+* **Terminal Marker** (optional suffix):
+
+  * `^`: Terminal piece (critical to match continuation)
+  * No suffix: Non-terminal piece
 
 ### Regular Expression
 
 ```ruby
-/\A[-+]?[A-Za-z]\z/
+/\A[-+]?[A-Za-z]\^?\z/
 ```
 
 ### Examples
 
 * `K` - First player king (normal state)
+* `K^` - First player king (normal state, terminal)
 * `k` - Second player king (normal state)
+* `k^` - Second player king (normal state, terminal)
 * `+R` - First player rook (enhanced state)
+* `+R^` - First player rook (enhanced state, terminal)
 * `-p` - Second player pawn (diminished state)
 
 ## API Reference
@@ -128,13 +154,13 @@ enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted
 
 * `Sashite::Pin.valid?(pin_string)` - Check if string is valid PIN notation
 * `Sashite::Pin.parse(pin_string)` - Parse PIN string into Identifier object
-* `Sashite::Pin.identifier(type, side, state = :normal)` - Create identifier instance directly
+* `Sashite::Pin.identifier(type, side, state = :normal, terminal: false)` - Create identifier instance directly
 
 ### Identifier Class
 
 #### Creation and Parsing
 
-* `Sashite::Pin::Identifier.new(type, side, state = :normal)` - Create identifier instance
+* `Sashite::Pin::Identifier.new(type, side, state = :normal, terminal: false)` - Create identifier instance
 * `Sashite::Pin::Identifier.parse(pin_string)` - Parse PIN string (same as module method)
 * `Sashite::Pin::Identifier.valid?(pin_string)` - Validate PIN string (class method)
 
@@ -143,8 +169,10 @@ enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted
 * `#type` - Get piece type (symbol \:A to \:Z, always uppercase)
 * `#side` - Get player side (\:first or \:second)
 * `#state` - Get state (\:normal, \:enhanced, or \:diminished)
+* `#terminal` - Get terminal status (Boolean)
 * `#letter` - Get letter representation (string, case determined by side)
 * `#prefix` - Get state prefix (string: "+", "-", or "")
+* `#suffix` - Get terminal marker (string: "^" or "")
 * `#to_s` - Convert to PIN string representation
 
 #### Type and Case Handling
@@ -174,6 +202,10 @@ identifier2.letter  # => "k" (lowercase display)
 * `#first_player?` - Check if first player identifier
 * `#second_player?` - Check if second player identifier
 
+#### Terminal Queries
+
+* `#terminal?` - Check if terminal piece
+
 #### State Transformations (immutable - return new instances)
 
 * `#enhance` - Create enhanced version
@@ -189,16 +221,24 @@ identifier2.letter  # => "k" (lowercase display)
 * `#with_side(new_side)` - Create identifier with different side
 * `#with_state(new_state)` - Create identifier with different state
 
+#### Terminal Transformations (immutable - return new instances)
+
+* `#mark_terminal` - Create terminal version
+* `#unmark_terminal` - Create non-terminal version
+* `#with_terminal(boolean)` - Create identifier with specified terminal status
+
 #### Comparison Methods
 
 * `#same_type?(other)` - Check if same piece type
 * `#same_side?(other)` - Check if same side
 * `#same_state?(other)` - Check if same state
+* `#same_terminal?(other)` - Check if same terminal status
 * `#==(other)` - Full equality comparison
 
 ### Constants
 
 * `Sashite::Pin::Identifier::PIN_PATTERN` - Regular expression for PIN validation (internal use)
+* `Sashite::Pin::Identifier::TERMINAL_MARKER` - Terminal marker character (`"^"`)
 
 ## Advanced Usage
 
@@ -229,7 +269,7 @@ white_king.same_side?(black_king)  # => false
 ### Immutable Transformations
 ```ruby
 # All transformations return new instances
-original = Sashite::Pin.piece(:K, :first, :normal)
+original = Sashite::Pin.identifier(:K, :first, :normal)
 enhanced = original.enhance
 diminished = original.diminish
 
@@ -241,6 +281,11 @@ puts diminished.to_s  # => "-K"
 # Transformations can be chained
 result = original.flip.enhance.with_type(:Q)
 puts result.to_s      # => "+q"
+
+# Terminal status is preserved through transformations
+terminal_king = Sashite::Pin.parse("K^")
+enhanced_terminal = terminal_king.enhance
+puts enhanced_terminal.to_s  # => "+K^"
 ```
 
 ### Game State Management
@@ -274,13 +319,17 @@ class GameBoard
   def promoted_pieces
     @pieces.select { |_, piece| piece.enhanced? }
   end
+
+  def terminal_pieces
+    @pieces.select { |_, piece| piece.terminal? }
+  end
 end
 
 # Usage
 board = GameBoard.new
-board.place("e1", Sashite::Pin.piece(:K, :first, :normal))
-board.place("e8", Sashite::Pin.piece(:K, :second, :normal))
-board.place("a7", Sashite::Pin.piece(:P, :first, :normal))
+board.place("e1", Sashite::Pin.identifier(:K, :first, :normal, terminal: true))
+board.place("e8", Sashite::Pin.identifier(:K, :second, :normal, terminal: true))
+board.place("a7", Sashite::Pin.identifier(:P, :first, :normal))
 
 # Promote pawn
 board.promote("a7", :Q)
@@ -299,14 +348,16 @@ def analyze_pieces(pins)
     by_type: pieces.group_by(&:type),
     by_state: pieces.group_by(&:state),
     promoted: pieces.count(&:enhanced?),
-    weakened: pieces.count(&:diminished?)
+    weakened: pieces.count(&:diminished?),
+    terminal: pieces.count(&:terminal?)
   }
 end
 
-pins = %w[K Q +R B N P k q r +b n -p]
+pins = %w[K^ Q +R B N P k^ q r +b n -p]
 analysis = analyze_pieces(pins)
 puts analysis[:by_side][:first].size  # => 6
 puts analysis[:promoted]              # => 2
+puts analysis[:terminal]              # => 2
 ```
 
 ### Move Validation Example
@@ -325,7 +376,7 @@ def can_promote?(piece, target_rank)
   end
 end
 
-pawn = Sashite::Pin.piece(:P, :first, :normal)
+pawn = Sashite::Pin.identifier(:P, :first, :normal)
 puts can_promote?(pawn, 8)          # => true
 
 promoted_pawn = pawn.enhance
@@ -338,9 +389,10 @@ Following the [Game Protocol](https://sashite.dev/game-protocol/):
 
 | Protocol Attribute | PIN Encoding | Examples | Notes |
 |-------------------|--------------|----------|-------|
-| **Type** | ASCII letter choice | `K`/`k` = King, `P`/`p` = Pawn | Type is always stored as uppercase symbol (`:K`, `:P`) |
-| **Side** | Letter case in display | `K` = First player, `k` = Second player | Case is determined by side during rendering |
-| **State** | Optional prefix | `+K` = Enhanced, `-K` = Diminished, `K` = Normal | |
+| **Piece Name** | ASCII letter choice | `K`/`k` = King, `P`/`p` = Pawn | Type is always stored as uppercase symbol (`:K`, `:P`) |
+| **Piece Side** | Letter case in display | `K` = First player, `k` = Second player | Case is determined by side during rendering |
+| **Piece State** | Optional prefix | `+K` = Enhanced, `-K` = Diminished, `K` = Normal | |
+| **Terminal Status** | Optional suffix | `K^` = Terminal, `K` = Non-terminal | Identifies pieces critical to match continuation |
 
 **Type Convention**: All piece types are internally represented as uppercase symbols (`:A` to `:Z`). The display case is determined by the `side` attribute: first player pieces display as uppercase, second player pieces as lowercase.
 
@@ -352,9 +404,10 @@ Following the [Game Protocol](https://sashite.dev/game-protocol/):
 
 * **ASCII Compatible**: Maximum portability across systems
 * **Rule-Agnostic**: Independent of specific game mechanics
-* **Compact Format**: 1-2 characters per piece
+* **Compact Format**: 1-3 characters per piece
 * **Visual Distinction**: Clear player differentiation through case
 * **Type Normalization**: Consistent uppercase type representation internally
+* **Terminal Marker**: Explicit identification of pieces critical to match continuation
 * **Protocol Compliant**: Direct implementation of Sashité piece attributes
 * **Immutable**: All piece instances are frozen and transformations return new objects
 * **Functional**: Pure functions with no side effects
@@ -375,6 +428,15 @@ This design ensures:
 - Clear separation between piece identity (type) and ownership (side)
 - Predictable behavior when comparing pieces of the same type
 
+### Terminal Marker Convention
+
+The terminal marker (`^`) identifies pieces whose presence, condition, or capacity for action determines whether the match can continue:
+
+1. **Suffix Position**: Always appears as the last character (`K^`, `+K^`, `-k^`)
+2. **Preservation**: Terminal status is preserved through all transformations
+3. **Equality**: Two pieces are equal only if they have the same terminal status
+4. **Independence**: Terminal status is independent of state (normal/enhanced/diminished)
+
 ### Example Flow
 
 ```ruby
@@ -394,6 +456,7 @@ This ensures that `parse(pin).to_s == pin` for all valid PIN strings while maint
 - **Maximum 26 piece types** per game system (one per ASCII letter)
 - **Exactly 2 players** (uppercase/lowercase distinction)
 - **3 state levels** (enhanced, normal, diminished)
+- **2 terminal levels** (terminal, non-terminal)
 
 ## Related Specifications
 

data/lib/sashite/pin/identifier.rb

@@ -17,13 +17,16 @@ module Sashite
     # This follows the Game Protocol's piece model with Type, Side, and State attributes.
     class Identifier
       # PIN validation pattern matching the specification
-      PIN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])\z/
+      PIN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<terminal>\^)?\z/
 
       # Valid state modifiers
       ENHANCED_PREFIX = "+"
       DIMINISHED_PREFIX = "-"
       NORMAL_PREFIX = ""
 
+      # Terminal marker
+      TERMINAL_MARKER = "^"
+
       # State constants
       ENHANCED_STATE = :enhanced
       DIMINISHED_STATE = :diminished
@@ -57,13 +60,17 @@ module Sashite
       # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
       attr_reader :state
 
+      # @return [Boolean] whether the piece is a terminal piece
+      attr_reader :terminal
+
       # Create a new identifier instance
       #
       # @param type [Symbol] piece type (:A to :Z)
       # @param side [Symbol] player side (:first or :second)
       # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+      # @param terminal [Boolean] whether the piece is a terminal piece
       # @raise [ArgumentError] if parameters are invalid
-      def initialize(type, side, state = NORMAL_STATE)
+      def initialize(type, side, state = NORMAL_STATE, terminal: false)
         self.class.validate_type(type)
         self.class.validate_side(side)
         self.class.validate_state(state)
@@ -71,6 +78,7 @@ module Sashite
         @type = type
         @side = side
         @state = state
+        @terminal = !!terminal
 
         freeze
       end
@@ -81,9 +89,11 @@ module Sashite
       # @return [Identifier] new identifier instance
       # @raise [ArgumentError] if the PIN string is invalid
       # @example
-      #   Pin::Identifier.parse("k")     # => #<Pin::Identifier type=:K side=:second state=:normal>
-      #   Pin::Identifier.parse("+R")    # => #<Pin::Identifier type=:R side=:first state=:enhanced>
-      #   Pin::Identifier.parse("-p")    # => #<Pin::Identifier type=:P side=:second state=:diminished>
+      #   Pin::Identifier.parse("k")     # => #<Pin::Identifier type=:K side=:second state=:normal terminal=false>
+      #   Pin::Identifier.parse("+R")    # => #<Pin::Identifier type=:R side=:first state=:enhanced terminal=false>
+      #   Pin::Identifier.parse("-p")    # => #<Pin::Identifier type=:P side=:second state=:diminished terminal=false>
+      #   Pin::Identifier.parse("K^")    # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
+      #   Pin::Identifier.parse("+K^")   # => #<Pin::Identifier type=:K side=:first state=:enhanced terminal=true>
       def self.parse(pin_string)
         string_value = String(pin_string)
         matches = match_pattern(string_value)
@@ -91,6 +101,7 @@ module Sashite
         letter = matches[:letter]
         enhanced = matches[:prefix] == ENHANCED_PREFIX
         diminished = matches[:prefix] == DIMINISHED_PREFIX
+        is_terminal = matches[:terminal] == TERMINAL_MARKER
 
         type = letter.upcase.to_sym
         side = letter == letter.upcase ? FIRST_PLAYER : SECOND_PLAYER
@@ -102,7 +113,7 @@ module Sashite
                   NORMAL_STATE
                 end
 
-        new(type, side, state)
+        new(type, side, state, terminal: is_terminal)
       end
 
       # Check if a string is a valid PIN notation
@@ -127,8 +138,10 @@ module Sashite
       # @return [String] PIN notation string
       # @example
       #   identifier.to_s  # => "+R"
+      #   terminal_king.to_s  # => "K^"
+      #   enhanced_terminal.to_s  # => "+K^"
       def to_s
-        "#{prefix}#{letter}"
+        "#{prefix}#{letter}#{suffix}"
       end
 
       # Get the letter representation
@@ -149,13 +162,20 @@ module Sashite
         end
       end
 
+      # Get the suffix representation
+      #
+      # @return [String] suffix representing terminal status
+      def suffix
+        terminal? ? TERMINAL_MARKER : ""
+      end
+
       # Create a new identifier with enhanced state
       #
       # @return [Identifier] new identifier instance with enhanced state
       def enhance
         return self if enhanced?
 
-        self.class.new(type, side, ENHANCED_STATE)
+        self.class.new(type, side, ENHANCED_STATE, terminal: terminal)
       end
 
       # Create a new identifier without enhanced state
@@ -164,7 +184,7 @@ module Sashite
       def unenhance
         return self unless enhanced?
 
-        self.class.new(type, side, NORMAL_STATE)
+        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
       end
 
       # Create a new identifier with diminished state
@@ -173,7 +193,7 @@ module Sashite
       def diminish
         return self if diminished?
 
-        self.class.new(type, side, DIMINISHED_STATE)
+        self.class.new(type, side, DIMINISHED_STATE, terminal: terminal)
       end
 
       # Create a new identifier without diminished state
@@ -182,7 +202,7 @@ module Sashite
       def undiminish
         return self unless diminished?
 
-        self.class.new(type, side, NORMAL_STATE)
+        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
       end
 
       # Create a new identifier with normal state (no modifiers)
@@ -191,14 +211,32 @@ module Sashite
       def normalize
         return self if normal?
 
-        self.class.new(type, side, NORMAL_STATE)
+        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
+      end
+
+      # Create a new identifier marked as terminal
+      #
+      # @return [Identifier] new identifier instance marked as terminal
+      def mark_terminal
+        return self if terminal?
+
+        self.class.new(type, side, state, terminal: true)
+      end
+
+      # Create a new identifier unmarked as terminal
+      #
+      # @return [Identifier] new identifier instance unmarked as terminal
+      def unmark_terminal
+        return self unless terminal?
+
+        self.class.new(type, side, state, terminal: false)
       end
 
       # Create a new identifier with opposite side
       #
       # @return [Identifier] new identifier instance with opposite side
       def flip
-        self.class.new(type, opposite_side, state)
+        self.class.new(type, opposite_side, state, terminal: terminal)
       end
 
       # Create a new identifier with a different type
@@ -209,7 +247,7 @@ module Sashite
         self.class.validate_type(new_type)
         return self if type == new_type
 
-        self.class.new(new_type, side, state)
+        self.class.new(new_type, side, state, terminal: terminal)
       end
 
       # Create a new identifier with a different side
@@ -220,7 +258,7 @@ module Sashite
         self.class.validate_side(new_side)
         return self if side == new_side
 
-        self.class.new(type, new_side, state)
+        self.class.new(type, new_side, state, terminal: terminal)
       end
 
       # Create a new identifier with a different state
@@ -231,7 +269,18 @@ module Sashite
         self.class.validate_state(new_state)
         return self if state == new_state
 
-        self.class.new(type, side, new_state)
+        self.class.new(type, side, new_state, terminal: terminal)
+      end
+
+      # Create a new identifier with a different terminal status
+      #
+      # @param new_terminal [Boolean] new terminal status
+      # @return [Identifier] new identifier instance with new terminal status
+      def with_terminal(new_terminal)
+        new_terminal_bool = !!new_terminal
+        return self if terminal? == new_terminal_bool
+
+        self.class.new(type, side, state, terminal: new_terminal_bool)
       end
 
       # Check if the identifier has enhanced state
@@ -269,6 +318,13 @@ module Sashite
         side == SECOND_PLAYER
       end
 
+      # Check if the identifier is a terminal piece
+      #
+      # @return [Boolean] true if terminal
+      def terminal?
+        terminal
+      end
+
       # Check if this identifier is the same type as another
       #
       # @param other [Identifier] identifier to compare with
@@ -299,6 +355,16 @@ module Sashite
         state == other.state
       end
 
+      # Check if this identifier has the same terminal status as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same terminal status
+      def same_terminal?(other)
+        return false unless other.is_a?(self.class)
+
+        terminal? == other.terminal?
+      end
+
       # Custom equality comparison
       #
       # @param other [Object] object to compare with
@@ -306,7 +372,7 @@ module Sashite
       def ==(other)
         return false unless other.is_a?(self.class)
 
-        type == other.type && side == other.side && state == other.state
+        type == other.type && side == other.side && state == other.state && terminal? == other.terminal?
       end
 
       # Alias for == to ensure Set functionality works correctly
@@ -316,7 +382,7 @@ module Sashite
       #
       # @return [Integer] hash value
       def hash
-        [self.class, type, side, state].hash
+        [self.class, type, side, state, terminal?].hash
       end
 
       # Validate that the type is a valid symbol

data/lib/sashite/pin.rb

@@ -53,14 +53,16 @@ module Sashite
     # @param type [Symbol] piece type (:A to :Z)
     # @param side [Symbol] player side (:first or :second)
     # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+    # @param terminal [Boolean] whether the piece is a terminal piece
     # @return [Pin::Identifier] new identifier instance
     # @raise [ArgumentError] if parameters are invalid
     # @example
-    #   Sashite::Pin.identifier(:K, :first, :normal)     # => #<Pin::Identifier type=:K side=:first state=:normal>
-    #   Sashite::Pin.identifier(:R, :first, :enhanced)   # => #<Pin::Identifier type=:R side=:first state=:enhanced>
-    #   Sashite::Pin.identifier(:P, :second, :diminished) # => #<Pin::Identifier type=:P side=:second state=:diminished>
-    def self.identifier(type, side, state)
-      Identifier.new(type, side, state)
+    #   Sashite::Pin.identifier(:K, :first, :normal)     # => #<Pin::Identifier type=:K side=:first state=:normal terminal=false>
+    #   Sashite::Pin.identifier(:R, :first, :enhanced)   # => #<Pin::Identifier type=:R side=:first state=:enhanced terminal=false>
+    #   Sashite::Pin.identifier(:P, :second, :diminished) # => #<Pin::Identifier type=:P side=:second state=:diminished terminal=false>
+    #   Sashite::Pin.identifier(:K, :first, :normal, terminal: true) # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
+    def self.identifier(type, side, state, terminal: false)
+      Identifier.new(type, side, state, terminal: terminal)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pin
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -13,10 +13,11 @@ description: |
   PIN (Piece Identifier Notation) provides a rule-agnostic format for identifying pieces
   in abstract strategy board games. This gem implements the PIN Specification v1.0.0 with
   a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. PIN uses single ASCII letters with optional state modifiers and case-based
-  side encoding (A-Z for first player, a-z for second player), enabling precise and portable
-  identification of pieces across multiple games. Perfect for game engines, board game notation
-  systems, and hybrid gaming platforms requiring compact, stateful piece representation.
+  principles. PIN uses single ASCII letters with optional state modifiers, terminal markers,
+  and case-based side encoding (A-Z for first player, a-z for second player), enabling
+  precise and portable identification of pieces across multiple games. Perfect for game
+  engines, board game notation systems, and hybrid gaming platforms requiring compact,
+  stateful piece representation.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -51,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: PIN (Piece Identifier Notation) implementation for Ruby with immutable identifier
   objects