sashite-sin 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b57d90bf310c7367cfb46d8fd7a927629c9daf51fea8fcb4c678abfe28bedba
-  data.tar.gz: 535401969041a91f3d54f05e022ac7f0f78ea705075dccfd5f306b402f7fa8a7
+  metadata.gz: 28dcd89f0b19451fd1f6455117c8094083dd0da16300e59c3b8aad0987353cc2
+  data.tar.gz: a21dd87d8a1437cad75f0c55c74e7cce93a3d69897384346dcb0ecedf5f7f6c1
 SHA512:
-  metadata.gz: 73e7edb26036041f09a93b5ae1f21c125ea34b8981dcc4d255674e2319d47bc733022e35d33d203792f5b750e9054695779c4e470d6500e87c7de35c2290653b
-  data.tar.gz: 0b828c1a6e076de5c29e6eaf32149719cfd4a1fcc3a6f30fd276bd3afdbf923aee5aabb90812684a3f5c6d3106889422b76deaeadf60c7e9cff2a2dcdc7fdf80
+  metadata.gz: dc4c9ae269c163a60e65c052013154c1709b79e781077ccf16c084a540e13f1303d2122de46f956e2e79d312d6ff106b4081ce0200bfa4296fe0a9e9402dda49
+  data.tar.gz: bcfa66181f441356daa3f7bfb5dfaf609b629728d17c8c798d0ac4af26da3d159954e13e9aa9fb87483c0979ab8f3cb54b7f6bdb3cca870d2ae0a2819a0a0f89

data/README.md

@@ -11,7 +11,7 @@
 
 SIN (Style Identifier Notation) provides a compact, ASCII-based format for identifying **styles** in abstract strategy board games. SIN uses single-character identifiers with case encoding to represent both style identity and player assignment simultaneously.
 
-This gem implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/), providing a rule-agnostic notation system for style identification in board games.
+This gem implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) exactly, providing a rule-agnostic notation system for style identification in board games.
 
 ## Installation
 
@@ -34,14 +34,15 @@ gem install sashite-sin
 require "sashite/sin"
 
 # Parse SIN strings into identifier objects
-identifier = Sashite::Sin.parse("C")           # => #<Sin::Identifier letter=:C side=:first>
+identifier = Sashite::Sin.parse("C")           # Family=:C, Side=:first
 identifier.to_s                                # => "C"
-identifier.letter                              # => :C
+identifier.family                              # => :C
 identifier.side                                # => :first
+identifier.letter                              # => "C" (combined representation)
 
 # Create identifiers directly
-identifier = Sashite::Sin.identifier(:C, :first)           # => #<Sin::Identifier letter=:C side=:first>
-identifier = Sashite::Sin::Identifier.new(:c, :second)     # => #<Sin::Identifier letter=:c side=:second>
+identifier = Sashite::Sin.identifier(:C, :first)           # Family=:C, Side=:first
+identifier = Sashite::Sin::Identifier.new(:C, :second)     # Family=:C, Side=:second
 
 # Validate SIN strings
 Sashite::Sin.valid?("C")                 # => true
@@ -57,19 +58,19 @@ Sashite::Sin.valid?("CC")                # => false (not single character)
 identifier = Sashite::Sin.parse("C")
 
 # Flip player assignment
-flipped = identifier.flip # => #<Sin::Identifier letter=:c side=:second>
+flipped = identifier.flip # Family=:C, Side=:second
 flipped.to_s # => "c"
 
-# Change letter
-changed = identifier.with_letter(:S) # => #<Sin::Identifier letter=:S side=:first>
+# Change family
+changed = identifier.with_family(:S) # Family=:S, Side=:first
 changed.to_s # => "S"
 
 # Change side
-other_side = identifier.with_side(:second) # => #<Sin::Identifier letter=:c side=:second>
+other_side = identifier.with_side(:second) # Family=:C, Side=:second
 other_side.to_s # => "c"
 
 # Chain transformations
-result = identifier.flip.with_letter(:M) # => #<Sin::Identifier letter=:m side=:second>
+result = identifier.flip.with_family(:M) # Family=:M, Side=:second
 result.to_s # => "m"
 ```
 
@@ -82,17 +83,17 @@ opposite = Sashite::Sin.parse("s")
 # Player identification
 identifier.first_player?                       # => true
 identifier.second_player?                      # => false
-opposite.first_player?                    # => false
-opposite.second_player?                   # => true
+opposite.first_player?                         # => false
+opposite.second_player?                        # => true
 
-# Letter comparison
+# Family and side comparison
 chess1 = Sashite::Sin.parse("C")
 chess2 = Sashite::Sin.parse("c")
 shogi = Sashite::Sin.parse("S")
 
-chess1.same_letter?(chess2)               # => true (both use letter C)
+chess1.same_family?(chess2)               # => true (both Chess family)
 chess1.same_side?(shogi)                  # => true (both first player)
-chess1.same_letter?(shogi)                # => false (different letters)
+chess1.same_family?(shogi)                # => false (different families)
 ```
 
 ### Identifier Collections
@@ -105,12 +106,12 @@ identifiers = %w[C c S s M m].map { |sin| Sashite::Sin.parse(sin) }
 first_player_identifiers = identifiers.select(&:first_player?)
 first_player_identifiers.map(&:to_s) # => ["C", "S", "M"]
 
-# Group by letter family
-by_letter = identifiers.group_by { |i| i.letter.to_s.upcase }
-by_letter["C"].size # => 2 (both C and c)
+# Group by family
+by_family = identifiers.group_by(&:family)
+by_family[:C].size # => 2 (both C and c)
 
