sashite-snn 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fb3b57b1f252e95f7e7d3e8484d6729b90ca6f13dfd19705c9ac61d6095cf25
-  data.tar.gz: 296ec73c256baf0ea7999b74b7933b0e95f92b2b7488e3d5efb69b43b7132951
+  metadata.gz: 1528b909fb1159a1b9d3fb06e4b62114efa110d991226945024f442fb08501e9
+  data.tar.gz: 3c6c44c3d69d1eacad6141d9309a27e5972dde45067bc8272e9584ed6cfc56ee
 SHA512:
-  metadata.gz: 1e7b8270ca459703a6bd41f47424af55452f8c287567abc8bdf0e85acc69914f20a1830361ce10e3f0e157c137e3f31f60149481274b24e6dedb597d109927d6
-  data.tar.gz: 9a684bb46685f7a77fbade6caaf2d642f31a6b31b142e1fb5a47512e8a4133fa50adf0f24c8b551d87c67232c23db6c5436e95d819a38ac72e069f37da63aff5
+  metadata.gz: fc20688ee514ec76125132aba5b121aa4b705230eb716f2abee6c5c1a88978aadfa52bf8cfa1c870315284050808f5fe5903a5e141c760af92f7aaca9bac82d5
+  data.tar.gz: b44e7af48ae53d52ca2b1961831b5eca677c2b8182589062139af966d3e960f0638720fba33c7e9099b6a8fe9424124f49386e3c9b025e71f93edfb797e9e558

data/README.md

@@ -9,9 +9,13 @@
 
 ## What is SNN?
 
-SNN (Style Name Notation) provides a compact, ASCII-based format for identifying **styles** in abstract strategy board games. SNN uses single-character identifiers with case encoding to represent both style identity and player assignment simultaneously.
+SNN (Style Name Notation) is a **foundational**, human-readable naming system for identifying game styles in abstract strategy board games. SNN serves as a primitive building block using descriptive alphabetic names with case encoding to represent style identity and player assignment.
 
-This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/), providing a rule-agnostic notation system for style identification in board games.
+Each SNN name is a case-consistent alphabetic identifier where:
+- **Uppercase names** (e.g., `CHESS`, `SHOGI`) represent the **first player's** style
+- **Lowercase names** (e.g., `chess`, `shogi`) represent the **second player's** style
+
+This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) as a foundational primitive with no dependencies.
 
 ## Installation
 
@@ -26,399 +30,320 @@ Or install manually:
 gem install sashite-snn
 ```
 
-## Usage
-
-### Basic Operations
+## Quick Start
 
 ```ruby
 require "sashite/snn"
 
-# Parse SNN strings into style objects
-style = Sashite::Snn.parse("C")           # => #<Snn::Style letter=:C side=:first>
-style.to_s                                # => "C"
-style.letter                              # => :C
-style.side                                # => :first
+# Parse SNN strings into style name objects
+name = Sashite::Snn.parse("SHOGI")             # => #<Snn::Name value="SHOGI">
+name.to_s                                      # => "SHOGI"
+name.value                                     # => "SHOGI"
 
-# Create styles directly
-style = Sashite::Snn.style(:C, :first)           # => #<Snn::Style letter=:C side=:first>
-style = Sashite::Snn::Style.new(:c, :second)     # => #<Snn::Style letter=:c side=:second>
+# Create from string or symbol
+name = Sashite::Snn.name("CHESS")              # => #<Snn::Name value="CHESS">
+name = Sashite::Snn::Name.new(:xiangqi)        # => #<Snn::Name value="xiangqi">
 
 # Validate SNN strings
-Sashite::Snn.valid?("C")                 # => true
-Sashite::Snn.valid?("c")                 # => true
-Sashite::Snn.valid?("1")                 # => false (not a letter)
-Sashite::Snn.valid?("CC")                # => false (not single character)
+Sashite::Snn.valid?("MAKRUK")                  # => true
+Sashite::Snn.valid?("shogi")                   # => true
+Sashite::Snn.valid?("Chess")                   # => false (mixed case)
+Sashite::Snn.valid?("Chess960")                # => false (contains digits)
 ```
 
-### Style Transformations
-
-```ruby
-# All transformations return new immutable instances
-style = Sashite::Snn.parse("C")
+## SNN Format
 
-# Flip player assignment
-flipped = style.flip                      # => #<Snn::Style letter=:c side=:second>
-flipped.to_s                              # => "c"
+An SNN string consists of alphabetic characters only, all in the same case:
 
-# Change letter
-changed = style.with_letter(:S)           # => #<Snn::Style letter=:S side=:first>
-changed.to_s                              # => "S"
-
-# Change side
-other_side = style.with_side(:second)     # => #<Snn::Style letter=:c side=:second>
-other_side.to_s                           # => "c"
-
-# Chain transformations
-result = style.flip.with_letter(:M)       # => #<Snn::Style letter=:m side=:second>
-result.to_s                               # => "m"
 ```
-
-### Player and Style Queries
-
-```ruby
-style = Sashite::Snn.parse("C")
-opposite = Sashite::Snn.parse("s")
-
-# Player identification
-style.first_player?                       # => true
-style.second_player?                      # => false
-opposite.first_player?                    # => false
-opposite.second_player?                   # => true
-
-# Letter comparison
-chess1 = Sashite::Snn.parse("C")
-chess2 = Sashite::Snn.parse("c")
-shogi = Sashite::Snn.parse("S")
-
-chess1.same_letter?(chess2)               # => true (both use letter C)
-chess1.same_side?(shogi)                  # => true (both first player)
-chess1.same_letter?(shogi)                # => false (different letters)
+<alphabetic-name>
 ```
 
-### Style Collections
-
-```ruby
-# Working with multiple styles
-styles = %w[C c S s M m].map { |snn| Sashite::Snn.parse(snn) }
-
-# Filter by player
-first_player_styles = styles.select(&:first_player?)
-first_player_styles.map(&:to_s)          # => ["C", "S", "M"]
-
-# Group by letter family
-by_letter = styles.group_by { |s| s.letter.to_s.upcase }
-by_letter["C"].size                       # => 2 (both C and c)
-
-# Find specific combinations
-chess_styles = styles.select { |s| s.letter.to_s.upcase == "C" }
-chess_styles.map(&:to_s)                  # => ["C", "c"]
-```
+**Examples:**
+- `CHESS` — Chess style for first player
+- `chess` — Chess style for second player
+- `SHOGI` — Shōgi style for first player
+- `shogi` — Shōgi style for second player
 
 ## Format Specification
 
 ### Structure
+
 ```
