sashite-qpi 1.0.0 → 2.0.0

data/README.md

@@ -9,9 +9,29 @@
 
 ## 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.
+QPI (Qualified Piece Identifier) provides complete piece identification by combining two primitive notations:
+- [SIN](https://sashite.dev/specs/sin/1.0.0/) (Style Identifier Notation) — identifies the piece style
+- [PIN](https://sashite.dev/specs/pin/1.0.0/) (Piece Identifier Notation) — identifies the piece attributes
 
-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**.
+A QPI identifier is simply a **pair of (SIN, PIN)** with one constraint: both components must represent the same player.
+
+This gem implements the [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) with a minimal compositional API.
+
+## Core Concept
+
+```ruby
+# QPI is just composition
+qpi = Sashite::Qpi.new(sin_component, pin_component)
+
+# Serializes as "sin:pin"
+qpi.to_s # => "C:K^"
+
+# Access components directly
+qpi.sin   # => SIN::Identifier instance
+qpi.pin   # => PIN::Identifier instance
+```
+
+**That's it.** All piece attributes come from the components.
 
 ## Installation
 
@@ -28,171 +48,209 @@ 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
+## Quick Start
 
 ```ruby
 require "sashite/qpi"
 
-# Parse QPI strings
-identifier = Sashite::Qpi.parse("C:K")         # Chess king, first player
-identifier.to_s                                # => "C:K"
+# Parse a QPI string
+qpi = Sashite::Qpi.parse("C:K^")
+qpi.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)
+# Access the five fundamental attributes through components
+qpi.sin.family        # => :C (Piece Style)
+qpi.pin.type          # => :K (Piece Name)
+qpi.sin.side          # => :first (Piece Side)
+qpi.pin.state         # => :normal (Piece State)
+qpi.pin.terminal?     # => true (Terminal Status)
 
-# Validate QPI strings
-Sashite::Qpi.valid?("C:K")                    # => true
-Sashite::Qpi.valid?("s:+p")                   # => true
-Sashite::Qpi.valid?("C:k")                    # => false (semantic mismatch)
+# Components are full SIN and PIN instances
+qpi.sin.first_player? # => true
+qpi.pin.enhanced?     # => false
 ```
 
-### Strict Parameter Validation
+## Basic Usage
+
+### Creating Identifiers
+
+```ruby
+# Parse from string
+qpi = Sashite::Qpi.parse("C:K^")
+
+# Create from components
+sin = Sashite::Sin.parse("C")
+pin = Sashite::Pin.parse("K^")
+qpi = Sashite::Qpi.new(sin, pin)
+
+# Validate
+Sashite::Qpi.valid?("C:K^")   # => true
+Sashite::Qpi.valid?("C:k")    # => false (side mismatch)
+```
 
-**Important**: QPI enforces the same strict validation as its underlying SIN and PIN primitives:
+### Accessing Components
 
 ```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"
+qpi = Sashite::Qpi.parse("S:+R^")
+
+# Get components
+qpi.sin                       # => #<Sin::Identifier family=:S side=:first>
+qpi.pin                       # => #<Pin::Identifier type=:R state=:enhanced terminal=true>
 
-# ✗ Invalid - lowercase symbols rejected with ArgumentError
-Sashite::Qpi.identifier(:c, :K, :first, :normal)   # => ArgumentError
-Sashite::Qpi.identifier(:C, :k, :first, :normal)   # => ArgumentError
+# Serialize components
+qpi.sin.to_s                  # => "S"
+qpi.pin.to_s                  # => "+R^"
+qpi.to_s                      # => "S:+R^"
 ```
 
-**Key principle**: Input parameters must use uppercase symbols (`:A` to `:Z`). The `side` parameter determines the display case, not the input case.
+### Five Fundamental Attributes
 
-### Attribute Access
+All attributes come directly from the components:
 
 ```ruby
-identifier = Sashite::Qpi.parse("S:+R")
+qpi = Sashite::Qpi.parse("S:+R^")
 
-# Four fundamental piece attributes
-identifier.family                             # => :S
-identifier.type                               # => :R
-identifier.side                               # => :first
-identifier.state                              # => :enhanced
+# From SIN component
+qpi.sin.family                # => :S (Piece Style)
+qpi.sin.side                  # => :first (Piece Side)
 
-# Component extraction
-identifier.to_sin                             # => "S"
-identifier.to_pin                             # => "+R"
-identifier.sin_component                      # => #<Sashite::Sin::Identifier>
-identifier.pin_component                      # => #<Sashite::Pin::Identifier>
+# From PIN component
+qpi.pin.type                  # => :R (Piece Name)
+qpi.pin.state                 # => :enhanced (Piece State)
+qpi.pin.terminal?             # => true (Terminal Status)
 ```
 
-### Transformations
+## Transformations
+
+All transformations return new immutable QPI instances:
+
+### Replace Components
 
 ```ruby
-# All transformations return new immutable instances
-identifier = Sashite::Qpi.parse("C:K")
+qpi = Sashite::Qpi.parse("C:K^")
 
-# State transformations
-enhanced = identifier.enhance                       # => "C:+K"
-diminished = identifier.diminish                    # => "C:-K"
-normalized = identifier.normalize                   # => "C:K"
+# Replace SIN component
+new_sin = Sashite::Sin.parse("S")
+qpi.with_sin(new_sin) # => "S: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"
+# Replace PIN component
+new_pin = Sashite::Pin.parse("Q^")
+qpi.with_pin(new_pin) # => "C:Q^"
 
-# Player assignment flip
-flipped = identifier.flip # => "c:k"
+# Transform both
+qpi.with_sin(new_sin).with_pin(new_pin) # => "S:Q^"
+```
 
-# Chain transformations
-result = identifier.flip.enhance.with_type(:Q) # => "c:+q"
+### Flip (Only Convenience Method)
+
+```ruby
+qpi = Sashite::Qpi.parse("C:K^")
+
+# Flip both components (change player)
+qpi.flip # => "c:k^"
 ```
 
-### State and Comparison Queries
+**Why only `flip`?** It's the only transformation that affects **both** SIN and PIN components simultaneously. All other transformations work through component replacement.
+
+### Transform via Components
 
 ```ruby
-identifier = Sashite::Qpi.parse("S:+P")
+qpi = Sashite::Qpi.parse("C:K^")
 
-# State queries
-identifier.normal?                             # => false
-identifier.enhanced?                           # => true
-identifier.diminished?                         # => false
-identifier.first_player?                       # => true
-identifier.second_player?                      # => false
+# Transform SIN via component
+qpi.with_sin(qpi.sin.with_family(:S)) # => "S:K^"
 
-# 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)
+# Transform PIN via component
+qpi.with_pin(qpi.pin.with_type(:Q)) # => "C:Q^"
+qpi.with_pin(qpi.pin.with_state(:enhanced)) # => "C:+K^"
+qpi.with_pin(qpi.pin.with_terminal(false)) # => "C:K"
+
+# Chain transformations
+qpi
+  .flip
+  .with_sin(qpi.sin.with_family(:S))
+  .with_pin(qpi.pin.with_type(:Q)) # => "s:q^"
+```
+
+## Component Queries
+
+Since QPI is just a composition, use the component APIs directly:
+
+```ruby
+qpi = Sashite::Qpi.parse("S:+P^")
+
+# SIN queries (style and side)
+qpi.sin.family                # => :S
+qpi.sin.side                  # => :first
+qpi.sin.first_player?         # => true
+qpi.sin.letter                # => "S"
+
+# PIN queries (type, state, terminal)
+qpi.pin.type                  # => :P
+qpi.pin.state                 # => :enhanced
+qpi.pin.terminal?             # => true
+qpi.pin.enhanced?             # => true
+qpi.pin.letter                # => "P"
+qpi.pin.prefix                # => "+"
+qpi.pin.suffix                # => "^"
+
+# Compare QPIs
+other = Sashite::Qpi.parse("C:+P^")
+qpi.sin.same_family?(other.sin)  # => false (S vs C)
+qpi.pin.same_type?(other.pin)    # => true (both P)
+qpi.sin.same_side?(other.sin)    # => true (both first)
+qpi.pin.same_state?(other.pin)   # => true (both enhanced)
 ```
 
 ## API Reference
 
-### Main Module Methods
+### Main Module
 
-- `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
+```ruby
+# Parse QPI string
+Sashite::Qpi.parse(qpi_string) # => Qpi::Identifier
+
+# Create from components
+Sashite::Qpi.new(sin, pin) # => Qpi::Identifier
+
+# Validate string
+Sashite::Qpi.valid?(qpi_string) # => Boolean
+```
 
 ### 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
+#### Core Methods (5 total)
+
+```ruby
+# Creation
+Sashite::Qpi.new(sin, pin) # Create from components
+
+# Component access
+qpi.sin                        # => SIN::Identifier
+qpi.pin                        # => PIN::Identifier
+
+# Serialization
+qpi.to_s # => "C:K^"
+
+# Component replacement
+qpi.with_sin(new_sin)          # New QPI with different SIN
+qpi.with_pin(new_pin)          # New QPI with different PIN
+
+# Convenience (transforms both components)
+qpi.flip # Flip both SIN and PIN sides
+```
+
+#### Equality
+
+```ruby
+qpi1 == qpi2 # True if both SIN and PIN equal
+```
+
+**That's the entire API.** Everything else uses the component APIs directly.
 
 ## Format Specification
 
@@ -204,96 +262,371 @@ identifier.cross_family?(other)               # => true (different families)
 ### 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>
+
+<uppercase-pin> ::= ["+" | "-"] <uppercase-letter> ["^"]
+<lowercase-pin> ::= ["+" | "-"] <lowercase-letter> ["^"]
+```
+
+### Semantic Constraint
+
+**Critical**: The SIN and PIN components must represent the **same player**:
+
+```ruby
+# Valid - both first player
+Sashite::Qpi.valid?("C:K")     # => true
+Sashite::Qpi.valid?("C:+K^")   # => true
+
+# Valid - both second player
+Sashite::Qpi.valid?("c:k")     # => true
+Sashite::Qpi.valid?("c:-p^")   # => true
+
+# Invalid - side mismatch
+Sashite::Qpi.valid?("C:k")     # => false (first vs second)
+Sashite::Qpi.valid?("c:K")     # => false (second vs first)
 ```
 
 ### Regular Expression
 ```ruby
-/\A([A-Z]:[-+]?[A-Z]|[a-z]:[-+]?[a-z])\z/
+/\A([A-Z]:[-+]?[A-Z]\^?|[a-z]:[-+]?[a-z]\^?)\z/
 ```
 
-### Examples
+## 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
+### Basic Identifiers
 
-## Semantic Consistency
+```ruby
+# Chess pieces
+chess_king = Sashite::Qpi.parse("C:K^")
+chess_king.sin.family         # => :C (Chess style)
+chess_king.pin.type           # => :K (King)
+chess_king.pin.terminal?      # => true
+
+# Shogi pieces
+shogi_rook = Sashite::Qpi.parse("S:+R")
+shogi_rook.sin.family         # => :S (Shogi style)
+shogi_rook.pin.type           # => :R (Rook)
+shogi_rook.pin.enhanced?      # => true (promoted)
+
+# Xiangqi pieces
+xiangqi_general = Sashite::Qpi.parse("X:G^")
+xiangqi_general.sin.family    # => :X (Xiangqi style)
+xiangqi_general.pin.type      # => :G (General)
+xiangqi_general.pin.terminal? # => true
+```
 
-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.
+### Cross-Style Scenarios
 
-**Valid combinations:**
 ```ruby
-Sashite::Qpi.valid?("C:K")    # => true (both first player)
-Sashite::Qpi.valid?("c:k")    # => true (both second player)
+# Chess vs Shogi match
+chess_player = Sashite::Qpi.parse("C:K^")   # First player uses Chess
+shogi_player = Sashite::Qpi.parse("s:k^")   # Second player uses Shogi
+
+# Different styles
+chess_player.sin.same_family?(shogi_player.sin) # => false
+
+# Same piece type
+chess_player.pin.same_type?(shogi_player.pin) # => true (both kings)
+
+# Different players
+chess_player.sin.same_side?(shogi_player.sin) # => false
 ```
 
-**Invalid combinations:**
+### Component Manipulation
+
 ```ruby
-Sashite::Qpi.valid?("C:k")    # => false (family=first, piece=second)
-Sashite::Qpi.valid?("c:K")    # => false (family=second, piece=first)
+# Start with Chess king
+qpi = Sashite::Qpi.parse("C:K^")
+
+# Change to Shogi style (keep same piece)
+shogi_king = qpi.with_sin(qpi.sin.with_family(:S))
+shogi_king.to_s # => "S:K^"
+
+# Change to queen (keep same style)
+chess_queen = qpi.with_pin(qpi.pin.with_type(:Q))
+chess_queen.to_s # => "C:Q^"
+
+# Enhance piece (keep everything else)
+enhanced = qpi.with_pin(qpi.pin.with_state(:enhanced))
+enhanced.to_s # => "C:+K^"
+
+# Remove terminal marker
+non_terminal = qpi.with_pin(qpi.pin.with_terminal(false))
+non_terminal.to_s # => "C:K"
+
+# Switch player (flip both components)
+opponent = qpi.flip
+opponent.to_s # => "c:k^"
+```
+
+### Working with Components
+
+```ruby
+qpi = Sashite::Qpi.parse("S:+R^")
+
+# Extract and transform SIN
+sin = qpi.sin                           # => "S"
+new_sin = sin.with_family(:C)           # => "C"
+qpi.with_sin(new_sin).to_s              # => "C:+R^"
+
+# Extract and transform PIN
+pin = qpi.pin                           # => "+R^"
+new_pin = pin.with_type(:B)             # => "+B^"
+qpi.with_pin(new_pin).to_s              # => "S:+B^"
+
+# Multiple PIN transformations
+new_pin = pin
+          .with_type(:Q)
+          .with_state(:normal)
+          .with_terminal(false)
+qpi.with_pin(new_pin).to_s # => "S:Q"
+
+# Create completely new QPI
+new_sin = Sashite::Sin.parse("X")
+new_pin = Sashite::Pin.parse("G^")
+Sashite::Qpi.new(new_sin, new_pin).to_s # => "X:G^"
+```
+
+### Immutability
+
+```ruby
+original = Sashite::Qpi.parse("C:K^")
+
+# All transformations return new instances
+flipped = original.flip
+enhanced = original.with_pin(original.pin.with_state(:enhanced))
+different = original.with_sin(original.sin.with_family(:S))
+
+# Original unchanged
+original.to_s                 # => "C:K^"
+flipped.to_s                  # => "c:k^"
+enhanced.to_s                 # => "C:+K^"
+different.to_s                # => "S:K^"
+
+# Components are also immutable
+sin = original.sin
+pin = original.pin
+sin.frozen?                   # => true
+pin.frozen?                   # => true
+```
+
+## Attribute Mapping
+
+QPI exposes all five fundamental attributes from the Sashité Game Protocol through component delegation:
+
+| Protocol Attribute | QPI Access | Example |
+|-------------------|------------|---------|
+| **Piece Style** | `qpi.sin.family` | `:C` (Chess), `:S` (Shogi) |
+| **Piece Name** | `qpi.pin.type` | `:K` (King), `:R` (Rook) |
+| **Piece Side** | `qpi.sin.side` or `qpi.pin.side` | `:first`, `:second` |
+| **Piece State** | `qpi.pin.state` | `:normal`, `:enhanced`, `:diminished` |
+| **Terminal Status** | `qpi.pin.terminal?` | `true`, `false` |
+
+**Note**: `qpi.sin.side` and `qpi.pin.side` are always equal (semantic constraint).
+
+## Design Principles
+
+### 1. Pure Composition
+
+QPI doesn't reimplement features — it composes existing primitives:
+
+```ruby
+# QPI is just a validated pair
+class Identifier
+  def initialize(sin, pin)
+    raise unless sin.side == pin.side # Only validation
+
+    @sin = sin
+    @pin = pin
+  end
+end
 ```
 
-## Parameter Validation
+### 2. Absolute Minimal API
+
+**5 core methods only:**
+1. `new(sin, pin)` — create from components
+2. `sin` — get SIN component
+3. `pin` — get PIN component
+4. `to_s` — serialize
+5. `flip` — flip both components (only convenience method)
+
+Everything else uses component APIs directly.
 
-### Strict Validation Rules
+### 3. Component Transparency
 
-QPI enforces strict parameter validation consistent with its underlying SIN and PIN primitives:
+Access components directly — no wrappers:
 
 ```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
+# Use component APIs directly
+qpi.sin.family
+qpi.sin.with_family(:S)
+qpi.pin.type
+qpi.pin.with_type(:Q)
+qpi.pin.with_terminal(true)
+
+# No need for wrapper methods like:
+# qpi.family
+# qpi.with_family
+# qpi.type
+# qpi.with_type
+# qpi.with_terminal
+```
+
+### 4. Single Convenience Method
+
+Only `flip` is provided as a convenience because it's the **only** transformation that naturally operates on both components:
+
+```ruby
+# Makes sense as convenience
+qpi.flip # Flips both SIN and PIN
 
-# ✗ 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
+# Would be arbitrary conveniences
+# qpi.with_family(:S)  # Just use qpi.with_sin(qpi.sin.with_family(:S))
+# qpi.with_type(:Q)    # Just use qpi.with_pin(qpi.pin.with_type(:Q))
 ```
 
-### Error Handling
+### 5. Immutability
+
+All instances frozen. Transformations return new instances:
+
+```ruby
+qpi1 = Sashite::Qpi.parse("C:K^")
+qpi2 = qpi1.flip
+qpi1.frozen?                  # => true
+qpi2.frozen?                  # => true
+qpi1.equal?(qpi2)             # => false
+```
 
-QPI delegates validation to its underlying primitives, ensuring consistent error messages:
+## Error Handling
 
 ```ruby
+# Invalid QPI string
+begin
+  Sashite::Qpi.parse("invalid")
+rescue ArgumentError => e
+  e.message # => "Invalid QPI string: invalid"
+end
+
+# Side mismatch between components
+sin = Sashite::Sin.parse("C")   # first player
+pin = Sashite::Pin.parse("k")   # second player
 begin
-  Sashite::Qpi.identifier(:c, :K, :first, :normal)
+  Sashite::Qpi.new(sin, pin)
 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"
+  e.message # => Semantic consistency error
 end
 
+# Component validation errors delegate
 begin
-  Sashite::Qpi.identifier(:C, :k, :first, :normal)
+  Sashite::Qpi.parse("CC:K")
 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"
+  # SIN validation error
+end
+```
+
+## Performance Considerations
+
+### Efficient Composition
+
+```ruby
+# Components are created once
+sin = Sashite::Sin.parse("C")
+pin = Sashite::Pin.parse("K^")
+qpi = Sashite::Qpi.new(sin, pin)
+
+# Accessing components is O(1)
+qpi.sin         # => direct reference
+qpi.pin         # => direct reference
+
+# No overhead from method delegation
+qpi.sin.family # => direct method call on component
+```
+
+### Transformation Patterns
+
+```ruby
+qpi = Sashite::Qpi.parse("C:K^")
+
+# Pattern 1: Single component transformation
+qpi.with_pin(qpi.pin.with_type(:Q))
+
+# Pattern 2: Multiple transformations on same component
+new_pin = qpi.pin
+             .with_type(:Q)
+             .with_state(:enhanced)
+             .with_terminal(false)
+qpi.with_pin(new_pin)
+
+# Pattern 3: Transform both components
+new_sin = qpi.sin.with_family(:S)
+new_pin = qpi.pin.with_type(:R)
+Sashite::Qpi.new(new_sin, new_pin)
+
+# Pattern 4: Flip (convenience)
+qpi.flip # Most efficient for switching sides
+```
+
+## Comparison with Other Approaches
+
+### Why Not More Convenience Methods?
+
+```ruby
+# ✗ Arbitrary conveniences
+qpi.with_family(:S)    # Why this...
+qpi.with_type(:Q)      # ...but not this?
+qpi.with_state(:enhanced)  # Where do we stop?
+qpi.with_terminal(true)    # All PIN methods?
+
+# ✓ Consistent principle: use components
+qpi.with_sin(qpi.sin.with_family(:S))
+qpi.with_pin(qpi.pin.with_type(:Q))
+qpi.with_pin(qpi.pin.with_state(:enhanced))
+qpi.with_pin(qpi.pin.with_terminal(true))
+
+# ✓ Only exception: flip (transforms both)
+qpi.flip
+```
+
+### Why Composition Over Inheritance?
+
+```ruby
+# ✗ Bad: QPI inheriting from PIN
+class Qpi < Pin
+  # Problem: QPI is not a specialized PIN
+end
+
+# ✓ Good: QPI composes SIN and PIN
+class Qpi
+  def initialize(sin, pin)
+    @sin = sin
+    @pin = pin
+  end
 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
+- **Rule-agnostic**: Independent of game mechanics
+- **Complete identification**: All five protocol attributes
+- **Cross-style support**: Multi-tradition games
+- **Absolute minimal API**: Only 5 core methods
+- **Pure composition**: Zero feature duplication
+- **Component transparency**: Direct primitive access
+- **Immutable**: Frozen instances
+- **Semantic validation**: Automatic side consistency
+- **Type-safe**: Full component type preservation
+- **Single convenience**: Only `flip` (multi-component operation)
 
 ## 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
+- [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) - Technical specification
+- [QPI Examples](https://sashite.dev/specs/qpi/1.0.0/examples/) - Usage examples
+- [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Style component
+- [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/) - Piece component
+- [Sashité Game Protocol](https://sashite.dev/game-protocol/) - Foundation
 
 ## License