sashite-qpi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f707276efe5619994fb1f4f3204b3b7bf32654cff14bae674d9ad75764afce3
+  data.tar.gz: 8a19a611d441d8e50362449d202e7f49c1298790388d802d9be90b4119ffd237
+SHA512:
+  metadata.gz: 84cbe2ee48fa8ef3e3c2e5b3146447f17f9c0f9755fd2376da25baae3e6ee1a7242144682f3ff0de371ee9a2a618d0051f043888c05d6e92bb4dad393c44077d
+  data.tar.gz: 12dfafe49bf08c75c915f72f1c9fc4484bd9d1e125fd653c6387d290ce761ed6e7d91233f40728bf9ffb61af4e25b3e2fe524f7bca1433048a889fd3588cbd1e

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2014-2025 Sashite
+
+MIT License
+
+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,304 @@
+# Qpi.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/qpi.rb?label=Version&logo=github)](https://github.com/sashite/qpi.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/qpi.rb/main)
+![Ruby](https://github.com/sashite/qpi.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/qpi.rb?label=License&logo=github)](https://github.com/sashite/qpi.rb/raw/main/LICENSE.md)
+
+> **QPI** (Qualified Piece Identifier) implementation for the Ruby language.
+
+## What is QPI?
+
+QPI (Qualified Piece Identifier) provides a rule-agnostic format for identifying game pieces in abstract strategy board games by combining [Style Identifier Notation (SIN)](https://sashite.dev/specs/sin/1.0.0/) and [Piece Identifier Notation (PIN)](https://sashite.dev/specs/pin/1.0.0/) primitives with a colon separator.
+
+This gem implements the [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) exactly, providing complete piece identification with all four fundamental attributes: **Family**, **Type**, **Side**, and **State**.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-qpi"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-qpi
+```
+
+## Dependencies
+
+QPI builds upon two foundational primitive specifications:
+
+```ruby
+gem "sashite-sin"  # Style Identifier Notation
+gem "sashite-pin"  # Piece Identifier Notation
+```
+
+## Usage
+
+### Basic Operations
+
+```ruby
+require "sashite/qpi"
+
+# Parse QPI strings
+identifier = Sashite::Qpi.parse("C:K")         # Chess king, first player
+identifier.to_s                                # => "C:K"
+
+# Create identifiers from parameters (strict validation)
+identifier = Sashite::Qpi.identifier(:C, :K, :first, :normal)
+identifier = Sashite::Qpi::Identifier.new(:S, :R, :first, :enhanced)
+
+# Validate QPI strings
+Sashite::Qpi.valid?("C:K")                    # => true
+Sashite::Qpi.valid?("s:+p")                   # => true
+Sashite::Qpi.valid?("C:k")                    # => false (semantic mismatch)
+```
+
+### Strict Parameter Validation
+
+**Important**: QPI enforces the same strict validation as its underlying SIN and PIN primitives:
+
+```ruby
+# ✓ Valid - uppercase symbols only for family and type parameters
+Sashite::Qpi.identifier(:C, :K, :first, :normal)   # => "C:K"
+Sashite::Qpi.identifier(:C, :K, :second, :normal)  # => "c:k"
+
+# ✗ Invalid - lowercase symbols rejected with ArgumentError
+Sashite::Qpi.identifier(:c, :K, :first, :normal)   # => ArgumentError
+Sashite::Qpi.identifier(:C, :k, :first, :normal)   # => ArgumentError
+```
+
+**Key principle**: Input parameters must use uppercase symbols (`:A` to `:Z`). The `side` parameter determines the display case, not the input case.
+
+### Attribute Access
+
+```ruby
+identifier = Sashite::Qpi.parse("S:+R")
+
+# Four fundamental piece attributes
+identifier.family                             # => :S
+identifier.type                               # => :R
+identifier.side                               # => :first
+identifier.state                              # => :enhanced
+
+# Component extraction
+identifier.to_sin                             # => "S"
+identifier.to_pin                             # => "+R"
+identifier.sin_component                      # => #<Sashite::Sin::Identifier>
+identifier.pin_component                      # => #<Sashite::Pin::Identifier>
+```
+
+### Transformations
+
+```ruby
+# All transformations return new immutable instances
+identifier = Sashite::Qpi.parse("C:K")
+
+# State transformations
+enhanced = identifier.enhance                       # => "C:+K"
+diminished = identifier.diminish                    # => "C:-K"
+normalized = identifier.normalize                   # => "C:K"
+
+# Attribute transformations
+different_type = identifier.with_type(:Q)           # => "C:Q"
+different_side = identifier.with_side(:second)      # => "c:k"
+different_state = identifier.with_state(:enhanced)  # => "C:+K"
+different_family = identifier.with_family(:S)       # => "S:K"
+
+# Player assignment flip
+flipped = identifier.flip # => "c:k"
+
+# Chain transformations
+result = identifier.flip.enhance.with_type(:Q) # => "c:+q"
+```
+
+### State and Comparison Queries
+
+```ruby
+identifier = Sashite::Qpi.parse("S:+P")
+
+# State queries
+identifier.normal?                             # => false
+identifier.enhanced?                           # => true
+identifier.diminished?                         # => false
+identifier.first_player?                       # => true
+identifier.second_player?                      # => false
+
+# Comparison methods
+other = Sashite::Qpi.parse("C:+P")
+identifier.same_family?(other)                # => false (S vs C)
+identifier.same_type?(other)                  # => true (both P)
+identifier.same_side?(other)                  # => true (both first player)
+identifier.same_state?(other)                 # => true (both enhanced)
+identifier.cross_family?(other)               # => true (different families)
+```
+
+## API Reference
+
+### Main Module Methods
+
+- `Sashite::Qpi.parse(qpi_string)` - Parse QPI string into Identifier object
+- `Sashite::Qpi.identifier(family, type, side, state = :normal)` - Create identifier from parameters (strict validation)
+- `Sashite::Qpi.valid?(qpi_string)` - Check if string is valid QPI notation
+
+### Identifier Class
+
+#### Creation and Parsing
+- `Sashite::Qpi::Identifier.new(family, type, side, state = :normal)` - Create from parameters (strict validation)
+- `Sashite::Qpi::Identifier.parse(qpi_string)` - Parse QPI string
+
+#### Parameter Validation
+**Strict validation enforced**:
+- `family` parameter: Must be symbol `:A` to `:Z` (uppercase only)
+- `type` parameter: Must be symbol `:A` to `:Z` (uppercase only)
+- `side` parameter: Must be `:first` or `:second`
+- `state` parameter: Must be `:normal`, `:enhanced`, or `:diminished`
+
+#### Attribute Access
+- `#family` - Get style family (symbol `:A` to `:Z`)
+- `#type` - Get piece type (symbol `:A` to `:Z`)
+- `#side` - Get player side (`:first` or `:second`)
+- `#state` - Get piece state (`:normal`, `:enhanced`, or `:diminished`)
+- `#to_s` - Convert to QPI string representation
+
+#### Component Access
+- `#to_sin` - Get SIN string representation
+- `#to_pin` - Get PIN string representation
+- `#sin_component` - Get SIN identifier object
+- `#pin_component` - Get PIN identifier object
+
+#### State Queries
+- `#normal?` - Check if normal state
+- `#enhanced?` - Check if enhanced state
+- `#diminished?` - Check if diminished state
+- `#first_player?` - Check if first player
+- `#second_player?` - Check if second player
+
+#### Transformations (immutable - return new instances)
+- `#enhance` - Create enhanced version
+- `#diminish` - Create diminished version
+- `#normalize` - Remove state modifiers
+- `#with_type(new_type)` - Change piece type
+- `#with_side(new_side)` - Change player side
+- `#with_state(new_state)` - Change piece state
+- `#with_family(new_family)` - Change style family
+- `#flip` - Switch player assignment for both components
+
+#### Comparison Methods
+- `#same_family?(other)` - Check if same style family
+- `#same_type?(other)` - Check if same piece type
+- `#same_side?(other)` - Check if same player side
+- `#same_state?(other)` - Check if same piece state
+- `#cross_family?(other)` - Check if different style families
+- `#==(other)` - Full equality comparison
+
+## Format Specification
+
+### Structure
+```
+<sin>:<pin>
+```
+
+### Grammar (BNF)
+```bnf
+<qpi> ::= <uppercase-qpi> | <lowercase-qpi>
+<uppercase-qpi> ::= <uppercase-letter> ":" <uppercase-pin>
+<lowercase-qpi> ::= <lowercase-letter> ":" <lowercase-pin>
+<uppercase-pin> ::= ["+" | "-"] <uppercase-letter>
+<lowercase-pin> ::= ["+" | "-"] <lowercase-letter>
+```
+
+### Regular Expression
+```ruby
+/\A([A-Z]:[-+]?[A-Z]|[a-z]:[-+]?[a-z])\z/
+```
+
+### Examples
+
+- `C:K` - Chess-style king, first player
+- `c:k` - Chess-style king, second player
+- `S:+R` - Shogi-style enhanced rook, first player
+- `x:-s` - Xiangqi-style diminished soldier, second player
+
+## Semantic Consistency
+
+QPI enforces semantic consistency: the style and piece components must represent the same player. Both components use case to indicate player assignment, and these must align.
+
+**Valid combinations:**
+```ruby
+Sashite::Qpi.valid?("C:K")    # => true (both first player)
+Sashite::Qpi.valid?("c:k")    # => true (both second player)
+```
+
+**Invalid combinations:**
+```ruby
+Sashite::Qpi.valid?("C:k")    # => false (family=first, piece=second)
+Sashite::Qpi.valid?("c:K")    # => false (family=second, piece=first)
+```
+
+## Parameter Validation
+
+### Strict Validation Rules
+
+QPI enforces strict parameter validation consistent with its underlying SIN and PIN primitives:
+
+```ruby
+# ✓ Valid parameter examples
+Sashite::Qpi.identifier(:C, :K, :first, :normal)     # All uppercase symbols
+Sashite::Qpi.identifier(:S, :R, :second, :enhanced)  # Display case determined by side
+
+# ✗ Invalid parameter examples (raise ArgumentError)
+Sashite::Qpi.identifier(:c, :K, :first, :normal)     # Lowercase family rejected
+Sashite::Qpi.identifier(:C, :k, :first, :normal)     # Lowercase type rejected
+Sashite::Qpi.identifier("C", :K, :first, :normal)    # String family rejected
+Sashite::Qpi.identifier(:C, "K", :first, :normal)    # String type rejected
+```
+
+### Error Handling
+
+QPI delegates validation to its underlying primitives, ensuring consistent error messages:
+
+```ruby
+begin
+  Sashite::Qpi.identifier(:c, :K, :first, :normal)
+rescue ArgumentError => e
+  # Same error message as Sashite::Sin::Identifier.new(:c, :first)
+  puts e.message # => "Family must be a symbol from :A to :Z representing Style Family, got: :c"
+end
+
+begin
+  Sashite::Qpi.identifier(:C, :k, :first, :normal)
+rescue ArgumentError => e
+  # Same error message as Sashite::Pin::Identifier.new(:k, :first, :normal)
+  puts e.message # => "Type must be a symbol from :A to :Z, got: :k"
+end
+```
+
+## Design Properties
+
+- **Rule-agnostic**: Independent of specific game mechanics
+- **Complete identification**: All four piece attributes represented
+- **Cross-style support**: Enables multi-tradition gaming
+- **Semantic validation**: Ensures component consistency
+- **Primitive foundation**: Built from SIN and PIN specifications
+- **Strict validation**: Consistent parameter validation with underlying primitives
+- **Immutable**: All instances frozen, transformations return new objects
+- **Functional**: Pure functions with no side effects
+
+## Related Specifications
+
+- [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) - Complete technical specification
+- [QPI Examples](https://sashite.dev/specs/qpi/1.0.0/examples/) - Practical implementation examples
+- [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Style identification component
+- [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/) - Piece identification component
+- [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation
+
+## 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/qpi/identifier.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "sashite/pin"
+require "sashite/sin"
+
+module Sashite
+  module Qpi
+    # Represents an identifier in QPI (Qualified Piece Identifier) format.
+    #
+    # A QPI identifier combines style and piece attributes into a unified representation:
+    # - Family: Style family from SIN component (:A to :Z only)
+    # - Type: Piece type (:A to :Z) from PIN component
+    # - Side: Player assignment (:first or :second) from both components
+    # - State: Piece state (:normal, :enhanced, :diminished) from PIN component
+    # - Semantic constraint: SIN and PIN components must represent the same player
+    #
+    # All instances are immutable - transformation methods return new instances.
+    # This follows the QPI Specification v1.0.0 with strict parameter validation
+    # consistent with the underlying SIN and PIN primitive specifications.
+    #
+    # ## Strict Parameter Validation
+    #
+    # QPI enforces the same strict validation as its underlying primitives:
+    # - Family parameter must be a symbol from :A to :Z (not :a to :z)
+    # - Type parameter must be a symbol from :A to :Z (delegated to PIN)
+    # - Side parameter determines the display case, not the input parameters
+    #
+    # This ensures consistency with SIN and PIN behavior where lowercase symbols
+    # are rejected with ArgumentError.
+    #
+    # @example Strict parameter validation
+    #   # Valid - uppercase symbols only
+    #   Sashite::Qpi::Identifier.new(:C, :K, :first, :normal)   # => "C:K"
+    #   Sashite::Qpi::Identifier.new(:C, :K, :second, :normal)  # => "c:k"
+    #
+    #   # Invalid - lowercase symbols rejected
+    #   Sashite::Qpi::Identifier.new(:c, :K, :second, :normal)  # => ArgumentError
+    #   Sashite::Qpi::Identifier.new(:C, :k, :second, :normal)  # => ArgumentError
+    #
+    # @see https://sashite.dev/specs/qpi/1.0.0/ QPI Specification v1.0.0
+    class Identifier
+      # Component separator for string representation
+      SEPARATOR = ":"
+
+      # Error messages
+      ERROR_INVALID_QPI = "Invalid QPI string: %s"
+      ERROR_SEMANTIC_MISMATCH = "Family and side must represent the same player: family=%s (side=%s), side=%s"
+      ERROR_MISSING_SEPARATOR = "QPI string must contain exactly one colon separator: %s"
+
+      # @return [Symbol] the style family (:A to :Z based on SIN component)
+      def family
+        @sin_identifier.family
+      end
+
+      # @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
+
+      # Create a new identifier instance
+      #
+      # @param family [Symbol] style family identifier (:A to :Z only)
+      # @param type [Symbol] piece type (:A to :Z only)
+      # @param side [Symbol] player side (:first or :second)
+      # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+      # @raise [ArgumentError] if parameters are invalid or semantically inconsistent
+      #
+      # @example Create identifiers with strict parameter validation
+      #   # Valid - uppercase symbols only
+      #   chess_king = Sashite::Qpi::Identifier.new(:C, :K, :first, :normal)   # => "C:K"
+      #   chess_pawn = Sashite::Qpi::Identifier.new(:C, :P, :second, :normal)  # => "c:p"
+      #
+      #   # Invalid - lowercase symbols rejected
+      #   # Sashite::Qpi::Identifier.new(:c, :K, :first, :normal)   # => ArgumentError
+      #   # Sashite::Qpi::Identifier.new(:C, :k, :first, :normal)   # => ArgumentError
+      def initialize(family, type, side, state = Pin::Identifier::NORMAL_STATE)
+        # Strict validation - delegate to underlying primitives for consistency
+        Sin::Identifier.validate_family(family)
+        Pin::Identifier.validate_type(type)
+        Pin::Identifier.validate_side(side)
+        Pin::Identifier.validate_state(state)
+
+        # Create PIN component
+        @pin_identifier = Pin::Identifier.new(type, side, state)
+
+        # Create SIN component - pass family directly without normalization
+        @sin_identifier = Sin::Identifier.new(family, side)
+
+        # Validate semantic consistency
+        validate_semantic_consistency
+
+        freeze
+      end
+
+      # Parse a QPI string into an Identifier object
+      #
+      # @param qpi_string [String] QPI notation string (format: sin:pin)
+      # @return [Identifier] new identifier instance
+      # @raise [ArgumentError] if the QPI string is invalid
+      #
+      # @example Parse QPI strings with automatic component separation
+      #   Sashite::Qpi::Identifier.parse("C:K")   # => #<Qpi::Identifier family=:C type=:K side=:first state=:normal>
+      #   Sashite::Qpi::Identifier.parse("s:+r")  # => #<Qpi::Identifier family=:S type=:R side=:second state=:enhanced>
+      #   Sashite::Qpi::Identifier.parse("X:-S")  # => #<Qpi::Identifier family=:X type=:S side=:first state=:diminished>
+      def self.parse(qpi_string)
+        string_value = String(qpi_string)
+        sin_part, pin_part = split_components(string_value)
+
+        # Parse components
+        sin_identifier = Sin::Identifier.parse(sin_part)
+        pin_identifier = Pin::Identifier.parse(pin_part)
+
+        # Validate semantic consistency BEFORE creating new instance
+        unless sin_identifier.side == pin_identifier.side
+          raise ::ArgumentError, format(ERROR_SEMANTIC_MISMATCH,
+                                        sin_part, sin_identifier.side, pin_identifier.side)
+        end
+
+        # Extract parameters and create new instance
+        new(sin_identifier.family, pin_identifier.type, pin_identifier.side, pin_identifier.state)
+      end
+
+      # Check if a string is a valid QPI notation
+      #
+      # @param qpi_string [String] the string to validate
+      # @return [Boolean] true if valid QPI, false otherwise
+      #
+      # @example Validate QPI strings with semantic checking
+      #   Sashite::Qpi::Identifier.valid?("C:K")     # => true
+      #   Sashite::Qpi::Identifier.valid?("s:+r")    # => true
+      #   Sashite::Qpi::Identifier.valid?("C:k")     # => false (semantic mismatch)
+      #   Sashite::Qpi::Identifier.valid?("Chess")   # => false (no separator)
+      def self.valid?(qpi_string)
+        return false unless qpi_string.is_a?(::String)
+
+        # Split components and validate each part
+        sin_part, pin_part = split_components(qpi_string)
+        return false unless Sashite::Sin.valid?(sin_part) && Sashite::Pin.valid?(pin_part)
+
+        # Semantic consistency check
+        sin_identifier = Sashite::Sin.parse(sin_part)
+        pin_identifier = Sashite::Pin.parse(pin_part)
+        sin_identifier.side == pin_identifier.side
+      rescue ArgumentError
+        false
+      end
+
+      # Convert the identifier to its QPI string representation
+      #
+      # @return [String] QPI notation string (format: sin:pin)
+      # @example Display QPI identifiers
+      #   identifier.to_s  # => "C:K"
+      def to_s
+        "#{@sin_identifier}#{SEPARATOR}#{@pin_identifier}"
+      end
+
+      # Convert to SIN string representation (style component only)
+      #
+      # @return [String] SIN notation string
+      # @example Extract style component
+      #   identifier.to_sin  # => "C"
+      def to_sin
+        @sin_identifier.to_s
+      end
+
+      # Convert to PIN string representation (piece component only)
+      #
+      # @return [String] PIN notation string
+      # @example Extract piece component
+      #   identifier.to_pin  # => "+K"
+      def to_pin
+        @pin_identifier.to_s
+      end
+
+      # Get the parsed SIN identifier object
+      #
+      # @return [Sashite::Sin::Identifier] SIN component as identifier object
+      def sin_component
+        @sin_identifier
+      end
+
+      # Get the parsed PIN identifier object
+      #
+      # @return [Sashite::Pin::Identifier] PIN component as identifier object
+      def pin_component
+        @pin_identifier
+      end
+
+      # Create a new identifier with enhanced state
+      #
+      # @return [Identifier] new identifier with enhanced PIN component
+      def enhance
+        return self if enhanced?
+
+        self.class.new(family, type, side, Pin::Identifier::ENHANCED_STATE)
+      end
+
+      # Create a new identifier with diminished state
+      #
+      # @return [Identifier] new identifier with diminished PIN component
+      def diminish
+        return self if diminished?
+
+        self.class.new(family, type, side, Pin::Identifier::DIMINISHED_STATE)
+      end
+
+      # Create a new identifier with normal state (no modifiers)
+      #
+      # @return [Identifier] new identifier with normalized PIN component
+      def normalize
+        return self if normal?
+
+        self.class.new(family, type, side, Pin::Identifier::NORMAL_STATE)
+      end
+
+      # Create a new identifier with different piece type
+      #
+      # @param new_type [Symbol] new piece type (:A to :Z)
+      # @return [Identifier] new identifier with different type
+      def with_type(new_type)
+        return self if type == new_type
+
+        self.class.new(family, new_type, side, state)
+      end
+
+      # Create a new identifier with different side
+      #
+      # @param new_side [Symbol] new player side (:first or :second)
+      # @return [Identifier] new identifier with different side
+      def with_side(new_side)
+        return self if side == new_side
+
+        self.class.new(family, type, new_side, state)
+      end
+
+      # Create a new identifier with different state
+      #
+      # @param new_state [Symbol] new piece state (:normal, :enhanced, or :diminished)
+      # @return [Identifier] new identifier with different state
+      def with_state(new_state)
+        return self if state == new_state
+
+        self.class.new(family, type, side, new_state)
+      end
+
+      # Create a new identifier with different family
+      #
+      # @param new_family [Symbol] new style family identifier (:A to :Z)
+      # @return [Identifier] new identifier with different family
+      def with_family(new_family)
+        return self if family == new_family
+
+        self.class.new(new_family, type, side, state)
+      end
+
+      # Create a new identifier with opposite player assignment
+      #
+      # Changes the player assignment (side) while preserving the family and piece attributes.
+      # This maintains semantic consistency between the components.
+      #
+      # @return [Identifier] new identifier with opposite side but same family
+      #
+      # @example Flip player assignment while preserving family and attributes
+      #   chess_first = Sashite::Qpi::Identifier.parse("C:K")   # Chess king, first player
+      #   chess_second = chess_first.flip                       # => "c:k" (Chess king, second player)
+      #
+      #   shogi_first = Sashite::Qpi::Identifier.parse("S:+R")  # Shogi enhanced rook, first player
+      #   shogi_second = shogi_first.flip                       # => "s:+r" (Shogi enhanced rook, second player)
+      def flip
+        self.class.new(family, type, opposite_side, state)
+      end
+
+      # Check if the identifier has normal state
+      #
+      # @return [Boolean] true if normal state
+      def normal?
+        @pin_identifier.normal?
+      end
+
+      # Check if the identifier has enhanced state
+      #
+      # @return [Boolean] true if enhanced state
+      def enhanced?
+        @pin_identifier.enhanced?
+      end
+
+      # Check if the identifier has diminished state
+      #
+      # @return [Boolean] true if diminished state
+      def diminished?
+        @pin_identifier.diminished?
+      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 this identifier has the same family as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same family (case-insensitive)
+      def same_family?(other)
+        return false unless other.is_a?(self.class)
+
+        @sin_identifier.same_family?(other.sin_component)
+      end
+
+      # Check if this identifier has different family from another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if different families
+      def cross_family?(other)
+        return false unless other.is_a?(self.class)
+
+        !same_family?(other)
+      end
+
+      # Check if this identifier has 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.pin_component)
+      end
+
+      # Check if this identifier has the same type as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same type
+      def same_type?(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier.same_type?(other.pin_component)
+      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.pin_component)
+      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)
+
+        @sin_identifier == other.sin_component && @pin_identifier == other.pin_component
+      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, @sin_identifier, @pin_identifier].hash
+      end
+
+      private
+
+      # Split QPI string into SIN and PIN components
+      #
+      # @param qpi_string [String] QPI string to split
+      # @return [Array<String>] array containing [sin_part, pin_part]
+      def self.split_components(qpi_string)
+        parts = qpi_string.split(SEPARATOR, 2)
+        raise ::ArgumentError, format(ERROR_MISSING_SEPARATOR, qpi_string) unless parts.size == 2
+
+        parts
+      end
+
+      private_class_method :split_components
+
+      # Validate semantic consistency between SIN and PIN components
+      #
+      # @raise [ArgumentError] if family case doesn't match side
+      def validate_semantic_consistency
+        expected_side = @sin_identifier.side
+        actual_side = @pin_identifier.side
+
+        return if expected_side == actual_side
+
+        raise ::ArgumentError, format(ERROR_SEMANTIC_MISMATCH,
+                                      @sin_identifier.letter, expected_side, actual_side)
+      end
+
+      # Get the opposite player side
+      #
+      # @return [Symbol] the opposite side
+      def opposite_side
+        first_player? ? Pin::Identifier::SECOND_PLAYER : Pin::Identifier::FIRST_PLAYER
+      end
+    end
+  end
+end

data/lib/sashite/qpi.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "qpi/identifier"
+
+module Sashite
+  # QPI (Qualified Piece Identifier) implementation for Ruby
+  #
+  # Provides a rule-agnostic format for identifying game pieces in abstract strategy board games
+  # by combining Style Identifier Notation (SIN) and Piece Identifier Notation (PIN) primitives
+  # with a colon separator. This combination enables complete piece identification across different
+  # game styles and contexts.
+  #
+  # ## Concept
+  #
+  # QPI addresses the fundamental need to uniquely identify game pieces across different style
+  # systems while maintaining complete attribute information. By combining SIN and PIN primitives,
+  # QPI provides explicit representation of all four fundamental piece attributes from the
+  # Sashité Protocol.
+  #
+  # ## Four Fundamental Attributes
+  #
+  # QPI represents all four piece attributes through primitive combination:
+  # - **Family**: Style identification from SIN component
+  # - **Type**: Piece type from PIN component
+  # - **Side**: Player assignment from both components (must be consistent)
+  # - **State**: Piece state from PIN component
+  #
+  # ## Format Structure
+  #
+  # A QPI identifier consists of two primitive components separated by a colon:
+  # - **SIN component**: Style identification with player assignment
+  # - **PIN component**: Piece identification with type, side, and state
+  # - **Separator**: Colon (:) provides clear delimitation
+  #
+  # The components must maintain semantic consistency: both SIN and PIN must represent
+  # the same player (first or second) through their respective case encodings.
+  #
+  # ## Semantic Consistency Constraint
+  #
+  # QPI enforces a critical constraint: the style identified by the SIN component must be
+  # associated with the same player as indicated by the PIN component. This ensures that
+  # piece ownership and style ownership remain aligned, preventing impossible combinations
+  # like a first player style with a second player piece.
+  #
+  # Examples of semantic consistency:
+  # - SIN "C" (first player) + PIN "K" (first player) = Valid
+  # - SIN "c" (second player) + PIN "k" (second player) = Valid
+  # - SIN "C" (first player) + PIN "k" (second player) = Invalid
+  # - SIN "c" (second player) + PIN "K" (first player) = Invalid
+  #
+  # ## Cross-Style Gaming Support
+  #
+  # QPI enables cross-style gaming scenarios where different players use different game
+  # traditions. The explicit style identification allows pieces from different systems
+  # to coexist while maintaining clear attribution to their respective players.
+  #
+  # ## Format Specification
+  #
+  # Structure: `<sin>:<pin>`
+  #
+  # Grammar (BNF):
+  #   <qpi> ::= <uppercase-qpi> | <lowercase-qpi>
+  #   <uppercase-qpi> ::= <uppercase-letter> ":" <uppercase-pin>
+  #   <lowercase-qpi> ::= <lowercase-letter> ":" <lowercase-pin>
+  #   <uppercase-pin> ::= ["+" | "-"] <uppercase-letter>
+  #   <lowercase-pin> ::= ["+" | "-"] <lowercase-letter>
+  #
+  # Regular Expression: `/\A([A-Z]:[-+]?[A-Z]|[a-z]:[-+]?[a-z])\z/`
+  #
+  # ## Attribute Mapping
+  #
+  # QPI encodes piece attributes through primitive combination:
+  #
+  # | Piece Attribute | QPI Encoding | Examples |
+  # |-----------------|--------------|----------|
+  # | **Family** | SIN component | `C:K` = Chess family, `O:K` = Ogi family |
+  # | **Type** | PIN letter choice | `C:K` = King, `C:P` = Pawn |
+  # | **Side** | Component cases | `C:K` = First player, `c:k` = Second player |
+  # | **State** | PIN prefix modifier | `O:+P` = Enhanced, `C:-P` = Diminished |
+  #
+  # ## System Constraints
+  #
+  # - **Semantic Consistency**: SIN and PIN components must represent the same player
+  # - **Component Validation**: Each component must be valid according to its specification
+  # - **Complete Attribution**: All four fundamental piece attributes explicitly represented
+  # - **Cross-Style Support**: Enables multi-tradition gaming environments
+  #
+  # ## Examples
+  #
+  # ### Single-Style Games
+  #
+  #   # Chess (both players use Chess style)
+  #   white_king = Sashite::Qpi.parse("C:K")     # Chess king, first player
+  #   black_king = Sashite::Qpi.parse("c:k")     # Chess king, second player
+  #
+  #   # Ogi (both players use Ogi style)
+  #   sente_king = Sashite::Qpi.parse("O:K")     # Ogi king, first player (sente)
+  #   gote_rook  = Sashite::Qpi.parse("o:+r")    # Ogi promoted rook, second player (gote)
+  #
+  # ### Cross-Style Games
+  #
+  #   # Chess vs. Ogi match
+  #   chess_player = Sashite::Qpi.parse("C:K")   # First player uses Chess
+  #   ogi_player   = Sashite::Qpi.parse("o:k")   # Second player uses Ogi
+  #
+  #   # Verify cross-style scenario
+  #   chess_player.cross_family?(ogi_player)   # => true
+  #
+  # ### Attribute Access and Manipulation
+  #
+  #   identifier = Sashite::Qpi.parse("O:+R")
+  #
+  #   # Four fundamental attributes
+  #   identifier.family                           # => :O
+  #   identifier.type                             # => :R
+  #   identifier.side                             # => :first
+  #   identifier.state                            # => :enhanced
+  #
+  #   # Component extraction
+  #   identifier.to_sin                           # => "O"
+  #   identifier.to_pin                           # => "+R"
+  #
+  #   # Immutable transformations
+  #   flipped = identifier.flip                   # => "o:+r"
+  #   different_type = identifier.with_type(:Q)   # => "O:+Q"
+  #   different_family = identifier.with_family(:C) # => "C:+R"
+  #
+  # ## Design Properties
+  #
+  # - **Rule-agnostic**: Independent of specific game mechanics
+  # - **Complete identification**: Explicit representation of all four piece attributes
+  # - **Cross-style support**: Enables multi-tradition gaming environments
+  # - **Semantic validation**: Ensures consistency between style and piece ownership
+  # - **Primitive foundation**: Built from foundational SIN and PIN building blocks
+  # - **Extension-ready**: Can be enhanced by human-readable naming systems
+  # - **Context-flexible**: Adaptable to various identification needs
+  # - **Immutable**: All instances are frozen and transformations return new objects
+  # - **Functional**: Pure functions with no side effects
+  #
+  # @see https://sashite.dev/specs/qpi/1.0.0/ QPI Specification v1.0.0
+  # @see https://sashite.dev/specs/qpi/1.0.0/examples/ QPI Examples
+  # @see https://sashite.dev/specs/sin/1.0.0/ Style Identifier Notation (SIN)
+  # @see https://sashite.dev/specs/pin/1.0.0/ Piece Identifier Notation (PIN)
+  module Qpi
+    # Check if a string is a valid QPI notation
+    #
+    # Validates the string format and semantic consistency between SIN and PIN components.
+    # Both components must be individually valid and represent the same player through
+    # their respective case encodings.
+    #
+    # @param qpi_string [String] the string to validate
+    # @return [Boolean] true if valid QPI, false otherwise
+    #
+    # @example Validate various QPI formats
+    #   Sashite::Qpi.valid?("C:K")      # => true (Chess king, first player)
+    #   Sashite::Qpi.valid?("c:k")      # => true (Chess king, second player)
+    #   Sashite::Qpi.valid?("O:+P")     # => true (Ogi enhanced pawn, first player)
+    #   Sashite::Qpi.valid?("o:-r")     # => true (Ogi diminished rook, second player)
+    #   Sashite::Qpi.valid?("C:k")      # => false (semantic mismatch: first player style, second player piece)
+    #   Sashite::Qpi.valid?("c:K")      # => false (semantic mismatch: second player style, first player piece)
+    #   Sashite::Qpi.valid?("CHESS:K")  # => false (multi-character SIN component)
+    #   Sashite::Qpi.valid?("C")        # => false (missing PIN component)
+    def self.valid?(qpi_string)
+      Identifier.valid?(qpi_string)
+    end
+
+    # Parse a QPI string into an Identifier object
+    #
+    # Creates a new QPI identifier by parsing the string into SIN and PIN components,
+    # validating each component, and ensuring semantic consistency between them.
+    #
+    # @param qpi_string [String] QPI notation string (format: sin:pin)
+    # @return [Qpi::Identifier] parsed identifier object with family, type, side, and state attributes
+    # @raise [ArgumentError] if the QPI string is invalid or semantically inconsistent
+    #
+    # @example Parse different QPI formats with complete attribute access
+    #   Sashite::Qpi.parse("C:K")   # => #<Qpi::Identifier family=:C type=:K side=:first state=:normal>
+    #   Sashite::Qpi.parse("c:k")   # => #<Qpi::Identifier family=:C type=:K side=:second state=:normal>
+    #   Sashite::Qpi.parse("O:+R")  # => #<Qpi::Identifier family=:O type=:R side=:first state=:enhanced>
+    #   Sashite::Qpi.parse("x:-s")  # => #<Qpi::Identifier family=:X type=:S side=:second state=:diminished>
+    #
+    # @example Traditional game styles
+    #   chess_king   = Sashite::Qpi.parse("C:K")  # Chess king, first player
+    #   ogi_rook     = Sashite::Qpi.parse("o:+r") # Ogi promoted rook, second player
+    #   xiongqi_king = Sashite::Qpi.parse("X:K")  # Xiongqi king, first player
+    def self.parse(qpi_string)
+      Identifier.parse(qpi_string)
+    end
+
+    # Create a new identifier instance with explicit parameters
+    #
+    # Constructs a QPI identifier by directly specifying all four fundamental attributes.
+    # This method provides parameter-based construction as an alternative to string parsing,
+    # enabling immediate validation and clearer API usage.
+    #
+    # @param family [Symbol] style family identifier (single ASCII letter as symbol)
+    # @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)
+    # @return [Qpi::Identifier] new immutable identifier instance
+    # @raise [ArgumentError] if parameters are invalid or semantically inconsistent
+    #
+    # @example Create identifiers with explicit parameters
+    #   Sashite::Qpi.identifier(:C, :K, :first, :normal)     # => "C:K"
+    #   Sashite::Qpi.identifier(:c, :K, :second, :normal)    # => "c:k"
+    #   Sashite::Qpi.identifier(:O, :R, :first, :enhanced)   # => "O:+R"
+    #   Sashite::Qpi.identifier(:x, :S, :second, :diminished) # => "x:-s"
+    #
+    # @example Cross-style game setup
+    #   chess_player = Sashite::Qpi.identifier(:C, :K, :first, :normal)   # Chess king, first player
+    #   ogi_player   = Sashite::Qpi.identifier(:o, :K, :second, :normal)  # Ogi king, second player
+    #
+    #   chess_player.cross_family?(ogi_player)  # => true (different families)
+    #   chess_player.same_type?(ogi_player)     # => true (both kings)
+    #   chess_player.same_side?(ogi_player)     # => false (different players)
+    def self.identifier(family, type, side, state = Pin::Identifier::NORMAL_STATE)
+      Identifier.new(family, type, side, state)
+    end
+  end
+end

data/lib/sashite-qpi.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "sashite/qpi"
+
+# 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,87 @@
+--- !ruby/object:Gem::Specification
+name: sashite-qpi
+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.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: sashite-sin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |
+  QPI (Qualified Piece Identifier) provides a rule-agnostic format for identifying game pieces
+  in abstract strategy board games by combining Style Identifier Notation (SIN) and Piece
+  Identifier Notation (PIN) primitives. This gem implements the QPI Specification v1.0.0 with
+  a modern Ruby interface featuring immutable identifier objects and functional programming
+  principles. QPI enables complete piece identification with all four fundamental attributes
+  (family, type, side, state) while supporting cross-style gaming environments. Perfect for
+  multi-tradition board games, hybrid gaming systems, and game engines requiring comprehensive
+  piece identification across different game styles and traditions.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-qpi.rb
+- lib/sashite/qpi.rb
+- lib/sashite/qpi/identifier.rb
+homepage: https://github.com/sashite/qpi.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/qpi.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/qpi.rb/main
+  homepage_uri: https://github.com/sashite/qpi.rb
+  source_code_uri: https://github.com/sashite/qpi.rb
+  specification_uri: https://sashite.dev/specs/qpi/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.7.1
+specification_version: 4
+summary: QPI (Qualified Piece Identifier) implementation for Ruby with immutable identifier
+  objects
+test_files: []