-<style-letter>
+<alphabetic-name>
 ```
 
+Where the name directly represents the style identity and player assignment through case.
+
 ### Grammar (BNF)
+
 ```bnf
-<snn> ::= <uppercase-letter> | <lowercase-letter>
+<snn> ::= <uppercase-name> | <lowercase-name>
+
+<uppercase-name> ::= <uppercase-letter>+
+<lowercase-name> ::= <lowercase-letter>+
 
 <uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
 <lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
 ```
 
 ### Regular Expression
+
 ```ruby
-/\A[A-Za-z]\z/
+/\A([A-Z]+|[a-z]+)\z/
 ```
 
-### Style Attribute Mapping
+### Constraints
 
-| Style Attribute | SNN Encoding | Examples |
-|-----------------|--------------|----------|
-| **Style Family** | Letter choice | `C`/`c` = Chess family |
-| **Player Assignment** | Letter case | `C` = First player, `c` = Second player |
+1. **Case consistency**: All letters must be either uppercase OR lowercase
+2. **Alphabetic only**: Only ASCII letters allowed (no digits, no special characters)
+3. **Direct assignment**: Names represent styles through explicit association
 
-## Game Examples
+## API Reference
 
-The SNN specification is rule-agnostic and does not define specific letter assignments. However, here are common usage patterns:
+### Module Methods
 
-### Traditional Game Families
+#### `Sashite::Snn.valid?(string)`
 
-```ruby
-# Chess family styles
-chess_white = Sashite::Snn.parse("C")    # First player, Chess family
-chess_black = Sashite::Snn.parse("c")    # Second player, Chess family
+Returns `true` if the string is valid SNN notation.
 
-# Shōgi family styles
-shogi_sente = Sashite::Snn.parse("S")    # First player, Shōgi family
-shogi_gote = Sashite::Snn.parse("s")     # Second player, Shōgi family
+- **Parameter**: `string` (String) - String to validate
+- **Returns**: `Boolean` - `true` if valid, `false` otherwise
 
-# Xiangqi family styles
-xiangqi_red = Sashite::Snn.parse("X")    # First player, Xiangqi family
-xiangqi_black = Sashite::Snn.parse("x")  # Second player, Xiangqi family
+```ruby
+Sashite::Snn.valid?("CHESS")      # => true
+Sashite::Snn.valid?("shogi")      # => true
+Sashite::Snn.valid?("Chess")      # => false (mixed case)
+Sashite::Snn.valid?("CHESS960")   # => false (contains digits)
+Sashite::Snn.valid?("3DChess")    # => false (starts with digit)
 ```
 
-### Cross-Style Scenarios
+#### `Sashite::Snn.parse(string)`
 
-```ruby
-# Different families in one match
-def create_hybrid_match
-  [
-    Sashite::Snn.parse("C"),             # First player uses Chess family
-    Sashite::Snn.parse("s")              # Second player uses Shōgi family
-  ]
-end
+Parses an SNN string into a `Name` object.
 
-styles = create_hybrid_match
-styles[0].same_side?(styles[1])         # => false (different players)
-styles[0].same_letter?(styles[1])       # => false (different families)
-```
-
-### Variant Families
+- **Parameter**: `string` (String) - SNN notation string
+- **Returns**: `Name` - Immutable name object
+- **Raises**: `ArgumentError` if the string is invalid
 
 ```ruby
-# Different letters can represent variants within traditions
-makruk = Sashite::Snn.parse("M")        # Makruk (Thai Chess) family
-janggi = Sashite::Snn.parse("J")        # Janggi (Korean Chess) family
-ogi = Sashite::Snn.parse("O")           # Ōgi (王棋) family
-
-# Each family can have both players
-makruk_black = makruk.flip              # Second player Makruk
-makruk_black.to_s                       # => "m"
+name = Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
+name = Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
 ```
 
-## API Reference
+#### `Sashite::Snn.name(value)`
 
-### Main Module Methods
+Creates a new `Name` instance directly.
 
-- `Sashite::Snn.valid?(snn_string)` - Check if string is valid SNN notation
-- `Sashite::Snn.parse(snn_string)` - Parse SNN string into Style object
-- `Sashite::Snn.style(letter, side)` - Create style instance directly
+- **Parameter**: `value` (String, Symbol) - Style name to construct
+- **Returns**: `Name` - New name instance
+- **Raises**: `ArgumentError` if name format is invalid
 
-### Style Class
-
-#### Creation and Parsing
-- `Sashite::Snn::Style.new(letter, side)` - Create style instance
-- `Sashite::Snn::Style.parse(snn_string)` - Parse SNN string
+```ruby
+Sashite::Snn.name("XIANGQI")  # => #<Snn::Name value="XIANGQI">
+Sashite::Snn.name(:makruk)    # => #<Snn::Name value="makruk">
+```
 
