sashite-epin 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d4832b1fa452d2b0c5fb78091435ee12a125efd9dcf66c68de291fdc840adf3
+  data.tar.gz: c847fd7927b983c57cf019514a2a4e798cd04a0cda2ed8ef7859a725eee418ba
+SHA512:
+  metadata.gz: 6b5cdff7dc99229e4e72175c284eb9af3baa94196b73923b642ec223028dde914ab9f4f4709a4f4f5c12c04ae53b70e5358864f92045c62b814f0c79c83c22e8
+  data.tar.gz: 21ebf13ebecdfc8ffa165d98788daaf6e3730d082d8fa5cdab0c8ae71da8c386673741b067231407fb5cbb45d1dd85b12b70ca859ff759b434dcf2eb1e0aa39e

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License
+
+Copyright (c) 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,547 @@
+# Epin.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/epin.rb?label=Version&logo=github)](https://github.com/sashite/epin.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/epin.rb/main)
+![Ruby](https://github.com/sashite/epin.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/epin.rb?label=License&logo=github)](https://github.com/sashite/epin.rb/raw/main/LICENSE.md)
+
+> **EPIN** (Extended Piece Identifier Notation) implementation for the Ruby language.
+
+## What is EPIN?
+
+EPIN (Extended Piece Identifier Notation) extends [PIN (Piece Identifier Notation)](https://sashite.dev/specs/pin/1.0.0/) to provide style-aware piece representation in abstract strategy board games. EPIN adds a derivation marker that distinguishes pieces by their style origin, enabling cross-style game scenarios and piece origin tracking.
+
+This gem implements the [EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/), providing a modern Ruby interface with immutable identifier objects and full backward compatibility with PIN while adding style differentiation capabilities.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-epin"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-epin
+```
+
+## Usage
+
+```ruby
+require "sashite/epin"
+
+# Parse EPIN strings into identifier objects
+identifier = Sashite::Epin.parse("K")          # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+identifier.to_s                                # => "K"
+identifier.type                                # => :K
+identifier.side                                # => :first
+identifier.state                               # => :normal
+identifier.native?                             # => true
+
+# Create identifiers directly
+identifier = Sashite::Epin.identifier(:K, :first) # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+identifier = Sashite::Epin::Identifier.new(:R, :second, :enhanced, false) # => #<Epin::Identifier type=:R side=:second state=:enhanced native=false>
+
+# Validate EPIN strings
+Sashite::Epin.valid?("K")                      # => true
+Sashite::Epin.valid?("+R'")                    # => true
+Sashite::Epin.valid?("invalid")                # => false
+
+# Style derivation with apostrophe suffix
+native_king = Sashite::Epin.parse("K")         # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+foreign_king = Sashite::Epin.parse("K'")       # => #<Epin::Identifier type=:K side=:first state=:normal native=false>
+
+native_king.to_s                               # => "K"
+foreign_king.to_s                              # => "K'"
+
+# State manipulation (returns new immutable instances)
+enhanced = identifier.enhance                  # => #<Epin::Identifier type=:K side=:first state=:enhanced native=true>
+enhanced.to_s                                  # => "+K"
+diminished = identifier.diminish               # => #<Epin::Identifier type=:K side=:first state=:diminished native=true>
+diminished.to_s                                # => "-K"
+
+# Style derivation manipulation
+foreign_piece = identifier.derive              # => #<Epin::Identifier type=:K side=:first state=:normal native=false>
+foreign_piece.to_s                             # => "K'"
+back_to_native = foreign_piece.underive        # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+back_to_native.to_s                            # => "K"
+
+# Side manipulation
+flipped = identifier.flip                      # => #<Epin::Identifier type=:K side=:second state=:normal native=true>
+flipped.to_s                                   # => "k"
+
+# Type manipulation
+queen = identifier.with_type(:Q)               # => #<Epin::Identifier type=:Q side=:first state=:normal native=true>
+queen.to_s                                     # => "Q"
+
+# Style queries
+identifier.native?                             # => true
+foreign_king.derived?                          # => true
+foreign_king.foreign?                          # => true (alias for derived?)
+
+# State queries
+identifier.normal?                             # => true
+enhanced.enhanced?                             # => true
+diminished.diminished?                         # => true
+
+# Side queries
+identifier.first_player?                       # => true
+flipped.second_player?                         # => true
+
+# Attribute access
+identifier.letter                              # => "K"
+enhanced.prefix                                # => "+"
+foreign_king.suffix                            # => "'"
+identifier.suffix                              # => ""
+
+# Type and side comparison
+king1 = Sashite::Epin.parse("K")
+king2 = Sashite::Epin.parse("k")
+queen = Sashite::Epin.parse("Q")
+
+king1.same_type?(king2)                        # => true (both kings)
+king1.same_side?(queen)                        # => true (both first player)
+king1.same_type?(queen)                        # => false (different types)
+
+# Style comparison
+native_king = Sashite::Epin.parse("K")
+foreign_king = Sashite::Epin.parse("K'")
+
+native_king.same_style?(foreign_king) # => false (different derivation)
+
+# Functional transformations can be chained
+pawn = Sashite::Epin.parse("P")
+enemy_foreign_promoted = pawn.flip.derive.enhance # => "+p'" (second player foreign promoted pawn)
+```
+
+## Format Specification
+
+### Structure
+```
+<pin>[<suffix>]
+```
+
+Where `<pin>` follows the PIN format: `[<state>]<letter>`
+
+### Components
+
+- **PIN part** (`[<state>]<letter>`): Standard PIN notation
+  - **Letter** (`A-Z`, `a-z`): Represents piece type and side
+    - Uppercase: First player pieces
+    - Lowercase: Second player pieces
+  - **State** (optional prefix):
+    - `+`: Enhanced state (promoted, upgraded, empowered)
+    - `-`: Diminished state (weakened, restricted, temporary)
+    - No prefix: Normal state
+
+- **Derivation suffix** (optional):
+  - `'`: Foreign style (piece has opposite side's native style)
+  - No suffix: Native style (piece has current side's native style)
+
+### Regular Expression
+```ruby
+/\A[-+]?[A-Za-z]'?\z/
+```
+
+### Examples
+- `K` - First player king (native style, normal state)
+- `k'` - Second player king (foreign style, normal state)
+- `+R'` - First player rook (foreign style, enhanced state)
+- `-p` - Second player pawn (native style, diminished state)
+
+## Game Examples
+
+### Cross-Style Chess vs. Shōgi
+
+```ruby
+# Match setup: First player uses Chess, Second player uses Shōgi
+# Native styles: first=Chess, second=Shōgi
+
+# Native pieces (no derivation suffix)
+white_king = Sashite::Epin.identifier(:K, :first)          # => "K" (Chess king)
+black_king = Sashite::Epin.identifier(:K, :second)         # => "k" (Shōgi king)
+
+# Foreign pieces (with derivation suffix)
+white_shogi_king = Sashite::Epin.identifier(:K, :first, :normal, false)   # => "K'" (Shōgi king for white)
+black_chess_king = Sashite::Epin.identifier(:K, :second, :normal, false)  # => "k'" (Chess king for black)
+
+# Promoted pieces in cross-style context
+white_promoted_rook = Sashite::Epin.parse("+R'")  # White shōgi rook promoted to Dragon King
+black_promoted_pawn = Sashite::Epin.parse("+p")   # Black shōgi pawn promoted to Tokin
+
+white_promoted_rook.enhanced?                      # => true
+white_promoted_rook.derived?                       # => true
+black_promoted_pawn.enhanced?                      # => true
+black_promoted_pawn.native?                        # => true
+```
+
+### Single-Style Games (PIN Compatibility)
+
+```ruby
+# Traditional Chess (both players use Chess style)
+# All pieces are native, so EPIN behaves exactly like PIN
+
+white_pieces = %w[K Q +R B N P].map { |pin| Sashite::Epin.parse(pin) }
+black_pieces = %w[k q +r b n p].map { |pin| Sashite::Epin.parse(pin) }
+
+white_pieces.all?(&:native?)                      # => true
+black_pieces.all?(&:native?)                      # => true
+
+# EPIN strings match PIN strings for native pieces
+white_pieces.map(&:to_s)                          # => ["K", "Q", "+R", "B", "N", "P"]
+black_pieces.map(&:to_s)                          # => ["k", "q", "+r", "b", "n", "p"]
+```
+
+### Style Mutation During Gameplay
+
+```ruby
+# Simulate capture with style change (Ōgi rules)
+chess_queen = Sashite::Epin.parse("q'") # Black chess queen (foreign for shōgi player)
+captured = chess_queen.flip.with_type(:P).underive # Becomes white native pawn
+
+chess_queen.to_s                                  # => "q'" (black foreign queen)
+captured.to_s                                     # => "P" (white native pawn)
+
+# Style derivation changes during gameplay
+shogi_piece = Sashite::Epin.parse("r")           # Black shōgi rook (native)
+foreign_piece = shogi_piece.derive               # Convert to foreign style
+foreign_piece.to_s                               # => "r'" (black foreign rook)
+```
+
+## API Reference
+
+### Main Module Methods
+
+- `Sashite::Epin.valid?(epin_string)` - Check if string is valid EPIN notation
+- `Sashite::Epin.parse(epin_string)` - Parse EPIN string into Identifier object
+- `Sashite::Epin.identifier(type, side, state = :normal, native = true)` - Create identifier instance directly
+
+### Identifier Class
+
+#### Creation and Parsing
+- `Sashite::Epin::Identifier.new(type, side, state = :normal, native = true)` - Create identifier instance
+- `Sashite::Epin::Identifier.parse(epin_string)` - Parse EPIN string (same as module method)
+- `Sashite::Epin::Identifier.valid?(epin_string)` - Validate EPIN string (class method)
+
+#### Attribute Access
+- `#type` - Get piece type (symbol :A to :Z, always uppercase)
+- `#side` - Get player side (:first or :second)
+- `#state` - Get state (:normal, :enhanced, or :diminished)
+- `#native` - Get style derivation (true for native, false for foreign)
+- `#letter` - Get letter representation (string, case determined by side)
+- `#prefix` - Get state prefix (string: "+", "-", or "")
+- `#suffix` - Get derivation suffix (string: "'" or "")
+- `#to_s` - Convert to EPIN string representation
+
+#### Style Queries
+- `#native?` - Check if native style (current side's native style)
+- `#derived?` - Check if foreign style (opposite side's native style)
+- `#foreign?` - Alias for `#derived?`
+
+#### State Queries
+- `#normal?` - Check if normal state (no modifiers)
+- `#enhanced?` - Check if enhanced state
+- `#diminished?` - Check if diminished state
+
+#### Side Queries
+- `#first_player?` - Check if first player identifier
+- `#second_player?` - Check if second player identifier
+
+#### State Transformations (immutable - return new instances)
+- `#enhance` - Create enhanced version
+- `#unenhance` - Remove enhanced state
+- `#diminish` - Create diminished version
+- `#undiminish` - Remove diminished state
+- `#normalize` - Remove all state modifiers
+
+#### Style Transformations (immutable - return new instances)
+- `#derive` - Convert to foreign style (add derivation suffix)
+- `#underive` - Convert to native style (remove derivation suffix)
+- `#flip` - Switch player (change side)
+
+#### Attribute Transformations (immutable - return new instances)
+- `#with_type(new_type)` - Create identifier with different type
+- `#with_side(new_side)` - Create identifier with different side
+- `#with_state(new_state)` - Create identifier with different state
+- `#with_derivation(native)` - Create identifier with different derivation
+
+#### 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_style?(other)` - Check if same style derivation
+- `#==(other)` - Full equality comparison
+
+### Constants
+- `Sashite::Epin::Identifier::NATIVE` - Constant for native style (`true`)
+- `Sashite::Epin::Identifier::FOREIGN` - Constant for foreign style (`false`)
+- `Sashite::Epin::Identifier::DERIVATION_SUFFIX` - Derivation suffix for foreign pieces (`"'"`)
+
+## Advanced Usage
+
+### Style Derivation Examples
+
+```ruby
+# Understanding native vs. foreign pieces
+# In a Chess vs. Shōgi match:
+# - First player native style: Chess
+# - Second player native style: Shōgi
+
+native_chess_king = Sashite::Epin.parse("K")      # First player native (Chess king)
+foreign_shogi_king = Sashite::Epin.parse("K'")    # First player foreign (Shōgi king)
+
+native_shogi_king = Sashite::Epin.parse("k")      # Second player native (Shōgi king)
+foreign_chess_king = Sashite::Epin.parse("k'")    # Second player foreign (Chess king)
+
+# Style queries
+native_chess_king.native?                         # => true
+foreign_shogi_king.derived?                       # => true
+native_shogi_king.native?                         # => true
+foreign_chess_king.derived?                       # => true
+```
+
+### Immutable Transformations
+```ruby
+# All transformations return new instances
+original = Sashite::Epin.identifier(:K, :first)
+enhanced = original.enhance
+derived = original.derive
+flipped = original.flip
+
+# Original piece is never modified
+puts original    # => "K"
+puts enhanced    # => "+K"
+puts derived     # => "K'"
+puts flipped     # => "k"
+
+# Transformations can be chained
+result = original.flip.derive.enhance.with_type(:Q)
+puts result # => "+q'"
+```
+
+### Cross-Style Game State Management
+```ruby
+class CrossStyleGameBoard
+  def initialize(first_style, second_style)
+    @first_style = first_style
+    @second_style = second_style
+    @pieces = {}
+  end
+
+  def place(square, piece)
+    @pieces[square] = piece
+  end
+
+  def capture_with_style_change(from_square, to_square, new_type = nil)
+    captured = @pieces[to_square]
+    capturing = @pieces.delete(from_square)
+
+    return nil unless captured && capturing
+
+    # Style mutation: captured piece becomes native to capturing side
+    mutated = captured.flip.underive
+    mutated = mutated.with_type(new_type) if new_type
+
+    @pieces[to_square] = capturing
+    mutated # Return mutated captured piece for hand
+  end
+
+  def pieces_by_style_derivation
+    {
+      native:  @pieces.select { |_, piece| piece.native? },
+      foreign: @pieces.select { |_, piece| piece.derived? }
+    }
+  end
+end
+
+# Usage
+board = CrossStyleGameBoard.new(:chess, :shogi)
+board.place("e1", Sashite::Epin.identifier(:K, :first))               # Chess king
+board.place("e8", Sashite::Epin.identifier(:K, :second))              # Shōgi king
+board.place("d4", Sashite::Epin.identifier(:Q, :first, :normal, false)) # Chess queen using Shōgi style
+
+analysis = board.pieces_by_style_derivation
+puts analysis[:native].size    # => 2
+puts analysis[:foreign].size   # => 1
+```
+
+### PIN Compatibility Layer
+```ruby
+# EPIN is fully backward compatible with PIN
+def convert_pin_to_epin(pin_string)
+  # All PIN strings are valid EPIN strings (native pieces)
+  Sashite::Epin.parse(pin_string)
+end
+
+def convert_epin_to_pin(epin_identifier)
+  # Only native EPIN pieces can be converted to PIN
+  return nil unless epin_identifier.native?
+
+  "#{epin_identifier.prefix}#{epin_identifier.letter}"
+end
+
+# Usage
+pin_pieces = %w[K Q +R -P k q r p]
+epin_pieces = pin_pieces.map { |pin| convert_pin_to_epin(pin) }
+
+epin_pieces.all?(&:native?) # => true
+epin_pieces.map { |p| convert_epin_to_pin(p) } # => ["K", "Q", "+R", "-P", "k", "q", "r", "p"]
+```
+
+### Move Validation Example
+```ruby
+def can_promote_in_style?(piece, target_rank, style_rules)
+  return false unless piece.normal? # Already promoted pieces can't promote again
+
+  case [piece.type, piece.native? ? style_rules[:native] : style_rules[:foreign]]
+  when %i[P chess]  # Chess pawn
+    (piece.first_player? && target_rank == 8) ||
+      (piece.second_player? && target_rank == 1)
+  when %i[P shogi]  # Shōgi pawn
+    (piece.first_player? && target_rank >= 7) ||
+      (piece.second_player? && target_rank <= 3)
+  when %i[R shogi], %i[B shogi] # Shōgi major pieces
+    true
+  else
+    false
+  end
+end
+
+# Usage
+chess_pawn = Sashite::Epin.identifier(:P, :first)
+shogi_pawn = Sashite::Epin.identifier(:P, :first, :normal, false)
+
+style_rules = { native: :chess, foreign: :shogi }
+
+puts can_promote_in_style?(chess_pawn, 8, style_rules)  # => true (chess pawn on 8th rank)
+puts can_promote_in_style?(shogi_pawn, 8, style_rules)  # => true (shogi pawn on 8th rank)
+```
+
+## Implementation Architecture
+
+This gem uses **composition over inheritance** by building upon the proven [sashite-pin](https://github.com/sashite/pin.rb) gem:
+
+- **PIN Foundation**: All type, side, and state logic is handled by an internal `Pin::Identifier` object
+- **EPIN Extension**: Only the derivation (`native`) attribute and related methods are added
+- **Delegation Pattern**: Core PIN methods are delegated to the internal PIN identifier
+- **Immutability**: All transformations return new instances, maintaining functional programming principles
+
+This architecture ensures:
+- **Reliability**: Reuses battle-tested PIN logic
+- **Maintainability**: PIN updates automatically benefit EPIN
+- **Consistency**: PIN and EPIN identifiers behave identically for shared attributes
+- **Performance**: Minimal overhead over pure PIN implementation
+
+## Protocol Mapping
+
+Following the [Game Protocol](https://sashite.dev/game-protocol/):
+
+| Protocol Attribute | EPIN 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 | |
+| **Style** | Derivation suffix | `K` = Native style, `K'` = Foreign style | |
+
+**Style Derivation Logic**:
+- **No suffix**: Piece has the **native style** of its current side
+- **Apostrophe suffix (`'`)**: Piece has the **foreign style** (opposite side's native style)
+
+**Canonical principle**: Identical pieces must have identical EPIN representations.
+
+## Properties
+
+* **PIN Compatible**: All valid PIN strings are valid EPIN strings
+* **Style Aware**: Distinguishes pieces by their style origin through derivation markers
+* **ASCII Compatible**: Maximum portability across systems
+* **Rule-Agnostic**: Independent of specific game mechanics
+* **Compact Format**: Minimal character usage (1-3 characters per piece)
+* **Visual Distinction**: Clear player and style differentiation
+* **Protocol Compliant**: Complete implementation of Sashité piece attributes
+* **Immutable**: All identifier instances are frozen and transformations return new objects
+* **Functional**: Pure functions with no side effects
+
+## Implementation Notes
+
+### Style Derivation Convention
+
+EPIN follows a strict style derivation convention:
+
+1. **Native pieces** (no suffix): Use the current side's native style
+2. **Foreign pieces** (`'` suffix): Use the opposite side's native style
+3. **Match context**: Each side has a defined native style for the entire match
+4. **Style mutations**: Pieces can change derivation through gameplay mechanics
+
+### Example Flow
+
+```ruby
+# Match context: First player=Chess, Second player=Shōgi
+# Input: "K'" (first player foreign)
+# ↓ Parsing
+# type: :K, side: :first, state: :normal, native: false
+# ↓ Style resolution
+# Effective style: Shōgi (second player's native style)
+# ↓ Display
+# EPIN: "K'" (first player king with foreign/Shōgi style)
+```
+
+This ensures that `parse(epin).to_s == epin` for all valid EPIN strings while enabling cross-style gameplay.
+
+## System Constraints
+
+- **Maximum 26 piece types** per game system (one per ASCII letter)
+- **Exactly 2 players** (uppercase/lowercase distinction)
+- **3 state levels** (enhanced, normal, diminished)
+- **2 style derivations** (native, foreign)
+- **Style context dependency**: Requires match-level side-style associations
+
+## Related Specifications
+
+- [PIN](https://sashite.dev/specs/pin/1.0.0/) - Piece Identifier Notation (style-agnostic base)
+- [Game Protocol](https://sashite.dev/game-protocol/) - Conceptual foundation for abstract strategy board games
+- [CELL](https://sashite.dev/specs/cell/) - Board position coordinates
+- [HAND](https://sashite.dev/specs/hand/) - Reserve location notation
+- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
+
+## Documentation
+
+- [Official EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/)
+- [EPIN Examples Documentation](https://sashite.dev/specs/epin/1.0.0/examples/)
+- [Game Protocol Foundation](https://sashite.dev/game-protocol/)
+- [API Documentation](https://rubydoc.info/github/sashite/epin.rb/main)
+
+## Development
+
+```sh
+# Clone the repository
+git clone https://github.com/sashite/epin.rb.git
+cd epin.rb
+
+# Install dependencies
+bundle install
+
+# Run tests
+ruby test.rb
+
+# Generate documentation
+yard doc
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`ruby test.rb`)
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Create a Pull Request
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## About
+
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/epin/identifier.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+
+require "sashite/pin"
+
+module Sashite
+  module Epin
+    # Represents an identifier in EPIN (Extended Piece Identifier Notation) format.
+    #
+    # An identifier consists of a PIN component with an optional derivation marker:
+    # - PIN component: [<state>]<letter> (from PIN specification)
+    # - Derivation marker: "'" (foreign style) or none (native style)
+    #
+    # The case of the letter determines ownership:
+    # - Uppercase (A-Z): first player
+    # - Lowercase (a-z): second player
+    #
+    # Style derivation logic:
+    # - No suffix: piece has the native style of its current side
+    # - Apostrophe suffix: piece has the foreign style (opposite side's native style)
+    #
+    # All instances are immutable - state manipulation methods return new instances.
+    # This extends the Game Protocol's piece model with Style support through derivation.
+    class Identifier
+      # Valid derivation suffixes
+      DERIVATION_SUFFIX = "'"
+      NATIVE_SUFFIX = ""
+
+      # Derivation constants
+      NATIVE = true
+      FOREIGN = false
+
+      # Valid derivations
+      VALID_DERIVATIONS = [NATIVE, FOREIGN].freeze
+
+      # Error messages
+      ERROR_INVALID_EPIN = "Invalid EPIN string: %s"
+      ERROR_INVALID_DERIVATION = "Derivation must be true (native) or false (foreign), got: %s"
+
+      # @return [Symbol] the piece type (:A to :Z)
+      def type
+        @pin_identifier.type
+      end
+
+      # @return [Symbol] the player side (:first or :second)
+      def side
+        @pin_identifier.side
+      end
+
+      # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
+      def state
+        @pin_identifier.state
+      end
+
+      # @return [Boolean] the style derivation (true for native, false for foreign)
+      attr_reader :native
+
+      # 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 native [Boolean] style derivation (true for native, false for foreign)
+      # @raise [ArgumentError] if parameters are invalid
+      # @example
+      #   Identifier.new(:K, :first, :normal, true)
+      #   Identifier.new(:P, :second, :enhanced, false)
+      def initialize(type, side, state = Pin::Identifier::NORMAL_STATE, native = NATIVE)
+        # Validate using PIN class methods for type, side, and state
+        Pin::Identifier.validate_type(type)
+        Pin::Identifier.validate_side(side)
+        Pin::Identifier.validate_state(state)
+        self.class.validate_derivation(native)
+
+        @pin_identifier = Pin::Identifier.new(type, side, state)
+        @native = native
+
+        freeze
+      end
+
+      # Parse an EPIN string into an Identifier object
+      #
+      # @param epin_string [String] EPIN notation string
+      # @return [Identifier] new identifier instance
+      # @raise [ArgumentError] if the EPIN string is invalid
+      # @example
+      #   Epin::Identifier.parse("k")     # => #<Epin::Identifier type=:K side=:second state=:normal native=true>
+      #   Epin::Identifier.parse("+R'")   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
+      #   Epin::Identifier.parse("-p")    # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
+      def self.parse(epin_string)
+        string_value = String(epin_string)
+
+        # Check for derivation suffix
+        if string_value.end_with?(DERIVATION_SUFFIX)
+          pin_part = string_value[0...-1] # Remove the apostrophe
+          foreign = true
+        else
+          pin_part = string_value
+          foreign = false
+        end
+
+        # Validate and parse the PIN part using existing PIN logic
+        raise ::ArgumentError, format(ERROR_INVALID_EPIN, string_value) unless Pin::Identifier.valid?(pin_part)
+
+        pin_identifier = Pin::Identifier.parse(pin_part)
+        identifier_native = !foreign
+
+        new(pin_identifier.type, pin_identifier.side, pin_identifier.state, identifier_native)
+      end
+
+      # Check if a string is a valid EPIN notation
+      #
+      # @param epin_string [String] The string to validate
+      # @return [Boolean] true if valid EPIN, false otherwise
+      #
+      # @example
+      #   Sashite::Epin::Identifier.valid?("K")    # => true
+      #   Sashite::Epin::Identifier.valid?("+R'")  # => true
+      #   Sashite::Epin::Identifier.valid?("-p")   # => true
+      #   Sashite::Epin::Identifier.valid?("KK")   # => false
+      #   Sashite::Epin::Identifier.valid?("++K")  # => false
+      def self.valid?(epin_string)
+        return false unless epin_string.is_a?(::String)
+        return false if epin_string.empty?
+
+        # Check for derivation suffix
+        if epin_string.end_with?(DERIVATION_SUFFIX)
+          pin_part = epin_string[0...-1] # Remove the apostrophe
+          return false if pin_part.empty? # Can't have just an apostrophe
+        else
+          pin_part = epin_string
+        end
+
+        # Validate the PIN part using existing PIN validation
+        Pin::Identifier.valid?(pin_part)
+      end
+
+      # Convert the identifier to its EPIN string representation
+      #
+      # @return [String] EPIN notation string
+      # @example
+      #   identifier.to_s  # => "+R'"
+      #   identifier.to_s  # => "-p"
+      #   identifier.to_s  # => "K"
+      def to_s
+        "#{prefix}#{letter}#{suffix}"
+      end
+
+      # Get the letter representation (inherited from PIN logic)
+      #
+      # @return [String] letter representation combining type and side
+      def letter
+        @pin_identifier.letter
+      end
+
+      # Get the prefix representation (inherited from PIN logic)
+      #
+      # @return [String] prefix representing the state
+      def prefix
+        @pin_identifier.prefix
+      end
+
+      # Get the suffix representation
+      #
+      # @return [String] suffix representing the derivation
+      def suffix
+        native? ? NATIVE_SUFFIX : DERIVATION_SUFFIX
+      end
+
+      # Create a new identifier with enhanced state
+      #
+      # @return [Identifier] new identifier instance with enhanced state
+      # @example
+      #   identifier.enhance  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
+      def enhance
+        return self if enhanced?
+
+        self.class.new(type, side, Pin::Identifier::ENHANCED_STATE, native)
+      end
+
+      # Create a new identifier without enhanced state
+      #
+      # @return [Identifier] new identifier instance without enhanced state
+      # @example
+      #   identifier.unenhance  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
+      def unenhance
+        return self unless enhanced?
+
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+      end
+
+      # Create a new identifier with diminished state
+      #
+      # @return [Identifier] new identifier instance with diminished state
+      # @example
+      #   identifier.diminish  # (:K, :first, :normal, true) => (:K, :first, :diminished, true)
+      def diminish
+        return self if diminished?
+
+        self.class.new(type, side, Pin::Identifier::DIMINISHED_STATE, native)
+      end
+
+      # Create a new identifier without diminished state
+      #
+      # @return [Identifier] new identifier instance without diminished state
+      # @example
+      #   identifier.undiminish  # (:K, :first, :diminished, true) => (:K, :first, :normal, true)
+      def undiminish
+        return self unless diminished?
+
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+      end
+
+      # Create a new identifier with normal state (no modifiers)
+      #
+      # @return [Identifier] new identifier instance with normal state
+      # @example
+      #   identifier.normalize  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
+      def normalize
+        return self if normal?
+
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+      end
+
+      # Create a new identifier with opposite side
+      #
+      # @return [Identifier] new identifier instance with opposite side
+      # @example
+      #   identifier.flip  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
+      def flip
+        self.class.new(type, opposite_side, state, native)
+      end
+
+      # Create a new identifier with foreign style (derivation marker)
+      #
+      # @return [Identifier] new identifier instance with foreign style
+      # @example
+      #   identifier.derive  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
+      def derive
+        return self if derived?
+
+        self.class.new(type, side, state, FOREIGN)
+      end
+
+      # Create a new identifier with native style (no derivation marker)
+      #
+      # @return [Identifier] new identifier instance with native style
+      # @example
+      #   identifier.underive  # (:K, :first, :normal, false) => (:K, :first, :normal, true)
+      def underive
+        return self if native?
+
+        self.class.new(type, side, state, NATIVE)
+      end
+
+      # Create a new identifier with a different type (keeping same side, state, and derivation)
+      #
+      # @param new_type [Symbol] new type (:A to :Z)
+      # @return [Identifier] new identifier instance with different type
+      # @example
+      #   identifier.with_type(:Q)  # (:K, :first, :normal, true) => (:Q, :first, :normal, true)
+      def with_type(new_type)
+        Pin::Identifier.validate_type(new_type)
+        return self if type == new_type
+
+        self.class.new(new_type, side, state, native)
+      end
+
+      # Create a new identifier with a different side (keeping same type, state, and derivation)
+      #
+      # @param new_side [Symbol] :first or :second
+      # @return [Identifier] new identifier instance with different side
+      # @example
+      #   identifier.with_side(:second)  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
+      def with_side(new_side)
+        Pin::Identifier.validate_side(new_side)
+        return self if side == new_side
+
+        self.class.new(type, new_side, state, native)
+      end
+
+      # Create a new identifier with a different state (keeping same type, side, and derivation)
+      #
+      # @param new_state [Symbol] :normal, :enhanced, or :diminished
+      # @return [Identifier] new identifier instance with different state
+      # @example
+      #   identifier.with_state(:enhanced)  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
+      def with_state(new_state)
+        Pin::Identifier.validate_state(new_state)
+        return self if state == new_state
+
+        self.class.new(type, side, new_state, native)
+      end
+
+      # Create a new identifier with a different derivation (keeping same type, side, and state)
+      #
+      # @param new_native [Boolean] true for native, false for foreign
+      # @return [Identifier] new identifier instance with different derivation
+      # @example
+      #   identifier.with_derivation(false)  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
+      def with_derivation(new_native)
+        self.class.validate_derivation(new_native)
+        return self if native == new_native
+
+        self.class.new(type, side, state, new_native)
+      end
+
+      # Check if the identifier has enhanced state
+      #
+      # @return [Boolean] true if enhanced
+      def enhanced?
+        @pin_identifier.enhanced?
+      end
+
+      # Check if the identifier has diminished state
+      #
+      # @return [Boolean] true if diminished
+      def diminished?
+        @pin_identifier.diminished?
+      end
+
+      # Check if the identifier has normal state (no modifiers)
+      #
+      # @return [Boolean] true if no modifiers are present
+      def normal?
+        @pin_identifier.normal?
+      end
+
+      # Check if the identifier belongs to the first player
+      #
+      # @return [Boolean] true if first player
+      def first_player?
+        @pin_identifier.first_player?
+      end
+
+      # Check if the identifier belongs to the second player
+      #
+      # @return [Boolean] true if second player
+      def second_player?
+        @pin_identifier.second_player?
+      end
+
+      # Check if the identifier has native style (no derivation marker)
+      #
+      # @return [Boolean] true if native style
+      def native?
+        native == NATIVE
+      end
+
+      # Check if the identifier has foreign style (derivation marker)
+      #
+      # @return [Boolean] true if foreign style
+      def derived?
+        native == FOREIGN
+      end
+
+      # Alias for derived? to match the specification terminology
+      alias foreign? derived?
+
+      # Check if this identifier is the same type as another (ignoring side, state, and derivation)
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same type
+      # @example
+      #   king1.same_type?(king2)  # (:K, :first, :normal, true) and (:K, :second, :enhanced, false) => true
+      def same_type?(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier.same_type?(other.instance_variable_get(:@pin_identifier))
+      end
+
+      # Check if this identifier belongs to the same side as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same side
+      def same_side?(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier.same_side?(other.instance_variable_get(:@pin_identifier))
+      end
+
+      # Check if this identifier has the same state as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same state
+      def same_state?(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier.same_state?(other.instance_variable_get(:@pin_identifier))
+      end
+
+      # Check if this identifier has the same style derivation as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same style derivation
+      def same_style?(other)
+        return false unless other.is_a?(self.class)
+
+        native == other.native
+      end
+
+      # Custom equality comparison
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if identifiers are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier == other.instance_variable_get(:@pin_identifier) && native == other.native
+      end
+
+      # Alias for == to ensure Set functionality works correctly
+      alias eql? ==
+
+      # Custom hash implementation for use in collections
+      #
+      # @return [Integer] hash value
+      def hash
+        [self.class, @pin_identifier, native].hash
+      end
+
+      # Validate that the derivation is a valid boolean
+      #
+      # @param derivation [Boolean] the derivation to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_derivation(derivation)
+        return if VALID_DERIVATIONS.include?(derivation)
+
+        raise ::ArgumentError, format(ERROR_INVALID_DERIVATION, derivation.inspect)
+      end
+
+      private
+
+      # Get the opposite side of the current identifier
+      #
+      # @return [Symbol] :first if current side is :second, :second if current side is :first
+      def opposite_side
+        @pin_identifier.send(:opposite_side)
+      end
+    end
+  end
+end

data/lib/sashite/epin.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "epin/identifier"
+
+module Sashite
+  # EPIN (Extended Piece Identifier Notation) implementation for Ruby
+  #
+  # Provides style-aware ASCII-based format for representing pieces in abstract strategy board games.
+  # EPIN extends PIN by adding derivation markers that distinguish pieces by their style origin,
+  # enabling cross-style game scenarios and piece origin tracking.
+  #
+  # Format: [<state>]<letter>[<derivation>]
+  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
+  # - Letter: A-Z (first player), a-z (second player)
+  # - Derivation marker: "'" (foreign style), or none (native style)
+  #
+  # Examples:
+  #   "K"   - First player king (native style, normal state)
+  #   "k'"  - Second player king (foreign style, normal state)
+  #   "+R'" - First player rook (foreign style, enhanced state)
+  #   "-p"  - Second player pawn (native style, diminished state)
+  #
+  # See: https://sashite.dev/specs/epin/1.0.0/
+  module Epin
+    # Check if a string is a valid EPIN notation
+    #
+    # @param epin_string [String] The string to validate
+    # @return [Boolean] true if valid EPIN, false otherwise
+    #
+    # @example
+    #   Sashite::Epin.valid?("K")     # => true
+    #   Sashite::Epin.valid?("+R'")   # => true
+    #   Sashite::Epin.valid?("-p")    # => true
+    #   Sashite::Epin.valid?("KK")    # => false
+    #   Sashite::Epin.valid?("++K")   # => false
+    def self.valid?(epin_string)
+      Identifier.valid?(epin_string)
+    end
+
+    # Parse an EPIN string into an Identifier object
+    #
+    # @param epin_string [String] EPIN notation string
+    # @return [Epin::Identifier] new identifier instance
+    # @raise [ArgumentError] if the EPIN string is invalid
+    # @example
+    #   Sashite::Epin.parse("K")     # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+    #   Sashite::Epin.parse("+R'")   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
+    #   Sashite::Epin.parse("-p")    # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
+    def self.parse(epin_string)
+      Identifier.parse(epin_string)
+    end
+
+    # 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 native [Boolean] style derivation (true for native, false for foreign)
+    # @return [Epin::Identifier] new identifier instance
+    # @raise [ArgumentError] if parameters are invalid
+    # @example
+    #   Sashite::Epin.identifier(:K, :first, :normal, true)      # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
+    #   Sashite::Epin.identifier(:R, :first, :enhanced, false)   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
+    #   Sashite::Epin.identifier(:P, :second, :diminished, true) # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
+    def self.identifier(type, side, state = Sashite::Pin::Identifier::NORMAL_STATE, native = Identifier::NATIVE)
+      Identifier.new(type, side, state, native)
+    end
+  end
+end

data/lib/sashite-epin.rb

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

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: sashite-epin
+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-pin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+description: |
+  EPIN (Extended Piece Identifier Notation) extends PIN to provide style-aware piece representation
+  in abstract strategy board games. This gem implements the EPIN Specification v1.0.0 with
+  a modern Ruby interface featuring immutable identifier objects and functional programming
+  principles. EPIN adds derivation markers to PIN that distinguish pieces by their style
+  origin, enabling cross-style game scenarios and piece origin tracking. Represents all
+  four Game Protocol piece attributes with full PIN backward compatibility. Perfect for
+  game engines, cross-tradition tournaments, and hybrid board game environments.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-epin.rb
+- lib/sashite/epin.rb
+- lib/sashite/epin/identifier.rb
+homepage: https://github.com/sashite/epin.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/epin.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/epin.rb/main
+  homepage_uri: https://github.com/sashite/epin.rb
+  source_code_uri: https://github.com/sashite/epin.rb
+  specification_uri: https://sashite.dev/specs/epin/1.0.0/
+  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.6.9
+specification_version: 4
+summary: EPIN (Extended Piece Identifier Notation) implementation for Ruby extending
+  PIN with style derivation markers.
+test_files: []