-# Find specific combinations
-chess_identifiers = identifiers.select { |i| i.letter.to_s.upcase == "C" }
+# Find specific families
+chess_identifiers = identifiers.select { |i| i.family == :C }
 chess_identifiers.map(&:to_s) # => ["C", "c"]
 ```
 
@@ -136,35 +137,60 @@ chess_identifiers.map(&:to_s) # => ["C", "c"]
 
 ### Style Attribute Mapping
 
+SIN encodes style attributes using the following correspondence:
+
 | Style Attribute | SIN Encoding | Examples |
 |-----------------|--------------|----------|
-| **Style Family** | Letter choice | `C`/`c` = Chess family |
-| **Player Assignment** | Letter case | `C` = First player, `c` = Second player |
+| **Family** | Style family symbol | `:C`, `:S`, `:X` |
+| **Side** | Player assignment | `:first`, `:second` |
+| **Letter** | Combined representation | `"C"`, `"c"`, `"S"`, `"s"` |
+
+#### Dual-Purpose Encoding
 
-## Game Examples
+The **Letter** combines two distinct semantic components:
+- **Style Family**: The underlying family symbol (:A-:Z), representing the game tradition or rule system
+- **Player Assignment**: The side (:first or :second), encoded as case in the letter representation
 
-The SIN specification is rule-agnostic and does not define specific letter assignments. However, here are common usage patterns:
+**Examples**:
+- Family `:C` + Side `:first` → Letter `"C"` (Chess, First player)
+- Family `:C` + Side `:second` → Letter `"c"` (Chess, Second player)
+- Family `:S` + Side `:first` → Letter `"S"` (Shōgi, First player)
+- Family `:S` + Side `:second` → Letter `"s"` (Shōgi, Second player)
 
-### Traditional Game Families
+## Traditional Game Style Examples
+
+The SIN specification is rule-agnostic and does not define specific letter assignments. However, here are common usage patterns following [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/):
 
 ```ruby
-# Chess family identifiers
-chess_white = Sashite::Sin.parse("C")    # First player, Chess family
-chess_black = Sashite::Sin.parse("c")    # Second player, Chess family
+# Chess (8×8 board)
+chess_white = Sashite::Sin.parse("C")    # First player (White pieces)
+chess_black = Sashite::Sin.parse("c")    # Second player (Black pieces)
+
+# Shōgi (9×9 board)
+shogi_sente = Sashite::Sin.parse("S")    # First player (Sente 先手)
+shogi_gote = Sashite::Sin.parse("s")     # Second player (Gote 後手)
 
-# Shōgi family identifiers
-shogi_sente = Sashite::Sin.parse("S")    # First player, Shōgi family
-shogi_gote = Sashite::Sin.parse("s")     # Second player, Shōgi family
+# Xiangqi (9×10 board)
+xiangqi_red = Sashite::Sin.parse("X")    # First player (Red pieces)
+xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)
 
-# Xiangqi family identifiers
-xiangqi_red = Sashite::Sin.parse("X")    # First player, Xiangqi family
-xiangqi_black = Sashite::Sin.parse("x")  # Second player, Xiangqi family
+# Makruk (8×8 board)
+makruk_white = Sashite::Sin.parse("M")   # First player (White pieces)
+makruk_black = Sashite::Sin.parse("m")   # Second player (Black pieces)
+
+# Janggi (9×10 board)
+janggi_cho = Sashite::Sin.parse("J")     # First player (Cho 초)
+janggi_han = Sashite::Sin.parse("j")     # Second player (Han 한)
 ```
 
-### Cross-Style Scenarios
+## Cross-Style Scenarios
 
 ```ruby