-#### Attribute Access
-- `#letter` - Get style letter (symbol :A through :z)
-- `#side` - Get player side (:first or :second)
-- `#to_s` - Convert to SNN string representation
+### Name Object
 
-#### Player Queries
-- `#first_player?` - Check if first player style
-- `#second_player?` - Check if second player style
+The `Name` object is immutable and provides read-only access to the style name:
 
-#### Transformations (immutable - return new instances)
-- `#flip` - Switch player assignment
-- `#with_letter(new_letter)` - Create style with different letter
-- `#with_side(new_side)` - Create style with different side
+```ruby
+name = Sashite::Snn.parse("SHOGI")
 
-#### Comparison Methods
-- `#same_letter?(other)` - Check if same style letter (case-insensitive)
-- `#same_side?(other)` - Check if same player side
-- `#==(other)` - Full equality comparison
+name.value    # => "SHOGI"
+name.to_s     # => "SHOGI"
+name.frozen?  # => true
+```
 
-### Style Class Constants
+**Equality and hashing:**
+```ruby
+name1 = Sashite::Snn.parse("CHESS")
+name2 = Sashite::Snn.parse("CHESS")
+name3 = Sashite::Snn.parse("chess")
 
-- `Sashite::Snn::Style::FIRST_PLAYER` - Symbol for first player (:first)
-- `Sashite::Snn::Style::SECOND_PLAYER` - Symbol for second player (:second)
-- `Sashite::Snn::Style::VALID_SIDES` - Array of valid sides
-- `Sashite::Snn::Style::SNN_PATTERN` - Regular expression for SNN validation
+name1 == name2 # => true
+name1.hash == name2.hash # => true
+name1 == name3 # => false (different case = different player)
+```
 
-## Advanced Usage
+## Examples
 
-### Letter Case and Side Mapping
+### Traditional Chess Family
 
 ```ruby
-# SNN encodes player assignment through case
-upper_case_letters = ("A".."Z").map { |letter| Sashite::Snn.parse(letter) }
-lower_case_letters = ("a".."z").map { |letter| Sashite::Snn.parse(letter) }
+# First player styles (uppercase)
+chess = Sashite::Snn.parse("CHESS")      # Western Chess
+shogi = Sashite::Snn.parse("SHOGI")      # Japanese Chess
+xiangqi = Sashite::Snn.parse("XIANGQI")  # Chinese Chess
+makruk = Sashite::Snn.parse("MAKRUK")    # Thai Chess
+
+# Second player styles (lowercase)
+chess_p2 = Sashite::Snn.parse("chess")
+shogi_p2 = Sashite::Snn.parse("shogi")
+```
 
-# All uppercase letters are first player
-upper_case_letters.all?(&:first_player?)     # => true
+### Historical Games
 
-# All lowercase letters are second player
-lower_case_letters.all?(&:second_player?)    # => true
+```ruby
+chaturanga = Sashite::Snn.parse("CHATURANGA")  # Ancient Indian Chess
+shatranj = Sashite::Snn.parse("SHATRANJ")      # Medieval Islamic Chess
+```
 
-# Letter families are related by case
-letter_a_first = Sashite::Snn.parse("A")
-letter_a_second = Sashite::Snn.parse("a")
+### Modern Variants
 
-letter_a_first.same_letter?(letter_a_second)  # => true
-letter_a_first.same_side?(letter_a_second)    # => false
+```ruby
+raumschach = Sashite::Snn.parse("RAUMSCHACH")  # 3D Chess
+omega = Sashite::Snn.parse("OMEGA")            # Omega Chess
 ```
 
-### Immutable Transformations
+### Case Consistency
 
 ```ruby
-# All transformations return new instances
-original = Sashite::Snn.style(:C, :first)
-flipped = original.flip
-changed_letter = original.with_letter(:S)
-
-# Original style is never modified
-original.to_s                           # => "C" (unchanged)
-flipped.to_s                            # => "c"
-changed_letter.to_s                     # => "S"
-
-# Transformations can be chained
-result = original.flip.with_letter(:M).flip
-result.to_s                             # => "M"
+# Valid - all uppercase
+Sashite::Snn.valid?("CHESS")      # => true
+Sashite::Snn.valid?("XIANGQI")    # => true
+
+# Valid - all lowercase
+Sashite::Snn.valid?("shogi")      # => true
+Sashite::Snn.valid?("makruk")     # => true
+
+# Invalid - mixed case
+Sashite::Snn.valid?("Chess")      # => false
+Sashite::Snn.valid?("Shogi")      # => false
+Sashite::Snn.valid?("XiangQi")    # => false
+
+# Invalid - contains non-alphabetic characters
+Sashite::Snn.valid?("CHESS960")   # => false
+Sashite::Snn.valid?("GO9X9")      # => false
+Sashite::Snn.valid?("MINI_SHOGI") # => false
 ```
 
-### Game Configuration Management
+### Working with Names
 
 ```ruby
-class GameConfiguration
-  def initialize
-    @player_styles = {}
-  end
-
-  def set_player_style(player, letter)
-    side = player == :white ? :first : :second
-    @player_styles[player] = Sashite::Snn.style(letter, side)
-  end
-
-  def get_player_style(player)
-    @player_styles[player]
-  end
-
-  def cross_family_match?
-    return false if @player_styles.size < 2
-
-    styles = @player_styles.values
-    !styles.all? { |style| style.same_letter?(styles.first) }
-  end
-
-  def same_family_match?
-    !cross_family_match?
-  end
-end
-
-# Usage
-config = GameConfiguration.new
-config.set_player_style(:white, :C)    # Chess family, first player
-config.set_player_style(:black, :S)    # Shōgi family, second player
+# Create and compare
+name1 = Sashite::Snn.parse("SHOGI")
+name2 = Sashite::Snn.parse("SHOGI")
+name1 == name2 # => true
+
+# String and symbol inputs
+name1 = Sashite::Snn.name("XIANGQI")
+name2 = Sashite::Snn.name(:XIANGQI)
+name1 == name2 # => true
+
+# Immutability
+name = Sashite::Snn.parse("CHESS")
+name.frozen?        # => true
+name.value.frozen?  # => true
+```
 
-config.cross_family_match?             # => true
+### Collections
 
-white_style = config.get_player_style(:white)
-white_style.to_s                       # => "C"
+```ruby
+# Create a set of styles
+styles = %w[CHESS SHOGI XIANGQI MAKRUK].map { |n| Sashite::Snn.parse(n) }
+
+# Filter by prefix
+styles.select { |s| s.value.start_with?("X") }.map(&:to_s)
+# => ["XIANGQI"]
+
+# Use in hash
+style_map = {
+  Sashite::Snn.parse("CHESS") => "Western Chess",
+  Sashite::Snn.parse("SHOGI") => "Japanese Chess"
+}
 ```
 
-### Style Analysis
+## Relationship with SIN
 
-```ruby
-def analyze_styles(snns)
-  styles = snns.map { |snn| Sashite::Snn.parse(snn) }
-
-  {
-    total: styles.size,
-    by_side: styles.group_by(&:side),
-    by_letter: styles.group_by { |s| s.letter.to_s.upcase },
-    unique_letters: styles.map { |s| s.letter.to_s.upcase }.uniq.size,
-    cross_family: styles.map { |s| s.letter.to_s.upcase }.uniq.size > 1
-  }
-end
+**SNN and SIN are independent primitives** that serve complementary roles:
 
-snns = %w[C c S s X x]
-analysis = analyze_styles(snns)
-analysis[:by_side][:first].size        # => 3
-analysis[:unique_letters]              # => 3
-analysis[:cross_family]                # => true
-```
+- **SNN**: Human-readable, descriptive names (`CHESS`, `SHOGI`)
+- **SIN**: Compact, single-character identification (`C`, `S`)
 
-### Tournament Style Registry
+### Optional Correspondence
+
+While both specifications can be used independently, they may be related through:
+
+- **Mapping tables**: External context defining SNN ↔ SIN relationships
+- **Case consistency**: When mapped, case must be preserved (`CHESS` ↔ `C`, `chess` ↔ `c`)
 
 ```ruby
-class TournamentStyleRegistry
-  def initialize
-    @registered_styles = Set.new
-  end
-
-  def register_letter(letter)
-    # Register both sides of a letter family
-    first_player_style = Sashite::Snn.style(letter.to_s.upcase.to_sym, :first)
-    second_player_style = first_player_style.flip
-
-    @registered_styles.add(first_player_style)
-    @registered_styles.add(second_player_style)
-
-    [first_player_style, second_player_style]
-  end
-
-  def valid_pairing?(style1, style2)
-    @registered_styles.include?(style1) &&
-    @registered_styles.include?(style2) &&
-    !style1.same_side?(style2)
-  end
-
-  def available_styles_for_side(side)
-    @registered_styles.select { |style| style.side == side }
-  end
-
-  def supported_families
-    @registered_styles.map { |s| s.letter.to_s.upcase }.uniq.sort
-  end
-end
+# Example mapping (defined externally, not part of SNN)
+SNN_TO_SIN = {
+  "CHESS" => "C",
+  "chess" => "c",
+  "SHOGI" => "S",
+  "shogi" => "s"
+}
+
+# Multiple SNN names may map to the same SIN
+SNN_TO_SIN["CAPABLANCA"] = "C"  # Also maps to "C"
+SNN_TO_SIN["COURIER"] = "C"     # Also maps to "C"
+```
+
+### Important Notes
 
-# Usage
-registry = TournamentStyleRegistry.new
-registry.register_letter(:C)
-registry.register_letter(:S)
+1. **No dependency**: SNN does not depend on SIN, nor SIN on SNN
+2. **Bidirectional mapping requires context**: Converting between SNN and SIN requires external mapping information
+3. **Independent usage**: Systems may use SNN alone, SIN alone, or both with defined mappings
+4. **Multiple mappings**: One SNN name may correspond to multiple SIN characters in different contexts, and vice versa
 
-chess_white = Sashite::Snn.parse("C")
-shogi_black = Sashite::Snn.parse("s")
+## Error Handling
 
-registry.valid_pairing?(chess_white, shogi_black)  # => true
-registry.supported_families                        # => ["C", "S"]
+```ruby
+begin
+  name = Sashite::Snn.parse("Chess960")
+rescue ArgumentError => e
+  warn "Invalid SNN: #{e.message}"
+  # => "Invalid SNN string: \"Chess960\""
+end
 ```
 
-## Protocol Mapping
+### Common Errors
 
-Following the [Sashité Protocol](https://sashite.dev/protocol/):
+```ruby
+# Mixed case
+Sashite::Snn.parse("Chess")
+# => ArgumentError: Invalid SNN string: "Chess"
 
-| Protocol Attribute | SNN 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 |
+# Contains digits
+Sashite::Snn.parse("CHESS960")
+# => ArgumentError: Invalid SNN string: "CHESS960"
 
-## System Constraints
+# Contains special characters
+Sashite::Snn.parse("MINI_SHOGI")
+# => ArgumentError: Invalid SNN string: "MINI_SHOGI"
 
-- **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
+# Empty string
+Sashite::Snn.parse("")
+# => ArgumentError: Invalid SNN string: ""
+```
 
-## Design Properties
+## Design Principles
 
-- **ASCII compatibility**: Maximum portability across systems
+- **Human-readable**: Descriptive names for better usability
+- **Case-consistent**: Visual distinction between players through case
+- **Foundational primitive**: Serves as building block for formal style identification
 - **Rule-agnostic**: Independent of specific game mechanics
-- **Minimal overhead**: Single character per style-player combination
-- **Canonical representation**: Each style-player combination has exactly one SNN identifier
-- **Immutable**: All style instances are frozen and transformations return new objects
-- **Functional**: Pure functions with no side effects
+- **Self-contained**: No external dependencies
+- **Immutable**: All objects are frozen and thread-safe
+- **Canonical**: Each style has one valid representation per context
 
-## Related Specifications
+## Properties
 
-- [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) - Complete technical specification
-- [SNN Examples](https://sashite.dev/specs/snn/1.0.0/examples/) - Practical implementation examples
-- [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
+- **Purely functional**: Immutable data structures, no side effects
+- **Specification compliant**: Strict adherence to [SNN v1.0.0](https://sashite.dev/specs/snn/1.0.0/)
+- **Minimal API**: Simple validation, parsing, and comparison
+- **Universal**: Supports any abstract strategy board game style
+- **No dependencies**: Foundational primitive requiring no external gems
 
 ## Documentation
 
-- [Official SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/)
-- [SNN Examples Documentation](https://sashite.dev/specs/snn/1.0.0/examples/)
-- [Sashité Protocol Foundation](https://sashite.dev/protocol/)
-- [API Documentation](https://rubydoc.info/github/sashite/snn.rb/main)
+- [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) — Complete technical specification
+- [SNN Examples](https://sashite.dev/specs/snn/1.0.0/examples/) — Comprehensive examples
+- [API Documentation](https://rubydoc.info/github/sashite/snn.rb/main) — Full API reference
 
 ## Development
 

data/lib/sashite/snn/name.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Snn
+    # Represents a style name in SNN (Style Name Notation) format.
+    #
+    # SNN provides a foundational naming system for abstract strategy game styles.
+    # Each name must consist of alphabetic characters only, all in the same case
+    # (either all uppercase or all lowercase).
+    #
+    # Case encoding:
+    #   - UPPERCASE names represent the first player's style
+    #   - lowercase names represent the second player's style
+    #
+    # Constraints:
+    #   - Alphabetic characters only (A-Z or a-z)
+    #   - Case consistency required (all uppercase OR all lowercase)
+    #   - No digits, no special characters, no mixed case
+    #
+    # All instances are immutable.
+    #
+    # @example Valid names
+    #   Sashite::Snn::Name.new("CHESS")    # => #<Snn::Name value="CHESS">
+    #   Sashite::Snn::Name.new("shogi")    # => #<Snn::Name value="shogi">
+    #   Sashite::Snn::Name.new("XIANGQI")  # => #<Snn::Name value="XIANGQI">
+    #
+    # @example Invalid names
+    #   Sashite::Snn::Name.new("Chess")    # => ArgumentError (mixed case)
+    #   Sashite::Snn::Name.new("CHESS960") # => ArgumentError (contains digits)
+    #   Sashite::Snn::Name.new("GO9X9")    # => ArgumentError (contains digits)
+    class Name
+      # SNN validation pattern matching the specification
+      # Format: All uppercase OR all lowercase alphabetic characters
+      SNN_PATTERN = /\A([A-Z]+|[a-z]+)\z/
+
+      # Error message for invalid SNN strings
+      ERROR_INVALID_NAME = "Invalid SNN string: %s"
+
+      # @return [String] the canonical style name
+      attr_reader :value
+
+      # Create a new style name instance
+      #
+      # The name must follow SNN format rules: all uppercase or all lowercase
+      # alphabetic characters only. No digits, special characters, or mixed case.
+      #
+      # @param name [String, Symbol] the style name (e.g., "SHOGI", :chess)
+      # @raise [ArgumentError] if the name does not match SNN pattern
+      #
+      # @example Create valid names
+      #   Sashite::Snn::Name.new("CHESS")    # First player Chess
+      #   Sashite::Snn::Name.new("shogi")    # Second player Shōgi
+      #   Sashite::Snn::Name.new(:XIANGQI)   # First player Xiangqi
+      #
+      # @example Invalid names raise errors
+      #   Sashite::Snn::Name.new("Chess")    # Mixed case
+      #   Sashite::Snn::Name.new("CHESS960") # Contains digits
+      def initialize(name)
+        string_value = name.to_s
+        self.class.validate_format(string_value)
+
+        @value = string_value.freeze
+        freeze
+      end
+
+      # Parse an SNN string into a Name object
+      #
+      # This is an alias for the constructor, provided for consistency
+      # with other Sashité specifications.
+      #
+      # @param string [String] the SNN-formatted style name
+      # @return [Name] a new Name instance
+      # @raise [ArgumentError] if the string is invalid
+      #
+      # @example Parse valid names
+      #   Sashite::Snn::Name.parse("SHOGI") # => #<Snn::Name value="SHOGI">
+      #   Sashite::Snn::Name.parse("chess") # => #<Snn::Name value="chess">
+      def self.parse(string)
+        new(string)
+      end
+
+      # Check whether the given string is a valid SNN name
+      #
+      # Valid SNN strings must:
+      #   - Contain only alphabetic characters (A-Z or a-z)
+      #   - Have consistent case (all uppercase OR all lowercase)
+      #   - Contain at least one character
+      #
+      # @param string [String] input string to validate
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example Valid names
+      #   Sashite::Snn::Name.valid?("CHESS")    # => true
+      #   Sashite::Snn::Name.valid?("shogi")    # => true
+      #   Sashite::Snn::Name.valid?("XIANGQI")  # => true
+      #
+      # @example Invalid names
+      #   Sashite::Snn::Name.valid?("Chess")    # => false (mixed case)
+      #   Sashite::Snn::Name.valid?("CHESS960") # => false (contains digits)
+      #   Sashite::Snn::Name.valid?("GO9X9")    # => false (contains digits)
+      #   Sashite::Snn::Name.valid?("")         # => false (empty)
+      def self.valid?(string)
+        string.is_a?(::String) && string.match?(SNN_PATTERN)
+      end
+
+      # Returns the string representation of the name
+      #
+      # @return [String] the canonical style name
+      #
+      # @example
+      #   name = Sashite::Snn::Name.new("SHOGI")
+      #   name.to_s # => "SHOGI"
+      def to_s
+        value
+      end
+
+      # Equality based on string value
+      #
+      # Two names are equal if they have the same string value. Case matters:
+      # "CHESS" (first player) is not equal to "chess" (second player).
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if equal, false otherwise
+      #
+      # @example
+      #   name1 = Sashite::Snn::Name.new("CHESS")
+      #   name2 = Sashite::Snn::Name.new("CHESS")
+      #   name3 = Sashite::Snn::Name.new("chess")
+      #
+      #   name1 == name2  # => true
+      #   name1 == name3  # => false (different case = different player)
+      def ==(other)
+        other.is_a?(self.class) && value == other.value
+      end
+
+      # Required for correct Set/Hash behavior
+      alias eql? ==
+
+      # Hash based on class and value
+      #
+      # Enables Name objects to be used as hash keys and in sets.
+      #
+      # @return [Integer] hash code
+      #
+      # @example Use as hash key
+      #   styles = {
+      #     Sashite::Snn::Name.new("CHESS") => "Western Chess",
+      #     Sashite::Snn::Name.new("SHOGI") => "Japanese Chess"
+      #   }
+      def hash
+        [self.class, value].hash
+      end
+
+      # Validate that the string is in proper SNN format
+      #
+      # @param str [String] string to validate
+      # @raise [ArgumentError] if the string does not match SNN pattern
+      #
+      # @example Valid format
+      #   Sashite::Snn::Name.validate_format("CHESS")  # No error
+      #   Sashite::Snn::Name.validate_format("shogi")  # No error
+      #
+      # @example Invalid format
+      #   Sashite::Snn::Name.validate_format("Chess")  # Raises ArgumentError
+      def self.validate_format(str)
+        raise ::ArgumentError, format(ERROR_INVALID_NAME, str.inspect) unless str.match?(SNN_PATTERN)
+      end
+    end
+  end
+end

data/lib/sashite/snn.rb

@@ -1,65 +1,93 @@
 # frozen_string_literal: true
 
-require_relative "snn/style"
+require_relative "snn/name"
 
 module Sashite
   # SNN (Style Name Notation) implementation for Ruby
   #
-  # Provides a rule-agnostic format for identifying styles in abstract strategy board games.
-  # SNN uses single ASCII letters with case-based side encoding, enabling clear
-  # distinction between different style families in multi-style gaming environments.
+  # Provides a foundational naming system for identifying styles in abstract strategy board games.
+  # SNN uses canonical, human-readable alphabetic names with case encoding to represent both
+  # style identity and player assignment.
   #
-  # 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 SNN identifier is exactly one ASCII letter
+  # Format: All uppercase OR all lowercase alphabetic characters
   #
   # 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
+  #   "CHESS"    - Chess style for first player
+  #   "chess"    - Chess style for second player
+  #   "SHOGI"    - Shōgi style for first player
+  #   "shogi"    - Shōgi style for second player
+  #   "XIANGQI"  - Xiangqi style for first player
+  #   "xiangqi"  - Xiangqi style for second player
+  #
+  # Case Encoding:
+  #   - UPPERCASE names represent the first player's style
+  #   - lowercase names represent the second player's style
+  #
+  # Constraints:
+  #   - Alphabetic characters only (A-Z, a-z)
+  #   - Case consistency required (all uppercase OR all lowercase)
+  #   - No digits, no special characters, no mixed case
+  #
+  # As a foundational primitive, SNN has no dependencies and serves as a building block
+  # for formal style identification in the Sashité ecosystem.
   #
   # See: https://sashite.dev/specs/snn/1.0.0/
   module Snn
-    # Check if a string is a valid SNN notation
+    # Check if a string is valid SNN notation
+    #
+    # Valid SNN strings must contain only alphabetic characters in consistent case
+    # (either all uppercase or all lowercase).
     #
     # @param snn_string [String] the string to validate
     # @return [Boolean] true if valid SNN, false otherwise
     #
-    # @example Validate various SNN formats
-    #   Sashite::Snn.valid?("C") # => true
-    #   Sashite::Snn.valid?("c") # => true
-    #   Sashite::Snn.valid?("CHESS") # => false (multi-character)
-    #   Sashite::Snn.valid?("1") # => false (not a letter)
+    # @example Validate SNN strings
+    #   Sashite::Snn.valid?("CHESS")     # => true
+    #   Sashite::Snn.valid?("shogi")     # => true
+    #   Sashite::Snn.valid?("Chess")     # => false (mixed case)
+    #   Sashite::Snn.valid?("CHESS960")  # => false (contains digits)
+    #   Sashite::Snn.valid?("GO9X9")     # => false (contains digits)
     def self.valid?(snn_string)
-      Style.valid?(snn_string)
+      Name.valid?(snn_string)
     end
 
-    # Parse an SNN string into a Style object
+    # Parse an SNN string into a Name object
+    #
+    # Converts a valid SNN string into an immutable Name object. The name must follow
+    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
     #
-    # @param snn_string [String] SNN notation string
-    # @return [Snn::Style] parsed style object with letter and side attributes
-    # @raise [ArgumentError] if the SNN string is invalid
-    # @example Parse different SNN formats
-    #   Sashite::Snn.parse("C") # => #<Snn::Style letter=:C side=:first>
-    #   Sashite::Snn.parse("c") # => #<Snn::Style letter=:c side=:second>
-    #   Sashite::Snn.parse("S") # => #<Snn::Style letter=:S side=:first>
+    # @param snn_string [String] the name string
+    # @return [Snn::Name] a parsed name object
+    # @raise [ArgumentError] if the name is invalid
+    #
+    # @example Parse valid SNN names
+    #   Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
+    #   Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
+    #
+    # @example Invalid names raise errors
+    #   Sashite::Snn.parse("Chess")    # => ArgumentError (mixed case)
+    #   Sashite::Snn.parse("CHESS960") # => ArgumentError (contains digits)
     def self.parse(snn_string)
-      Style.parse(snn_string)
+      Name.parse(snn_string)
     end
 
-    # Create a new style instance
+    # Create a new Name instance directly
+    #
+    # Constructs a Name object from a string or symbol. The value must follow
+    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
+    #
+    # @param value [String, Symbol] style name to construct
+    # @return [Snn::Name] new name instance
+    # @raise [ArgumentError] if name format is invalid
+    #
+    # @example Create names
+    #   Sashite::Snn.name("XIANGQI") # => #<Snn::Name value="XIANGQI">
+    #   Sashite::Snn.name(:makruk)   # => #<Snn::Name value="makruk">
     #
-    # @param letter [Symbol] style letter (single ASCII letter as symbol)
-    # @param side [Symbol] player side (:first or :second)
-    # @return [Snn::Style] new immutable style instance
-    # @raise [ArgumentError] if parameters are invalid
-    # @example Create styles directly
-    #   Sashite::Snn.style(:C, :first)  # => #<Snn::Style letter=:C side=:first>
-    #   Sashite::Snn.style(:s, :second) # => #<Snn::Style letter=:s side=:second>
-    def self.style(letter, side)
-      Style.new(letter, side)
+    # @example Invalid formats raise errors
+    #   Sashite::Snn.name("Chess960") # => ArgumentError
+    def self.name(value)
+      Name.new(value)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-snn
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,13 +10,18 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  SNN (Style Name Notation) provides a rule-agnostic format for identifying styles
-  in abstract strategy board games. This gem implements the SNN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable style objects and functional programming
-  principles. SNN uses single ASCII letters with case-based side encoding (A-Z for first player,
-  a-z for second player), enabling clear distinction between different style families in
-  multi-style gaming environments. Perfect for cross-style matches, game engines, and hybrid
-  gaming systems requiring compact style identification.
+  SNN (Style Name Notation) provides a foundational, rule-agnostic naming system for identifying
+  game styles in abstract strategy board games. This gem implements the SNN Specification v1.0.0
+  with a modern Ruby interface featuring immutable style name objects and functional programming
+  principles.
+
+  SNN uses case-consistent alphabetic names (e.g., "CHESS", "SHOGI", "XIANGQI" for first player;
+  "chess", "shogi", "xiangqi" for second player) to unambiguously represent both style identity
+  and player assignment. As a foundational primitive with no dependencies, SNN serves as a building
+  block for formal style identification across the Sashité ecosystem.
+
+  Format: All uppercase OR all lowercase alphabetic characters only (no digits, no special characters).
+  Ideal for game engines, protocols, and tools requiring clear and extensible style identifiers.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -26,7 +31,7 @@ files:
 - README.md
 - lib/sashite-snn.rb
 - lib/sashite/snn.rb
-- lib/sashite/snn/style.rb
+- lib/sashite/snn/name.rb
 homepage: https://github.com/sashite/snn.rb
 licenses:
 - MIT
@@ -51,7 +56,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
-summary: SNN (Style Name Notation) implementation for Ruby with immutable style objects
+summary: SNN (Style Name Notation) - foundational naming system for abstract strategy
+  game styles
 test_files: []

data/lib/sashite/snn/style.rb

@@ -1,250 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Snn
-    # Represents a style in SNN (Style Name Notation) format.
-    #
-    # A style 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)
-    #
-    # All instances are immutable - transformation methods return new instances.
-    # This follows the SNN Specification v1.0.0 with Letter and Side attributes.
-    class Style
-      # SNN validation pattern matching the specification
-      SNN_PATTERN = /\A[A-Za-z]\z/
-
-      # Player side constants
-      FIRST_PLAYER = :first
-      SECOND_PLAYER = :second
-
-      # Valid sides
-      VALID_SIDES = [FIRST_PLAYER, SECOND_PLAYER].freeze
-
-      # Error messages
-      ERROR_INVALID_SNN = "Invalid SNN 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"
-
-      # @return [Symbol] the style letter (single ASCII letter as symbol)
-      attr_reader :letter
-
-      # @return [Symbol] the player side (:first or :second)
-      attr_reader :side
-
-      # Create a new style instance
-      #
-      # @param letter [Symbol] style letter (single ASCII letter as symbol)
-      # @param side [Symbol] player side (:first or :second)
-      # @raise [ArgumentError] if parameters are invalid
-      def initialize(letter, side)
-        self.class.validate_letter(letter)
-        self.class.validate_side(side)
-
-        @letter = letter
-        @side = side
-
-        freeze
-      end
-
-      # Parse an SNN string into a Style object
-      #
-      # @param snn_string [String] SNN notation string (single ASCII letter)
-      # @return [Style] parsed style object with letter and inferred side
-      # @raise [ArgumentError] if the SNN string is invalid
-      # @example Parse SNN strings with case-based side inference
-      #   Sashite::Snn::Style.parse("C") # => #<Snn::Style letter=:C side=:first>
-      #   Sashite::Snn::Style.parse("c") # => #<Snn::Style letter=:c side=:second>
-      #   Sashite::Snn::Style.parse("S") # => #<Snn::Style letter=:S side=:first>
-      def self.parse(snn_string)
-        string_value = String(snn_string)
-        validate_snn_string(string_value)
-
-        # Determine side from case
-        style_side = string_value == string_value.upcase ? FIRST_PLAYER : SECOND_PLAYER
-
-        # Use the letter directly as symbol
-        style_letter = string_value.to_sym
-
-        new(style_letter, style_side)
-      end
-
-      # Check if a string is a valid SNN notation
-      #
-      # @param snn_string [String] the string to validate
-      # @return [Boolean] true if valid SNN, false otherwise
-      #
-      # @example Validate SNN strings
-      #   Sashite::Snn::Style.valid?("C") # => true
-      #   Sashite::Snn::Style.valid?("c") # => true
-      #   Sashite::Snn::Style.valid?("CHESS") # => false (multi-character)
-      def self.valid?(snn_string)
-        return false unless snn_string.is_a?(::String)
-
-        snn_string.match?(SNN_PATTERN)
-      end
-
-      # Convert the style to its SNN string representation
-      #
-      # @return [String] SNN notation string (single ASCII letter)
-      # @example Display styles
-      #   style.to_s  # => "C" (first player, C family)
-      #   style.to_s  # => "c" (second player, C family)
-      #   style.to_s  # => "S" (first player, S family)
-      def to_s
-        letter.to_s
-      end
-
-      # Create a new style with opposite ownership (side)
-      #
-      # @return [Style] new immutable style instance with flipped side
-      # @example Flip player sides
-      #   style.flip  # (:C, :first) => (:c, :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)
-      end
-
-      # Create a new style with a different letter (keeping same side)
-      #
-      # @param new_letter [Symbol] new letter (single ASCII letter as symbol)
-      # @return [Style] new immutable style instance with different letter
-      # @example Change style letter
-      #   style.with_letter(:S)  # (:C, :first) => (:S, :first)
-      def with_letter(new_letter)
-        self.class.validate_letter(new_letter)
-        return self if letter == new_letter
-
-        # 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)
-      end
-
-      # Create a new style with a different side (keeping same letter family)
-      #
-      # @param new_side [Symbol] :first or :second
-      # @return [Style] new immutable style instance with different side
-      # @example Change player side
-      #   style.with_side(:second)  # (:C, :first) => (:c, :second)
-      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)
-      end
-
-      # Check if the style belongs to the first player
-      #
-      # @return [Boolean] true if first player
-      def first_player?
-        side == FIRST_PLAYER
-      end
-
-      # Check if the style belongs to the second player
-      #
-      # @return [Boolean] true if second player
-      def second_player?
-        side == SECOND_PLAYER
-      end
-
-      # Check if this style has the same letter family as another
-      #
-      # @param other [Style] style to compare with
-      # @return [Boolean] true if both styles use the same letter family (case-insensitive)
-      # @example Compare style letter families
-      #   c_style.same_letter?(C_style)  # (:c, :second) and (:C, :first) => true
-      def same_letter?(other)
-        return false unless other.is_a?(self.class)
-
-        letter.to_s.upcase == other.letter.to_s.upcase
-      end
-
-      # Check if this style belongs to the same side as another
-      #
-      # @param other [Style] style to compare with
-      # @return [Boolean] true if both styles belong to the same side
-      def same_side?(other)
-        return false unless other.is_a?(self.class)
-
-        side == other.side
-      end
-
-      # Custom equality comparison
-      #
-      # @param other [Object] object to compare with
-      # @return [Boolean] true if both objects are styles with identical letter and side
-      def ==(other)
-        return false unless other.is_a?(self.class)
-
-        letter == other.letter && side == other.side
-      end
-
-      # Alias for == to ensure Set functionality works correctly
-      alias eql? ==
-
-      # Custom hash implementation for use in collections
-      #
-      # @return [Integer] hash value based on class, letter, and side
-      def hash
-        [self.class, letter, side].hash
-      end
-
-      # Validate that the letter is a valid single ASCII letter symbol
-      #
-      # @param letter [Symbol] the letter to validate
-      # @raise [ArgumentError] if invalid
-      def self.validate_letter(letter)
-        return if valid_letter?(letter)
-
-        raise ::ArgumentError, format(ERROR_INVALID_LETTER, letter.inspect)
-      end
-
-      # Validate that the side is a valid symbol
-      #
-      # @param side [Symbol] the side to validate
-      # @raise [ArgumentError] if invalid
-      def self.validate_side(side)
-        return if VALID_SIDES.include?(side)
-
-        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?(SNN_PATTERN)
-      end
-
-      # Validate SNN string format
-      #
-      # @param string [String] string to validate
-      # @raise [ArgumentError] if string doesn't match SNN pattern
-      def self.validate_snn_string(string)
-        return if string.match?(SNN_PATTERN)
-
-        raise ::ArgumentError, format(ERROR_INVALID_SNN, string)
-      end
-
-      private_class_method :valid_letter?, :validate_snn_string
-
-      private
-
-      # Get the opposite side
-      #
-      # @return [Symbol] the opposite side
-      def opposite_side
-        first_player? ? SECOND_PLAYER : FIRST_PLAYER
-      end
-    end
-  end
-end