-# Different families in one match
+# Chess vs. Ōgi Match (both 8×8 compatible)
+chess_white = Sashite::Sin.parse("C")    # Chess style, first player
+ogi_black = Sashite::Sin.parse("o")      # Ōgi style, second player
+
+# Cross-Style Match Setup
 def create_hybrid_match
   [
     Sashite::Sin.parse("C"),             # First player uses Chess family
@@ -173,22 +199,22 @@ def create_hybrid_match
 end
 
 identifiers = create_hybrid_match
-identifiers[0].same_side?(identifiers[1])         # => false (different players)
-identifiers[0].same_letter?(identifiers[1])       # => false (different families)
+identifiers[0].same_side?(identifiers[1])    # => false (different players)
+identifiers[0].same_family?(identifiers[1])  # => false (different families)
 ```
 
-### Variant Families
+## System Constraints
 
-```ruby
-# Different letters can represent variants within traditions
-makruk = Sashite::Sin.parse("M")        # Makruk (Thai Chess) family
-janggi = Sashite::Sin.parse("J")        # Janggi (Korean Chess) family
-ogi = Sashite::Sin.parse("O")           # Ōgi (王棋) family
-
-# Each family can have both players
-makruk_black = makruk.flip              # Second player Makruk
-makruk_black.to_s                       # => "m"
-```
+### Character Limitation
+SIN provides **26 possible identifiers** per player using ASCII letters (A-Z, a-z).
+
+### Player Limitation
+SIN supports exactly **two players** through case distinction:
+- **First player**: Uppercase letters (A-Z) → `:first`
+- **Second player**: Lowercase letters (a-z) → `:second`
+
+### Context Dependency
+The specific SIN assignment for a style may vary between different game contexts based on collision avoidance, historical precedence, and community conventions.
 
 ## API Reference
 
@@ -196,17 +222,18 @@ makruk_black.to_s                       # => "m"
 
 - `Sashite::Sin.valid?(sin_string)` - Check if string is valid SIN notation
 - `Sashite::Sin.parse(sin_string)` - Parse SIN string into Identifier object
-- `Sashite::Sin.identifier(letter, side)` - Create identifier instance directly
+- `Sashite::Sin.identifier(family, side)` - Create identifier instance directly
 
 ### Identifier Class
 
 #### Creation and Parsing
-- `Sashite::Sin::Identifier.new(letter, side)` - Create identifier instance
+- `Sashite::Sin::Identifier.new(family, side)` - Create identifier instance
 - `Sashite::Sin::Identifier.parse(sin_string)` - Parse SIN string
 
 #### Attribute Access
-- `#letter` - Get style letter (symbol :A through :z)
+- `#family` - Get style family (symbol :A through :Z)
 - `#side` - Get player side (:first or :second)
+- `#letter` - Get combined letter representation (string)
 - `#to_s` - Convert to SIN string representation
 
 #### Player Queries
@@ -215,42 +242,38 @@ makruk_black.to_s                       # => "m"
 
 #### Transformations (immutable - return new instances)
 - `#flip` - Switch player assignment
-- `#with_letter(new_letter)` - Create identifier with different letter
+- `#with_family(new_family)` - Create identifier with different family
 - `#with_side(new_side)` - Create identifier with different side
 
 #### Comparison Methods
-- `#same_letter?(other)` - Check if same style letter (case-insensitive)
+- `#same_family?(other)` - Check if same style family
 - `#same_side?(other)` - Check if same player side
 - `#==(other)` - Full equality comparison
+- `#same_letter?(other)` - Alias for `same_family?` (deprecated)
 
-### Identifier Class Constants
+### Constants
 
-- `Sashite::Sin::Identifier::FIRST_PLAYER` - Symbol for first player (:first)
-- `Sashite::Sin::Identifier::SECOND_PLAYER` - Symbol for second player (:second)
+- `Sashite::Sin::Identifier::FIRST_PLAYER` - Symbol for first player (`:first`)
+- `Sashite::Sin::Identifier::SECOND_PLAYER` - Symbol for second player (`:second`)
+- `Sashite::Sin::Identifier::VALID_FAMILIES` - Array of valid families (`:A` to `:Z`)
 - `Sashite::Sin::Identifier::VALID_SIDES` - Array of valid sides
 - `Sashite::Sin::Identifier::SIN_PATTERN` - Regular expression for SIN validation
 
 ## Advanced Usage
 
-### Letter Case and Side Mapping
+### Family and Side Separation
 
 ```ruby
-# SIN encodes player assignment through case
-upper_case_letters = ("A".."Z").map { |letter| Sashite::Sin.parse(letter) }
-lower_case_letters = ("a".."z").map { |letter| Sashite::Sin.parse(letter) }
-
-# All uppercase letters are first player
-upper_case_letters.all?(&:first_player?) # => true
-
-# All lowercase letters are second player
-lower_case_letters.all?(&:second_player?) # => true
-
-# Letter families are related by case
-letter_a_first = Sashite::Sin.parse("A")
-letter_a_second = Sashite::Sin.parse("a")
-
-letter_a_first.same_letter?(letter_a_second)  # => true
-letter_a_first.same_side?(letter_a_second)    # => false
+# Clear separation of concerns
+identifier = Sashite::Sin.parse("C")
+identifier.family  # => :C (Style Family - invariant)
+identifier.side    # => :first (Player Assignment)
+identifier.letter  # => "C" (Combined representation)
+
+# Transformations are explicit
+chess_white = Sashite::Sin.identifier(:C, :first)
+shogi_white = chess_white.with_family(:S) # Change family, keep side
+chess_black = chess_white.with_side(:second) # Change side, keep family
 ```
 
 ### Immutable Transformations
@@ -259,39 +282,29 @@ letter_a_first.same_side?(letter_a_second)    # => false
 # All transformations return new instances
 original = Sashite::Sin.identifier(:C, :first)
 flipped = original.flip
-changed_letter = original.with_letter(:S)
+changed_family = original.with_family(:S)
 
 # Original identifier is never modified
-original.to_s                           # => "C" (unchanged)
-flipped.to_s                            # => "c"
-changed_letter.to_s                     # => "S"
+original.to_s         # => "C" (unchanged)
+flipped.to_s          # => "c"
+changed_family.to_s   # => "S"
 
 # Transformations can be chained
-result = original.flip.with_letter(:M).flip
+result = original.flip.with_family(:M).flip
 result.to_s # => "M"
 ```
 
-## Protocol Mapping
-
-Following the [Sashité Protocol](https://sashite.dev/protocol/):
-
-| Protocol Attribute | SIN Encoding | Examples | Notes |
-|-------------------|--------------|----------|-------|
-| **Style Family** | Letter choice | `C`, `S`, `X` | Rule-agnostic letter assignment |
-| **Player Assignment** | Case encoding | `C` = First player, `c` = Second player | Case determines side |
-
-## System Constraints
-
-- **26 possible identifiers** per player using ASCII letters (A-Z, a-z)
-- **Exactly 2 players** through case distinction
-- **Single character** per style-player combination
-- **Rule-agnostic** - no predefined letter meanings
-
 ## Design Properties
 
+Following the SIN v1.0.0 specification, this implementation provides:
+
 - **ASCII compatibility**: Maximum portability across systems
 - **Rule-agnostic**: Independent of specific game mechanics
 - **Minimal overhead**: Single character per style-player combination
+- **Flexible collision resolution**: Systematic approaches for identifier conflicts
+- **Semantic clarity**: Distinct concepts for Family, Side, and Letter
+- **SNN coordination**: Works harmoniously with formal style naming
+- **Context-aware**: Adapts to avoid conflicts within specific game scenarios
 - **Canonical representation**: Each style-player combination has exactly one SIN identifier
 - **Immutable**: All identifier instances are frozen and transformations return new objects
 - **Functional**: Pure functions with no side effects
@@ -300,16 +313,13 @@ Following the [Sashité Protocol](https://sashite.dev/protocol/):
 
 - [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Complete technical specification
 - [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/) - Practical implementation examples
+- [Style Name Notation (SNN)](https://sashite.dev/specs/snn/) - Formal naming for game styles
 - [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation for abstract strategy board games
-- [PIN](https://sashite.dev/specs/pin/) - Piece Identifier Notation
-- [PNN](https://sashite.dev/specs/pnn/) - Piece Name Notation (style-aware piece representation)
-- [QPI](https://sashite.dev/specs/qpi/) - Qualified Piece Identifier
 
 ## Documentation
 
 - [Official SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/)
 - [SIN Examples Documentation](https://sashite.dev/specs/sin/1.0.0/examples/)
-- [Sashité Protocol Foundation](https://sashite.dev/protocol/)
 - [API Documentation](https://rubydoc.info/github/sashite/sin.rb/main)
 
 ## Development
@@ -329,16 +339,6 @@ ruby test.rb
 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).

data/lib/sashite/sin/identifier.rb

@@ -4,80 +4,170 @@ module Sashite
   module Sin
     # Represents an identifier in SIN (Style Identifier Notation) format.
     #
+    # ## Concept
+    #
+    # SIN addresses the fundamental need to identify which style system governs piece behavior
+    # while simultaneously indicating which player controls pieces of that style. In cross-style
+    # scenarios where different players use different game traditions, this dual encoding becomes
+    # essential for unambiguous piece identification.
+    #
+    # ## Dual-Purpose Encoding
+    #
+    # Each SIN identifier serves two functions:
+    # - **Style Family Identification**: The family choice indicates which rule system applies
+    # - **Player Assignment**: The side indicates which player uses this style as their native system
+    #
+    # ## Format Structure
+    #
     # An identifier consists of a single ASCII letter with case-based side encoding:
     # - Uppercase letter: first player (A, B, C, ..., Z)
     # - Lowercase letter: second player (a, b, c, ..., z)
     #
+    # The letter representation combines two distinct semantic components:
+    # - **Style Family**: The underlying ASCII character (A-Z), representing the game tradition or rule system
+    # - **Player Assignment**: The case of the character (uppercase/lowercase), representing which player uses this style
+    #
+    # Examples of letter composition:
+    # - Family :C + Side :first  → Letter "C" (Chess, First player)
+    # - Family :C + Side :second → Letter "c" (Chess, Second player)
+    # - Family :S + Side :first  → Letter "S" (Shōgi, First player)
+    # - Family :S + Side :second → Letter "s" (Shōgi, Second player)
+    #
+    # ## Canonical Representation
+    #
+    # SIN enforces canonical representation where each style-player combination has exactly one
+    # valid identifier within a given context. This ensures consistent interpretation across
+    # different implementations while allowing flexibility for collision resolution.
+    #
+    # ## Immutability
+    #
     # All instances are immutable - transformation methods return new instances.
-    # This follows the SIN Specification v1.0.0 with Letter and Side attributes.
+    # This follows the SIN Specification v1.0.0 functional design principles.
+    #
+    # @example Basic usage with traditional game styles
+    #   # Chess family identifiers
+    #   chess_white = Sashite::Sin::Identifier.parse("C")  # Family :C, Side :first
+    #   chess_black = Sashite::Sin::Identifier.parse("c")  # Family :C, Side :second
+    #
+    #   # Shōgi family identifiers
+    #   shogi_sente = Sashite::Sin::Identifier.parse("S")  # Family :S, Side :first
+    #   shogi_gote  = Sashite::Sin::Identifier.parse("s")  # Family :S, Side :second
+    #
+    # @example Dual-purpose encoding demonstration
+    #   identifier = Sashite::Sin::Identifier.parse("C")
+    #   identifier.family  # => :C (Style Family)
+    #   identifier.side    # => :first (Player Assignment)
+    #   identifier.letter  # => "C" (Combined representation)
+    #
+    # @example Cross-style scenarios
+    #   # Different families in one match (requires compatible board structures)
+    #   chess_style = Sashite::Sin::Identifier.parse("C")  # First player uses Chess family
+    #   ogi_style   = Sashite::Sin::Identifier.parse("o")  # Second player uses Ōgi family
+    #
+    # @see https://sashite.dev/specs/sin/1.0.0/ SIN Specification v1.0.0
     class Identifier
-      # SIN validation pattern matching the specification
+      # SIN validation pattern matching the specification regular expression
+      # Grammar: <sin> ::= <uppercase-letter> | <lowercase-letter>
       SIN_PATTERN = /\A[A-Za-z]\z/
 
-      # Player side constants
+      # Player side constants following SIN v1.0.0 two-player constraint
       FIRST_PLAYER = :first
       SECOND_PLAYER = :second
 
-      # Valid sides
+      # Valid families (A-Z)
+      VALID_FAMILIES = (:A..:Z).to_a.freeze
+
+      # Valid sides array for validation
       VALID_SIDES = [FIRST_PLAYER, SECOND_PLAYER].freeze
 
-      # Error messages
-      ERROR_INVALID_SIN = "Invalid SIN string: %s"
-      ERROR_INVALID_LETTER = "Letter must be a single ASCII letter symbol (A-Z, a-z), got: %s"
-      ERROR_INVALID_SIDE = "Side must be :first or :second, got: %s"
+      # Error messages with SIN-compliant terminology
+      ERROR_INVALID_SIN = "Invalid SIN string: %s. Must be a single ASCII letter (A-Z, a-z)"
+      ERROR_INVALID_FAMILY = "Family must be a symbol from :A to :Z representing Style Family, got: %s"
+      ERROR_INVALID_SIDE = "Side must be :first or :second following SIN two-player constraint, got: %s"
 
-      # @return [Symbol] the style letter (single ASCII letter as symbol)
-      attr_reader :letter
+      # @return [Symbol] the style family (:A to :Z)
+      #   This represents the Style Family component - the game tradition or rule system
+      attr_reader :family
 
       # @return [Symbol] the player side (:first or :second)
+      #   This represents the Player Assignment component
       attr_reader :side
 
-      # Create a new identifier instance
+      # Create a new identifier instance with canonical representation
       #
-      # @param letter [Symbol] style letter (single ASCII letter as symbol)
-      # @param side [Symbol] player side (:first or :second)
+      # @param family [Symbol] style family (:A to :Z representing Style Family)
+      # @param side [Symbol] player side (:first or :second representing Player Assignment)
       # @raise [ArgumentError] if parameters are invalid
-      def initialize(letter, side)
-        self.class.validate_letter(letter)
+      #
+      # @example Create identifiers with family and side separation
+      #   # Chess family identifiers
+      #   chess_first  = Sashite::Sin::Identifier.new(:C, :first)   # => Family=:C, Side=:first
+      #   chess_second = Sashite::Sin::Identifier.new(:C, :second)  # => Family=:C, Side=:second
+      #
+      # @example Style Family and Player Assignment demonstration
+      #   identifier = Sashite::Sin::Identifier.new(:S, :first)
+      #   identifier.family  # => :S (Shōgi Style Family)
+      #   identifier.side    # => :first (First Player Assignment)
+      #   identifier.letter  # => "S" (Combined representation)
+      def initialize(family, side)
+        self.class.validate_family(family)
         self.class.validate_side(side)
 
-        @letter = letter
+        @family = family
         @side = side
 
         freeze
       end
 
-      # Parse an SIN string into an Identifier object
+      # Parse an SIN string into an Identifier object with dual-purpose encoding
+      #
+      # The family and side are inferred from both the character choice (Style Family)
+      # and case (Player Assignment):
+      # - Uppercase letter → Style Family + First player
+      # - Lowercase letter → Style Family + Second player
       #
       # @param sin_string [String] SIN notation string (single ASCII letter)
-      # @return [Identifier] parsed identifier object with letter and inferred side
+      # @return [Identifier] parsed identifier object with Family and Side attributes
       # @raise [ArgumentError] if the SIN string is invalid
-      # @example Parse SIN strings with case-based side inference
-      #   Sashite::Sin::Identifier.parse("C") # => #<Sin::Identifier letter=:C side=:first>
-      #   Sashite::Sin::Identifier.parse("c") # => #<Sin::Identifier letter=:c side=:second>
-      #   Sashite::Sin::Identifier.parse("S") # => #<Sin::Identifier letter=:S side=:first>
+      #
+      # @example Parse SIN strings with case-based Player Assignment inference
+      #   Sashite::Sin::Identifier.parse("C")  # => Family=:C, Side=:first (Chess, White)
+      #   Sashite::Sin::Identifier.parse("c")  # => Family=:C, Side=:second (Chess, Black)
+      #   Sashite::Sin::Identifier.parse("S")  # => Family=:S, Side=:first (Shōgi, Sente)
+      #   Sashite::Sin::Identifier.parse("s")  # => Family=:S, Side=:second (Shōgi, Gote)
+      #
+      # @example Traditional game styles from SIN Examples
+      #   # Chess (8×8 board)
+      #   chess_white = Sashite::Sin::Identifier.parse("C")  # First player (White pieces)
+      #   chess_black = Sashite::Sin::Identifier.parse("c")  # Second player (Black pieces)
+      #
+      #   # Xiangqi (9×10 board)
+      #   xiangqi_red   = Sashite::Sin::Identifier.parse("X")  # First player (Red pieces)
+      #   xiangqi_black = Sashite::Sin::Identifier.parse("x")  # Second player (Black pieces)
       def self.parse(sin_string)
         string_value = String(sin_string)
         validate_sin_string(string_value)
 
-        # Determine side from case
+        # Extract Style Family (case-insensitive) and Player Assignment (case-sensitive)
+        family_symbol = string_value.upcase.to_sym
         identifier_side = string_value == string_value.upcase ? FIRST_PLAYER : SECOND_PLAYER
 
-        # Use the letter directly as symbol
-        identifier_letter = string_value.to_sym
-
-        new(identifier_letter, identifier_side)
+        new(family_symbol, identifier_side)
       end
 
-      # Check if a string is a valid SIN notation
+      # Check if a string is a valid SIN notation according to specification
+      #
+      # Validates against the SIN grammar:
+      # <sin> ::= <uppercase-letter> | <lowercase-letter>
       #
       # @param sin_string [String] the string to validate
       # @return [Boolean] true if valid SIN, false otherwise
       #
-      # @example Validate SIN strings
-      #   Sashite::Sin::Identifier.valid?("C") # => true
-      #   Sashite::Sin::Identifier.valid?("c") # => true
-      #   Sashite::Sin::Identifier.valid?("CHESS") # => false (multi-character)
+      # @example Validate SIN strings against specification
+      #   Sashite::Sin::Identifier.valid?("C")      # => true (Chess first player)
+      #   Sashite::Sin::Identifier.valid?("c")      # => true (Chess second player)
+      #   Sashite::Sin::Identifier.valid?("CHESS")  # => false (multi-character)
+      #   Sashite::Sin::Identifier.valid?("1")      # => false (not ASCII letter)
       def self.valid?(sin_string)
         return false unless sin_string.is_a?(::String)
 
@@ -86,99 +176,179 @@ module Sashite
 
       # Convert the identifier to its SIN string representation
       #
+      # Returns the canonical SIN notation with proper case encoding for Player Assignment.
+      #
       # @return [String] SIN notation string (single ASCII letter)
-      # @example Display identifiers
-      #   identifier.to_s  # => "C" (first player, C family)
-      #   identifier.to_s  # => "c" (second player, C family)
-      #   identifier.to_s  # => "S" (first player, S family)
+      #
+      # @example Display identifiers in canonical SIN format
+      #   chess_first.to_s   # => "C" (Chess family, first player)
+      #   chess_second.to_s  # => "c" (Chess family, second player)
+      #   shogi_first.to_s   # => "S" (Shōgi family, first player)
       def to_s
-        letter.to_s
+        letter
       end
 
-      # Create a new identifier with opposite ownership (side)
+      # Get the letter representation combining Style Family and Player Assignment
+      #
+      # @return [String] letter representation with proper case encoding
+      #
+      # @example Letter representation with dual-purpose encoding
+      #   chess_first.letter   # => "C" (Chess family, first player)
+      #   chess_second.letter  # => "c" (Chess family, second player)
+      #   shogi_first.letter   # => "S" (Shōgi family, first player)
+      def letter
+        first_player? ? family.to_s.upcase : family.to_s.downcase
+      end
+
+      # Create a new identifier with opposite Player Assignment (flip sides)
+      #
+      # Transforms Player Assignment while maintaining Style Family:
+      # - First player → Second player (uppercase → lowercase)
+      # - Second player → First player (lowercase → uppercase)
       #
-      # @return [Identifier] new immutable identifier instance with flipped side
-      # @example Flip player sides
-      #   identifier.flip  # (:C, :first) => (:c, :second)
+      # @return [Identifier] new immutable identifier instance with flipped Player Assignment
+      #
+      # @example Flip Player Assignment within same Style Family
+      #   chess_white = Sashite::Sin::Identifier.parse("C")
+      #   chess_black = chess_white.flip  # => Family=:C, Side=:second
+      #
+      #   shogi_sente = Sashite::Sin::Identifier.parse("S")
+      #   shogi_gote  = shogi_sente.flip  # => Family=:S, Side=:second
       def flip
-        new_letter = first_player? ? letter.to_s.downcase.to_sym : letter.to_s.upcase.to_sym
-        self.class.new(new_letter, opposite_side)
+        self.class.new(family, opposite_side)
       end
 
-      # Create a new identifier with a different letter (keeping same side)
+      # Create a new identifier with a different Style Family (keeping same Player Assignment)
+      #
+      # Changes the Style Family component while preserving Player Assignment.
+      #
+      # @param new_family [Symbol] new Style Family (:A to :Z)
+      # @return [Identifier] new immutable identifier instance with different Style Family
       #
-      # @param new_letter [Symbol] new letter (single ASCII letter as symbol)
-      # @return [Identifier] new immutable identifier instance with different letter
-      # @example Change identifier letter
-      #   identifier.with_letter(:S)  # (:C, :first) => (:S, :first)
-      def with_letter(new_letter)
-        self.class.validate_letter(new_letter)
-        return self if letter == new_letter
+      # @example Change Style Family while preserving Player Assignment
+      #   chess_white = Sashite::Sin::Identifier.parse("C")     # Chess, first player
+      #   shogi_white = chess_white.with_family(:S)             # Shōgi, first player
+      #
+      #   chess_black = Sashite::Sin::Identifier.parse("c")     # Chess, second player
+      #   xiangqi_black = chess_black.with_family(:X)           # Xiangqi, second player
+      def with_family(new_family)
+        self.class.validate_family(new_family)
+        return self if family == new_family
 
-        # Ensure the new letter has the correct case for the current side
-        adjusted_letter = first_player? ? new_letter.to_s.upcase.to_sym : new_letter.to_s.downcase.to_sym
-        self.class.new(adjusted_letter, side)
+        self.class.new(new_family, side)
       end
 
-      # Create a new identifier with a different side (keeping same letter family)
+      # Create a new identifier with a different Player Assignment (keeping same Style Family)
+      #
+      # Changes the Player Assignment component while preserving Style Family.
       #
       # @param new_side [Symbol] :first or :second
-      # @return [Identifier] new immutable identifier instance with different side
-      # @example Change player side
-      #   identifier.with_side(:second)  # (:C, :first) => (:c, :second)
+      # @return [Identifier] new immutable identifier instance with different Player Assignment
+      #
+      # @example Change Player Assignment within same Style Family
+      #   chess_white = Sashite::Sin::Identifier.parse("C")     # Chess, first player
+      #   chess_black = chess_white.with_side(:second)          # Chess, second player
+      #
+      #   shogi_sente = Sashite::Sin::Identifier.parse("S")     # Shōgi, first player
+      #   shogi_gote  = shogi_sente.with_side(:second)          # Shōgi, second player
       def with_side(new_side)
         self.class.validate_side(new_side)
         return self if side == new_side
 
-        # Adjust letter case for the new side
-        new_letter = new_side == FIRST_PLAYER ? letter.to_s.upcase.to_sym : letter.to_s.downcase.to_sym
-        self.class.new(new_letter, new_side)
+        self.class.new(family, new_side)
       end
 
       # Check if the identifier belongs to the first player
       #
-      # @return [Boolean] true if first player
+      # @return [Boolean] true if first player (uppercase letter)
+      #
+      # @example Player identification
+      #   Sashite::Sin::Identifier.parse("C").first_player?   # => true
+      #   Sashite::Sin::Identifier.parse("c").first_player?   # => false
       def first_player?
         side == FIRST_PLAYER
       end
 
       # Check if the identifier belongs to the second player
       #
-      # @return [Boolean] true if second player
+      # @return [Boolean] true if second player (lowercase letter)
+      #
+      # @example Player identification
+      #   Sashite::Sin::Identifier.parse("c").second_player?  # => true
+      #   Sashite::Sin::Identifier.parse("C").second_player?  # => false
       def second_player?
         side == SECOND_PLAYER
       end
 
-      # Check if this identifier has the same letter family as another
+      # Check if this identifier has the same Style Family as another
+      #
+      # Compares the Style Family component, ignoring Player Assignment.
+      # This is useful for identifying pieces from the same game tradition in cross-style scenarios.
       #
       # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if both identifiers use the same letter family (case-insensitive)
-      # @example Compare identifier letter families
-      #   c_identifier.same_letter?(C_identifier)  # (:c, :second) and (:C, :first) => true
-      def same_letter?(other)
+      # @return [Boolean] true if both identifiers use the same Style Family
+      #
+      # @example Compare Style Families across different Player Assignments
+      #   chess_white = Sashite::Sin::Identifier.parse("C")  # Chess, first player
+      #   chess_black = Sashite::Sin::Identifier.parse("c")  # Chess, second player
+      #   shogi_white = Sashite::Sin::Identifier.parse("S")  # Shōgi, first player
+      #
+      #   chess_white.same_family?(chess_black)  # => true (both Chess family)
+      #   chess_white.same_family?(shogi_white)  # => false (different families)
+      def same_family?(other)
         return false unless other.is_a?(self.class)
 
-        letter.to_s.upcase == other.letter.to_s.upcase
+        family == other.family
       end
 
-      # Check if this identifier belongs to the same side as another
+      # Check if this identifier belongs to the same Player Assignment as another
+      #
+      # Compares the Player Assignment component of identifiers across different Style Families.
+      # This is useful for grouping pieces by controlling player in multi-style games.
       #
       # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if both identifiers belong to the same side
+      # @return [Boolean] true if both identifiers belong to the same Player Assignment
+      #
+      # @example Compare Player Assignments across different Style Families
+      #   chess_white = Sashite::Sin::Identifier.parse("C")  # Chess, first player
+      #   shogi_white = Sashite::Sin::Identifier.parse("S")  # Shōgi, first player
+      #   chess_black = Sashite::Sin::Identifier.parse("c")  # Chess, second player
+      #
+      #   chess_white.same_side?(shogi_white)  # => true (both first player)
+      #   chess_white.same_side?(chess_black)  # => false (different players)
       def same_side?(other)
         return false unless other.is_a?(self.class)
 
         side == other.side
       end
 
+      # Compatibility alias for same_family? to maintain API consistency
+      #
+      # @deprecated Use {#same_family?} instead for clearer semantics
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if both identifiers use the same Style Family
+      def same_letter?(other)
+        same_family?(other)
+      end
+
       # Custom equality comparison
       #
+      # Two identifiers are equal if they have identical Family and Side attributes.
+      #
       # @param other [Object] object to compare with
-      # @return [Boolean] true if both objects are identifiers with identical letter and side
+      # @return [Boolean] true if both objects are identifiers with identical Family and Side
+      #
+      # @example Equality comparison
+      #   id1 = Sashite::Sin::Identifier.parse("C")
+      #   id2 = Sashite::Sin::Identifier.parse("C")
+      #   id3 = Sashite::Sin::Identifier.parse("c")
+      #
+      #   id1 == id2  # => true (identical Family and Side)
+      #   id1 == id3  # => false (different Player Assignment)
       def ==(other)
         return false unless other.is_a?(self.class)
 
-        letter == other.letter && side == other.side
+        family == other.family && side == other.side
       end
 
       # Alias for == to ensure Set functionality works correctly
@@ -186,22 +356,22 @@ module Sashite
 
       # Custom hash implementation for use in collections
       #
-      # @return [Integer] hash value based on class, letter, and side
+      # @return [Integer] hash value based on class, Family, and Side
       def hash
-        [self.class, letter, side].hash
+        [self.class, family, side].hash
       end
 
-      # Validate that the letter is a valid single ASCII letter symbol
+      # Validate that the family is a valid Style Family symbol
       #
-      # @param letter [Symbol] the letter to validate
+      # @param family [Symbol] the family to validate
       # @raise [ArgumentError] if invalid
-      def self.validate_letter(letter)
-        return if valid_letter?(letter)
+      def self.validate_family(family)
+        return if VALID_FAMILIES.include?(family)
 
-        raise ::ArgumentError, format(ERROR_INVALID_LETTER, letter.inspect)
+        raise ::ArgumentError, format(ERROR_INVALID_FAMILY, family.inspect)
       end
 
-      # Validate that the side is a valid symbol
+      # Validate that the side follows SIN two-player constraint
       #
       # @param side [Symbol] the side to validate
       # @raise [ArgumentError] if invalid
@@ -211,21 +381,7 @@ module Sashite
         raise ::ArgumentError, format(ERROR_INVALID_SIDE, side.inspect)
       end
 
-      # Check if a letter is valid (single ASCII letter symbol)
-      #
-      # @param letter [Object] the letter to check
-      # @return [Boolean] true if valid
-      def self.valid_letter?(letter)
-        return false unless letter.is_a?(::Symbol)
-
-        letter_string = letter.to_s
-        return false if letter_string.empty?
-
-        # Must be exactly one ASCII letter
-        letter_string.match?(SIN_PATTERN)
-      end
-
-      # Validate SIN string format
+      # Validate SIN string format against specification grammar
       #
       # @param string [String] string to validate
       # @raise [ArgumentError] if string doesn't match SIN pattern
@@ -235,11 +391,11 @@ module Sashite
         raise ::ArgumentError, format(ERROR_INVALID_SIN, string)
       end
 
-      private_class_method :valid_letter?, :validate_sin_string
+      private_class_method :validate_sin_string
 
       private
 
-      # Get the opposite side
+      # Get the opposite Player Assignment
       #
       # @return [Symbol] the opposite side
       def opposite_side

data/lib/sashite/sin.rb

@@ -5,22 +5,118 @@ require_relative "sin/identifier"
 module Sashite
   # SIN (Style Identifier Notation) implementation for Ruby
   #
-  # Provides a rule-agnostic format for identifying styles in abstract strategy board games.
-  # SIN uses single ASCII letters with case-based side encoding, enabling clear
-  # distinction between different style families in multi-style gaming environments.
-  #
-  # Format: <style-letter>
-  # - Uppercase letter: First player styles (A, B, C, ..., Z)
-  # - Lowercase letter: Second player styles (a, b, c, ..., z)
-  # - Single character only: Each SIN identifier is exactly one ASCII letter
-  #
-  # Examples:
-  #   "C"  - First player, C style family
-  #   "c"  - Second player, C style family
-  #   "S"  - First player, S style family
-  #   "s"  - Second player, S style family
-  #
-  # @see https://sashite.dev/specs/sin/1.0.0/
+  # Provides a compact, ASCII-based format for identifying styles in abstract strategy board games.
+  # SIN uses single-character identifiers with case encoding to represent both style identity
+  # and player assignment simultaneously.
+  #
+  # ## Concept
+  #
+  # SIN addresses the fundamental need to identify which style system governs piece behavior
+  # while simultaneously indicating which player controls pieces of that style. In cross-style
+  # scenarios where different players use different game traditions, this dual encoding becomes
+  # essential for unambiguous piece identification.
+  #
+  # ## Dual-Purpose Encoding
+  #
+  # Each SIN identifier serves two functions:
+  # - **Style Family Identification**: The letter choice indicates which rule system applies
+  # - **Player Assignment**: The letter case indicates which player uses this style as their native system
+  #
+  # ## Format Specification
+  #
+  # Structure: `<style-letter>`
+  #
+  # Grammar (BNF):
+  #   <sin> ::= <uppercase-letter> | <lowercase-letter>
+  #   <uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
+  #   <lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
+  #
+  # Regular Expression: `/\A[A-Za-z]\z/`
+  #
+  # ## Style Attribute Mapping
+  #
+  # SIN encodes style attributes using the following correspondence:
+  #
+  # | Style Attribute | SIN Encoding | Examples |
+  # |-----------------|--------------|----------|
+  # | **Letter** | Single ASCII character | `C`, `c`, `S`, `s` |
+  # | **Style Family** | ASCII letter choice (A-Z) | `C`/`c` = Chess, `S`/`s` = Shōgi |
+  # | **Player Assignment** | Letter case | `C` = First player, `c` = Second player |
+  #
+  # The **Letter** attribute combines two distinct semantic components:
+  # - **Style Family**: The underlying ASCII character (A-Z), representing the game tradition or rule system
+  # - **Player Assignment**: The case of the character (uppercase/lowercase), representing which player uses this style
+  #
+  # ## Character Selection Conventions
+  #
+  # ### Primary Convention: First Letter
+  # By convention, SIN identifiers should preferably use the **first letter** of the corresponding SNN style name:
+  # - `Chess` → `C`/`c`
+  # - `Shogi` → `S`/`s`
+  # - `Xiangqi` → `X`/`x`
+  # - `Makruk` → `M`/`m`
+  # - `Janggi` → `J`/`j`
+  #
+  # ### Collision Resolution
+  # When multiple styles would claim the same first letter, systematic collision resolution applies
+  # using sequential letter selection from the SNN name until a unique identifier is found.
+  #
+  # ### Compatibility Groups
+  # Styles requiring incompatible board structures can safely share SIN letters since they
+  # cannot coexist in the same match.
+  #
+  # ## System Constraints
+  #
+  # - **26 possible identifiers** per player using ASCII letters
+  # - **Exactly 2 players** through case distinction:
+  #   - First player: Uppercase letters (`A-Z`)
+  #   - Second player: Lowercase letters (`a-z`)
+  # - **Single character** per style-player combination
+  # - **Rule-agnostic** - independent of specific game mechanics
+  #
+  # ## Examples
+  #
+  # ### Traditional Game Styles
+  #
+  #   # Chess (8×8)
+  #   chess_white = Sashite::Sin.parse("C")    # First player (White pieces)
+  #   chess_black = Sashite::Sin.parse("c")    # Second player (Black pieces)
+  #
+  #   # Shōgi (9×9)
+  #   shogi_sente = Sashite::Sin.parse("S")    # First player (Sente 先手)
+  #   shogi_gote  = Sashite::Sin.parse("s")    # Second player (Gote 後手)
+  #
+  #   # Xiangqi (9×10)
+  #   xiangqi_red   = Sashite::Sin.parse("X")  # First player (Red pieces)
+  #   xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)
+  #
+  # ### Cross-Style Scenarios
+  #
+  #   # Chess vs. Ōgi Match (both 8×8 compatible)
+  #   chess_style = Sashite::Sin.parse("C")    # Chess style, first player
+  #   ogi_style   = Sashite::Sin.parse("o")    # Ōgi style, second player
+  #
+  # ### All 26 Letters
+  #
+  #   # First player identifiers (A-Z)
+  #   ("A".."Z").each { |letter| Sashite::Sin.parse(letter).first_player? }  # => all true
+  #
+  #   # Second player identifiers (a-z)
+  #   ("a".."z").each { |letter| Sashite::Sin.parse(letter).second_player? } # => all true
+  #
+  # ## Design Properties
+  #
+  # - **ASCII compatibility**: Maximum portability across systems
+  # - **Rule-agnostic**: Independent of specific game mechanics
+  # - **Minimal overhead**: Single character per style-player combination
+  # - **Flexible collision resolution**: Systematic approaches for identifier conflicts
+  # - **Semantic clarity**: Distinct concepts for Letter (Style Family + Player Assignment)
+  # - **SNN coordination**: Works harmoniously with formal style naming
+  # - **Context-aware**: Adapts to avoid conflicts within specific game scenarios
+  #
+  # @see https://sashite.dev/specs/sin/1.0.0/ SIN Specification v1.0.0
+  # @see https://sashite.dev/specs/sin/1.0.0/examples/ SIN Examples
+  # @see https://sashite.dev/specs/snn/ Style Name Notation (SNN)
   module Sin
     # Check if a string is a valid SIN notation
     #
@@ -28,38 +124,65 @@ module Sashite
     # @return [Boolean] true if valid SIN, false otherwise
     #
     # @example Validate various SIN formats
-    #   Sashite::Sin.valid?("C") # => true
-    #   Sashite::Sin.valid?("c") # => true
-    #   Sashite::Sin.valid?("CHESS") # => false (multi-character)
-    #   Sashite::Sin.valid?("1") # => false (not a letter)
+    #   Sashite::Sin.valid?("C")      # => true (Chess first player)
+    #   Sashite::Sin.valid?("c")      # => true (Chess second player)
+    #   Sashite::Sin.valid?("S")      # => true (Shōgi first player)
+    #   Sashite::Sin.valid?("s")      # => true (Shōgi second player)
+    #   Sashite::Sin.valid?("CHESS")  # => false (multi-character)
+    #   Sashite::Sin.valid?("1")      # => false (not a letter)
+    #   Sashite::Sin.valid?("")       # => false (empty string)
     def self.valid?(sin_string)
       Identifier.valid?(sin_string)
     end
 
     # Parse an SIN string into an Identifier object
     #
-    # @param sin_string [String] SIN notation string
+    # The identifier will have both letter and side attributes inferred from the case:
+    # - Uppercase letter → first player (:first)
+    # - Lowercase letter → second player (:second)
+    #
+    # @param sin_string [String] SIN notation string (single ASCII letter)
     # @return [Sin::Identifier] parsed identifier object with letter and side attributes
     # @raise [ArgumentError] if the SIN string is invalid
-    # @example Parse different SIN formats
-    #   Sashite::Sin.parse("C") # => #<Sin::Identifier letter=:C side=:first>
-    #   Sashite::Sin.parse("c") # => #<Sin::Identifier letter=:c side=:second>
-    #   Sashite::Sin.parse("S") # => #<Sin::Identifier letter=:S side=:first>
+    #
+    # @example Parse different SIN formats with dual-purpose encoding
+    #   Sashite::Sin.parse("C")  # => #<Sashite::Sin::Identifier @family=:C, @side=:first>
+    #   Sashite::Sin.parse("c")  # => #<Sashite::Sin::Identifier @family=:C, @side=:second>
+    #   Sashite::Sin.parse("S")  # => #<Sashite::Sin::Identifier @family=:S, @side=:first>
+    #   Sashite::Sin.parse("s")  # => #<Sashite::Sin::Identifier @family=:S, @side=:second>
+    #
+    # @example Traditional game styles
+    #   chess_white = Sashite::Sin.parse("C")  # Chess, first player (White)
+    #   chess_black = Sashite::Sin.parse("c")  # Chess, second player (Black)
+    #   shogi_sente = Sashite::Sin.parse("S")  # Shōgi, first player (Sente)
+    #   shogi_gote  = Sashite::Sin.parse("s")  # Shōgi, second player (Gote)
     def self.parse(sin_string)
       Identifier.parse(sin_string)
     end
 
-    # Create a new identifier instance
+    # Create a new identifier instance with canonical representation
     #
-    # @param letter [Symbol] style letter (single ASCII letter as symbol)
+    # Ensures the letter case matches the specified side:
+    # - :first side → uppercase letter
+    # - :second side → lowercase letter
+    #
+    # @param family [Symbol] style family (:A to :Z representing Style Family)
     # @param side [Symbol] player side (:first or :second)
     # @return [Sin::Identifier] new immutable identifier instance
     # @raise [ArgumentError] if parameters are invalid
-    # @example Create identifiers directly
-    #   Sashite::Sin.identifier(:C, :first)  # => #<Sin::Identifier letter=:C side=:first>
-    #   Sashite::Sin.identifier(:s, :second) # => #<Sin::Identifier letter=:s side=:second>
-    def self.identifier(letter, side)
-      Identifier.new(letter, side)
+    #
+    # @example Create identifiers with family and side separation
+    #   Sashite::Sin.identifier(:C, :first)   # => #<Sashite::Sin::Identifier @family=:C, @side=:first>
+    #   Sashite::Sin.identifier(:C, :second)  # => #<Sashite::Sin::Identifier @family=:C, @side=:second>
+    #
+    # @example Style family and player assignment
+    #   chess_first  = Sashite::Sin.identifier(:C, :first)   # Chess family, first player
+    #   chess_second = Sashite::Sin.identifier(:C, :second)  # Chess family, second player
+    #
+    #   chess_first.same_family?(chess_second)   # => true (same style family)
+    #   chess_first.same_side?(chess_second)     # => false (different players)
+    def self.identifier(family, side)
+      Identifier.new(family, side)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-sin
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato