sashite-sin 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0243c39193799ab26a617517ae8deb0a63f4c6400a00ebdd265710ccae62dccb
-  data.tar.gz: 6a7c470c3f03680ab983ebb65c66d0a28dacaf1b6f422d5a900d214999f6ba2b
+  metadata.gz: 611d7fa815981b0a68443f7641f2f780afe46bca6fd8fed0f6204f35b0c2721b
+  data.tar.gz: c414565ed46cb55375c7ec599424dea459999c2162e458ee62be81a49dcf601b
 SHA512:
-  metadata.gz: fcd80485fabc9888e20925161a29b9c6cd1dc286d8cd802e1363e8887991226243c414c7ff6c50714b464d6eb8058519c5d04fd82458856a5c4d0a618e1185b9
-  data.tar.gz: b1005945dd8bdcd9c818c07a104ac8582e3b2e966dc73626034cf53f7b1c7d306a59b419621c0eb3dc1705200e55ffa54904b4f54d2842348d13f797e9e3b329
+  metadata.gz: e8e1fa4bbc10f70ba9e17f01292228d538d639f3de6a4e1fc30207f436a1d72133edf502eef557405fce096ecb30c4c9125cd6919f3dc03cb5005e356fcb11f4
+  data.tar.gz: b3904a0fa64f33251e6db3cf6f454578a3dadccb75f8e3b3e885de834ecd6c9b0e0dd53aeaa62587fe9dde5979b991f0b54dc93e10b835ab9bfdad8cd31f4136

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Cyril Kato
+   Copyright 2025-2026 Cyril Kato
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -2,7 +2,7 @@
 
 [![Version](https://img.shields.io/github/v/tag/sashite/sin.rb?label=Version&logo=github)](https://github.com/sashite/sin.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/sin.rb/main)
-[![CI](https://github.com/sashite/sin.rb/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/sashite/sin.rb/actions)
+[![CI](https://github.com/sashite/sin.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/sin.rb/actions)
 [![License](https://img.shields.io/github/license/sashite/sin.rb?label=License&logo=github)](https://github.com/sashite/sin.rb/raw/main/LICENSE)
 
 > **SIN** (Style Identifier Notation) implementation for Ruby.
@@ -11,6 +11,18 @@
 
 This library implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/).
 
+SIN is a single-character, ASCII-only token format encoding a **Player Identity**: the tuple (**Player Side**, **Player Style**). Uppercase indicates the first player, lowercase indicates the second player.
+
+### Implementation Constraints
+
+| Constraint | Value | Rationale |
+|------------|-------|-----------|
+| Token length | Exactly 1 | Single ASCII letter per spec |
+| Character space | A–Z, a–z | 52 total tokens (26 abbreviations × 2 sides) |
+| Instance pool | 52 objects | All identifiers are pre-instantiated and frozen |
+
+The closed domain of 52 possible values enables a flyweight architecture with zero allocation on the hot path.
+
 ## Installation
 
 ```ruby
@@ -35,69 +47,78 @@ require "sashite/sin"
 
 # Standard parsing (raises on error)
 sin = Sashite::Sin.parse("C")
-sin.style  # => :C
-sin.side   # => :first
+sin.abbr  # => :C
+sin.side  # => :first
 
 # Lowercase indicates second player
 sin = Sashite::Sin.parse("c")
-sin.style  # => :C
-sin.side   # => :second
+sin.abbr  # => :C
+sin.side  # => :second
+
+# Returns a cached instance — no allocation
+Sashite::Sin.parse("C").equal?(Sashite::Sin.parse("C"))  # => true
 
 # Invalid input raises ArgumentError
 Sashite::Sin.parse("")    # => raises ArgumentError
 Sashite::Sin.parse("CC")  # => raises ArgumentError
 ```
 
-### Formatting (Identifier → String)
+### Safe Parsing (String → Identifier | nil)
 
-Convert an `Identifier` back to a SIN string.
+Parse without raising exceptions. Returns `nil` on invalid input.
 
 ```ruby
-# From Identifier object
-sin = Sashite::Sin::Identifier.new(:C, :first)
-sin.to_s  # => "C"
-
-sin = Sashite::Sin::Identifier.new(:C, :second)
-sin.to_s  # => "c"
+# Valid input returns an Identifier
+Sashite::Sin.safe_parse("C")   # => #<Sashite::Sin::Identifier C>
+Sashite::Sin.safe_parse("c")   # => #<Sashite::Sin::Identifier c>
+
+# Invalid input returns nil — no exception allocated
+Sashite::Sin.safe_parse("")    # => nil
+Sashite::Sin.safe_parse("CC")  # => nil
+Sashite::Sin.safe_parse("1")   # => nil
+Sashite::Sin.safe_parse(nil)   # => nil
 ```
 
-### Validation
+### Fetching by Components (Symbol, Symbol → Identifier)
 
-```ruby
-# Boolean check
-Sashite::Sin.valid?("C")   # => true
-Sashite::Sin.valid?("c")   # => true
-Sashite::Sin.valid?("")    # => false
-Sashite::Sin.valid?("CC")  # => false
-Sashite::Sin.valid?("1")   # => false
-```
-
-### Accessing Identifier Data
+Retrieve a cached identifier directly by abbreviation and side, bypassing string parsing entirely.
 
 ```ruby
-sin = Sashite::Sin.parse("C")
+# Direct lookup — no string parsing, no allocation
+Sashite::Sin.fetch(:C, :first)   # => #<Sashite::Sin::Identifier C>
+Sashite::Sin.fetch(:C, :second)  # => #<Sashite::Sin::Identifier c>
 
-# Get attributes
-sin.style  # => :C
-sin.side   # => :first
+# Same cached instance as parse
+Sashite::Sin.fetch(:C, :first).equal?(Sashite::Sin.parse("C"))  # => true
 
-# Get string component
-sin.letter  # => "C"
+# Invalid components raise ArgumentError
+Sashite::Sin.fetch(:CC, :first)    # => raises ArgumentError
+Sashite::Sin.fetch(:C, :third)     # => raises ArgumentError
 ```
 
-### Transformations
+### Formatting (Identifier → String)
 
-All transformations return new immutable `Identifier` objects.
+Convert an `Identifier` back to a SIN string.
 
 ```ruby
 sin = Sashite::Sin.parse("C")
+sin.to_s  # => "C"
 
-# Side transformation
-sin.flip.to_s  # => "c"
+sin = Sashite::Sin.parse("c")
+sin.to_s  # => "c"
+```
 
-# Attribute changes
-sin.with_style(:S).to_s  # => "S"
-sin.with_side(:second).to_s  # => "c"
+### Validation
+
+```ruby
+# Boolean check (never raises)
+# Uses an exception-free code path internally for performance.
+Sashite::Sin.valid?("C")   # => true
+Sashite::Sin.valid?("c")   # => true
+Sashite::Sin.valid?("")    # => false
+Sashite::Sin.valid?("CC")  # => false
+Sashite::Sin.valid?("1")   # => false
+Sashite::Sin.valid?(nil)   # => false
 ```
 
 ### Queries
@@ -111,82 +132,73 @@ sin.second_player?  # => false
 
 # Comparison queries
 other = Sashite::Sin.parse("c")
-sin.same_style?(other)  # => true
-sin.same_side?(other)   # => false
+sin.same_abbr?(other)  # => true
+sin.same_side?(other)  # => false
 ```
 
 ## API Reference
 
-### Types
-
-```ruby
-# Identifier represents a parsed SIN identifier with style and side.
-class Sashite::Sin::Identifier
-  # Creates an Identifier from style and side.
-  # Raises ArgumentError if attributes are invalid.
-  #
-  # @param style [Symbol] Style abbreviation (:A through :Z)
-  # @param side [Symbol] Player side (:first or :second)
-  # @return [Identifier]
-  def initialize(style, side)
-
-  # Returns the style as an uppercase symbol.
-  #
-  # @return [Symbol]
-  def style
-
-  # Returns the player side.
-  #
-  # @return [Symbol] :first or :second
-  def side
-
-  # Returns the SIN string representation.
-  #
-  # @return [String]
-  def to_s
-end
-```
-
-### Constants
-
-```ruby
-Sashite::Sin::Identifier::VALID_STYLES  # => [:A, :B, ..., :Z]
-Sashite::Sin::Identifier::VALID_SIDES   # => [:first, :second]
-```
-
-### Parsing
+### Module Methods
 
 ```ruby
-# Parses a SIN string into an Identifier.
+# Parses a SIN string into a cached Identifier.
+# Returns a pre-instantiated, frozen instance.
 # Raises ArgumentError if the string is not valid.
 #
 # @param string [String] SIN string
 # @return [Identifier]
 # @raise [ArgumentError] if invalid
 def Sashite::Sin.parse(string)
-```
 
-### Validation
+# Parses a SIN string without raising.
+# Returns a cached Identifier on success, nil on failure.
+# Never allocates exception objects or captures backtraces.
+#
+# @param string [String] SIN string
+# @return [Identifier, nil]
+def Sashite::Sin.safe_parse(string)
+
+# Retrieves a cached Identifier by abbreviation and side.
+# Bypasses string parsing entirely — direct hash lookup.
+# Raises ArgumentError if components are invalid.
+#
+# @param abbr [Symbol] Style abbreviation (:A through :Z)
+# @param side [Symbol] Player side (:first or :second)
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Sin.fetch(abbr, side)
 
-```ruby
 # Reports whether string is a valid SIN identifier.
+# Never raises; returns false for any invalid input.
+# Uses an exception-free code path internally for performance.
 #
 # @param string [String] SIN string
 # @return [Boolean]
 def Sashite::Sin.valid?(string)
 ```
 
-### Transformations
-
-All transformations return new `Sashite::Sin::Identifier` objects:
+### Identifier
 
 ```ruby
-# Side transformation
-def flip  # => Identifier
+# Identifier represents a parsed SIN identifier with abbreviation and side.
+# All instances are frozen and pre-instantiated — never construct directly,
+# use Sashite::Sin.parse, .safe_parse, or .fetch instead.
+class Sashite::Sin::Identifier
+  # Returns the style abbreviation as an uppercase symbol.
+  #
+  # @return [Symbol] :A through :Z
+  def abbr
+
+  # Returns the player side.
+  #
+  # @return [Symbol] :first or :second
+  def side
 
-# Attribute changes
-def with_style(style)  # => Identifier
-def with_side(side)    # => Identifier
+  # Returns the SIN string representation.
+  #
+  # @return [String]
+  def to_s
+end
 ```
 
 ### Queries
@@ -197,13 +209,20 @@ def first_player?   # => Boolean
 def second_player?  # => Boolean
 
 # Comparison queries
-def same_style?(other)  # => Boolean
-def same_side?(other)   # => Boolean
+def same_abbr?(other)  # => Boolean
+def same_side?(other)  # => Boolean
+```
+
+### Constants
+
+```ruby
+Sashite::Sin::Identifier::VALID_ABBRS  # => [:A, :B, ..., :Z]
+Sashite::Sin::Identifier::VALID_SIDES  # => [:first, :second]
 ```
 
 ### Errors
 
-All parsing and validation errors raise `ArgumentError` with descriptive messages:
+All errors raise `ArgumentError` with descriptive messages:
 
 | Message | Cause |
 |---------|-------|
@@ -213,12 +232,28 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 
 ## Design Principles
 
-- **Bounded values**: Explicit validation of styles and sides
-- **Object-oriented**: `Identifier` class enables methods and encapsulation
+- **Spec conformance**: Strict adherence to SIN v1.0.0
+- **Flyweight identifiers**: All 52 possible instances are pre-built and frozen; parsing and fetching return cached objects with zero allocation
+- **Performance-oriented internals**: Exception-free validation path; exceptions only at the public API boundary
 - **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
-- **Immutable identifiers**: All transformations return new objects
+- **Immutable identifiers**: All instances are frozen after creation
 - **No dependencies**: Pure Ruby standard library only
 
+### Performance Architecture
+
+SIN has a closed domain of exactly 52 valid tokens (26 letters × 2 cases). The implementation exploits this constraint through two complementary strategies.
+
+**Flyweight instance pool** — All 52 `Identifier` objects are pre-instantiated and frozen at load time. `parse`, `safe_parse`, and `fetch` return these cached instances via hash lookup. No `Identifier` is ever allocated after the module loads. This makes SIN essentially free to call from FEEN or any other hot loop — every call is a hash lookup returning a pre-existing frozen object.
+
+**Dual-path parsing** — Parsing is split into two layers to avoid using exceptions for control flow:
+
+- **Validation layer** — `safe_parse` performs all validation and returns the cached `Identifier` on success, or `nil` on failure, without raising, without allocating exception objects, and without capturing backtraces.
+- **Public API layer** — `parse` calls `safe_parse` internally. On failure, it raises `ArgumentError` exactly once, at the boundary. `valid?` calls `safe_parse` and returns a boolean directly, never raising.
+
+**Direct component lookup** — `fetch` bypasses string parsing entirely. Given a symbol pair `(:C, :first)`, it performs a single hash lookup into the instance pool. This is the fastest path for callers that already have structured data (e.g., FEEN's dumper reconstructing a style–turn field from `Qi` attributes).
+
+This architecture ensures that SIN never becomes a bottleneck when called from higher-level parsers like FEEN, where it may be invoked multiple times per position.
+
 ## Related Specifications
 
 - [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation

data/lib/sashite/sin/constants.rb

@@ -4,35 +4,53 @@ module Sashite
   module Sin
     # Constants for the SIN (Style Identifier Notation) specification.
     #
-    # Defines valid values for styles and sides, as well as formatting constants.
-    #
-    # @example Accessing valid styles
-    #   Constants::VALID_STYLES  # => [:A, :B, ..., :Z]
-    #
-    # @example Accessing valid sides
-    #   Constants::VALID_SIDES  # => [:first, :second]
+    # Provides public-facing domain constants and pre-computed lookup tables
+    # used internally for zero-allocation parsing.
     #
     # @see https://sashite.dev/specs/sin/1.0.0/
     module Constants
-      # Valid style symbols (A-Z as uppercase symbols).
+      # Valid abbreviation symbols (A-Z as uppercase symbols).
       #
-      # @return [Array<Symbol>] Array of 26 valid style symbols
-      VALID_STYLES = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
+      # @return [Array<Symbol>] Array of 26 valid abbreviation symbols
+      VALID_ABBRS = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
 
       # Valid side symbols.
       #
       # @return [Array<Symbol>] Array of valid side symbols
       VALID_SIDES = %i[first second].freeze
 
-      # Maximum length of a valid SIN string.
+      # Pre-computed byte → uppercase Symbol lookup table.
+      #
+      # Maps every valid ASCII letter byte (A-Z, a-z) to its uppercase Symbol
+      # abbreviation. Used by the parser for O(1) extraction with no intermediate
+      # String allocation.
       #
-      # @return [Integer] Maximum string length (1)
-      MAX_STRING_LENGTH = 1
+      # @example
+      #   BYTE_TO_ABBR[0x43]  # => :C  (byte for 'C')
+      #   BYTE_TO_ABBR[0x63]  # => :C  (byte for 'c')
+      #   BYTE_TO_ABBR[0x31]  # => nil  (byte for '1')
+      #
+      # @return [Hash{Integer => Symbol}] Frozen byte-to-symbol mapping
+      BYTE_TO_ABBR = {}.tap { |h|
+        (0x41..0x5A).each { |b| h[b] = b.chr.to_sym }
+        (0x61..0x7A).each { |b| h[b] = (b - 32).chr.to_sym }
+      }.freeze
 
-      # Empty string constant for internal use.
+      # Pre-computed byte → side lookup table.
+      #
+      # Maps every valid ASCII letter byte to its corresponding side.
+      # Uppercase letters map to :first, lowercase to :second.
+      #
+      # @example
+      #   BYTE_TO_SIDE[0x43]  # => :first   (byte for 'C')
+      #   BYTE_TO_SIDE[0x63]  # => :second  (byte for 'c')
+      #   BYTE_TO_SIDE[0x31]  # => nil      (byte for '1')
       #
-      # @return [String] Empty string
-      EMPTY_STRING = ""
+      # @return [Hash{Integer => Symbol}] Frozen byte-to-side mapping
+      BYTE_TO_SIDE = {}.tap { |h|
+        (0x41..0x5A).each { |b| h[b] = :first }
+        (0x61..0x7A).each { |b| h[b] = :second }
+      }.freeze
     end
   end
 end

data/lib/sashite/sin/errors/argument/messages.rb

@@ -29,10 +29,10 @@ module Sashite
           # @return [String] Error message
           MUST_BE_LETTER = "must be a letter"
 
-          # Error message for invalid style value.
+          # Error message for invalid abbreviation value.
           #
           # @return [String] Error message
-          INVALID_STYLE = "invalid style"
+          INVALID_ABBR = "invalid abbr"
 
           # Error message for invalid side value.
           #

data/lib/sashite/sin/identifier.rb

@@ -8,49 +8,51 @@ module Sashite
     # Represents a parsed SIN (Style Identifier Notation) identifier.
     #
     # An Identifier encodes two attributes:
-    # - Style: the piece style (A-Z as uppercase symbol)
+    # - Abbr: the style abbreviation (A-Z as uppercase symbol)
     # - Side: the player side (:first or :second)
     #
-    # Instances are immutable (frozen after creation).
+    # All 52 possible instances are pre-instantiated and frozen at load time.
+    # Never construct directly — use {Sashite::Sin.parse}, {Sashite::Sin.safe_parse},
+    # or {Sashite::Sin.fetch} instead.
     #
-    # @example Creating identifiers
-    #   sin = Identifier.new(:C, :first)
-    #   sin = Identifier.new(:S, :second)
+    # @example Obtaining identifiers
+    #   Sashite::Sin.parse("C")           # => #<Sashite::Sin::Identifier C>
+    #   Sashite::Sin.fetch(:C, :first)    # => #<Sashite::Sin::Identifier C>
     #
-    # @example String conversion
-    #   Identifier.new(:C, :first).to_s   # => "C"
-    #   Identifier.new(:C, :second).to_s  # => "c"
+    # @example Identity guarantee (flyweight)
+    #   Sashite::Sin.parse("C").equal?(Sashite::Sin.fetch(:C, :first))  # => true
     #
     # @see https://sashite.dev/specs/sin/1.0.0/
     class Identifier
-      # Valid style symbols (A-Z).
-      VALID_STYLES = Constants::VALID_STYLES
+      # Valid abbreviation symbols (A-Z).
+      VALID_ABBRS = Constants::VALID_ABBRS
 
       # Valid side symbols.
       VALID_SIDES = Constants::VALID_SIDES
 
-      # @return [Symbol] Piece style (:A to :Z, always uppercase)
-      attr_reader :style
+      # @return [Symbol] Style abbreviation (:A to :Z, always uppercase)
+      attr_reader :abbr
 
       # @return [Symbol] Player side (:first or :second)
       attr_reader :side
 
       # Creates a new Identifier instance.
       #
-      # @param style [Symbol] Piece style (:A to :Z)
+      # @param abbr [Symbol] Style abbreviation (:A to :Z)
       # @param side [Symbol] Player side (:first or :second)
       # @return [Identifier] A new frozen Identifier instance
       # @raise [Errors::Argument] If any attribute is invalid
       #
-      # @example
-      #   Identifier.new(:C, :first)
-      #   Identifier.new(:S, :second)
-      def initialize(style, side)
-        validate_style!(style)
+      # @api private
+      def initialize(abbr, side)
+        validate_abbr!(abbr)
         validate_side!(side)
 
-        @style = style
+        @abbr = abbr
         @side = side
+        @string = (side.equal?(:first) ? abbr.to_s : abbr.to_s.downcase).freeze
+        @hash = [abbr, side].hash
+        @inspect = "#<#{self.class} #{@string}>".freeze
 
         freeze
       end
@@ -61,79 +63,15 @@ module Sashite
 
       # Returns the SIN string representation.
       #
+      # Returns a pre-computed, frozen string — zero allocation per call.
+      #
       # @return [String] The single-character SIN string
       #
       # @example
-      #   Identifier.new(:C, :first).to_s   # => "C"
-      #   Identifier.new(:C, :second).to_s  # => "c"
+      #   Sashite::Sin.parse("C").to_s   # => "C"
+      #   Sashite::Sin.parse("c").to_s   # => "c"
       def to_s
-        letter
-      end
-
-      # Returns the letter component of the SIN.
-      #
-      # @return [String] Uppercase for first player, lowercase for second
-      #
-      # @example
-      #   Identifier.new(:C, :first).letter   # => "C"
-      #   Identifier.new(:C, :second).letter  # => "c"
-      def letter
-        base = String(style)
-
-        case side
-        when :first  then base.upcase
-        when :second then base.downcase
-        end
-      end
-
-      # ========================================================================
-      # Side Transformations
-      # ========================================================================
-
-      # Returns a new Identifier with the opposite side.
-      #
-      # @return [Identifier] A new Identifier with flipped side
-      #
-      # @example
-      #   sin = Identifier.new(:C, :first)
-      #   sin.flip.to_s  # => "c"
-      def flip
-        new_side = first_player? ? :second : :first
-        self.class.new(style, new_side)
-      end
-
-      # ========================================================================
-      # Attribute Transformations
-      # ========================================================================
-
-      # Returns a new Identifier with a different style.
-      #
-      # @param new_style [Symbol] The new piece style (:A to :Z)
-      # @return [Identifier] A new Identifier with the specified style
-      # @raise [Errors::Argument] If the style is invalid
-      #
-      # @example
-      #   sin = Identifier.new(:C, :first)
-      #   sin.with_style(:S).to_s  # => "S"
-      def with_style(new_style)
-        return self if style.equal?(new_style)
-
-        self.class.new(new_style, side)
-      end
-
-      # Returns a new Identifier with a different side.
-      #
-      # @param new_side [Symbol] The new side (:first or :second)
-      # @return [Identifier] A new Identifier with the specified side
-      # @raise [Errors::Argument] If the side is invalid
-      #
-      # @example
-      #   sin = Identifier.new(:C, :first)
-      #   sin.with_side(:second).to_s  # => "c"
-      def with_side(new_side)
-        return self if side.equal?(new_side)
-
-        self.class.new(style, new_side)
+        @string
       end
 
       # ========================================================================
@@ -145,7 +83,7 @@ module Sashite
       # @return [Boolean] true if first player
       #
       # @example
-      #   Identifier.new(:C, :first).first_player?  # => true
+      #   Sashite::Sin.parse("C").first_player?  # => true
       def first_player?
         side.equal?(:first)
       end
@@ -155,7 +93,7 @@ module Sashite
       # @return [Boolean] true if second player
       #
       # @example
-      #   Identifier.new(:C, :second).second_player?  # => true
+      #   Sashite::Sin.parse("c").second_player?  # => true
       def second_player?
         side.equal?(:second)
       end
@@ -164,17 +102,17 @@ module Sashite
       # Comparison Queries
       # ========================================================================
 
-      # Checks if two Identifiers have the same style.
+      # Checks if two Identifiers have the same abbreviation.
       #
       # @param other [Identifier] The other Identifier to compare
-      # @return [Boolean] true if same style
+      # @return [Boolean] true if same abbreviation
       #
       # @example
-      #   sin1 = Identifier.new(:C, :first)
-      #   sin2 = Identifier.new(:C, :second)
-      #   sin1.same_style?(sin2)  # => true
-      def same_style?(other)
-        style.equal?(other.style)
+      #   sin1 = Sashite::Sin.parse("C")
+      #   sin2 = Sashite::Sin.parse("c")
+      #   sin1.same_abbr?(sin2)  # => true
+      def same_abbr?(other)
+        abbr.equal?(other.abbr)
       end
 
       # Checks if two Identifiers have the same side.
@@ -183,8 +121,8 @@ module Sashite
       # @return [Boolean] true if same side
       #
       # @example
-      #   sin1 = Identifier.new(:C, :first)
-      #   sin2 = Identifier.new(:S, :first)
+      #   sin1 = Sashite::Sin.parse("C")
+      #   sin2 = Sashite::Sin.parse("S")
       #   sin1.same_side?(sin2)  # => true
       def same_side?(other)
         side.equal?(other.side)
@@ -196,36 +134,36 @@ module Sashite
 
       # Checks equality with another Identifier.
       #
+      # With the flyweight pool, equal identifiers are always the same object
+      # (i.e., == implies equal?). Value-based comparison is provided for
+      # correctness when comparing across different object sources.
+      #
       # @param other [Object] The object to compare
       # @return [Boolean] true if equal
       #
       # @example
-      #   sin1 = Identifier.new(:C, :first)
-      #   sin2 = Identifier.new(:C, :first)
-      #   sin1 == sin2  # => true
+      #   Sashite::Sin.parse("C") == Sashite::Sin.fetch(:C, :first)  # => true
       def ==(other)
-        return false unless self.class === other
-
-        style.equal?(other.style) && side.equal?(other.side)
+        equal?(other) || (self.class === other && abbr.equal?(other.abbr) && side.equal?(other.side))
       end
 
       alias eql? ==
 
-      # Returns a hash code for the Identifier.
+      # Returns a pre-computed hash code for the Identifier.
       #
       # @return [Integer] Hash code
       def hash
-        [style, side].hash
+        @hash
       end
 
-      # Returns an inspect string for the Identifier.
+      # Returns a pre-computed inspect string for the Identifier.
       #
       # @return [String] Inspect representation
       #
       # @example
-      #   Identifier.new(:C, :first).inspect  # => "#<Sashite::Sin::Identifier C>"
+      #   Sashite::Sin.parse("C").inspect  # => "#<Sashite::Sin::Identifier C>"
       def inspect
-        "#<#{self.class} #{self}>"
+        @inspect
       end
 
       private
@@ -234,10 +172,10 @@ module Sashite
       # Private Validation
       # ========================================================================
 
-      def validate_style!(style)
-        return if ::Symbol === style && Constants::VALID_STYLES.include?(style)
+      def validate_abbr!(abbr)
+        return if ::Symbol === abbr && Constants::VALID_ABBRS.include?(abbr)
 
-        raise Errors::Argument, Errors::Argument::Messages::INVALID_STYLE
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_ABBR
       end
 
       def validate_side!(side)
@@ -245,6 +183,38 @@ module Sashite
 
         raise Errors::Argument, Errors::Argument::Messages::INVALID_SIDE
       end
+
+      # ========================================================================
+      # Flyweight Instance Pool
+      # ========================================================================
+
+      public
+
+      # Component-keyed pool: [abbr, side] → Identifier.
+      #
+      # Used by {Sashite::Sin.fetch} for direct lookup by structured components.
+      #
+      # @return [Hash{Array(Symbol, Symbol) => Identifier}]
+      POOL = {}.tap { |pool|
+        Constants::VALID_ABBRS.each do |abbr|
+          Constants::VALID_SIDES.each do |side|
+            pool[[abbr, side]] = new(abbr, side)
+          end
+        end
+      }.freeze
+
+      # Byte-keyed pool: ASCII byte → Identifier.
+      #
+      # Used by the parser for O(1) lookup from a validated byte.
+      # Returns nil for non-letter bytes, doubling as implicit validation.
+      #
+      # @return [Hash{Integer => Identifier}]
+      BYTE_POOL = {}.tap { |pool|
+        (0x41..0x5A).each { |b| pool[b] = POOL[[b.chr.to_sym, :first]] }
+        (0x61..0x7A).each { |b| pool[b] = POOL[[(b - 32).chr.to_sym, :second]] }
+      }.freeze
+
+      private_class_method :new
     end
   end
 end

data/lib/sashite/sin/parser.rb

@@ -1,18 +1,31 @@
 # frozen_string_literal: true
 
-require_relative "constants"
 require_relative "errors"
+require_relative "identifier"
 
 module Sashite
   module Sin
     # Parses SIN (Style Identifier Notation) strings.
     #
-    # The parser uses byte-level validation to ensure security against
-    # malformed input, Unicode lookalikes, and injection attacks.
+    # Implements a dual-path architecture for maximum performance:
+    #
+    # - {.safe_parse} validates and returns a cached Identifier or nil,
+    #   without ever raising or allocating exception objects.
+    # - {.parse} delegates to safe_parse and raises exactly once at the
+    #   API boundary on failure.
+    # - {.valid?} delegates to safe_parse and converts to boolean.
+    #
+    # All valid inputs resolve to a pre-instantiated flyweight Identifier
+    # via a single byte-indexed Hash lookup.
     #
     # @example Parsing a valid SIN string
-    #   Parser.parse("C")  # => { style: :C, side: :first }
-    #   Parser.parse("c")  # => { style: :C, side: :second }
+    #   Parser.parse("C")  # => #<Sashite::Sin::Identifier C>
+    #   Parser.parse("c")  # => #<Sashite::Sin::Identifier c>
+    #
+    # @example Safe parsing
+    #   Parser.safe_parse("C")   # => #<Sashite::Sin::Identifier C>
+    #   Parser.safe_parse("1")   # => nil
+    #   Parser.safe_parse(nil)   # => nil
     #
     # @example Validation
     #   Parser.valid?("C")   # => true
@@ -20,28 +33,45 @@ module Sashite
     #
     # @see https://sashite.dev/specs/sin/1.0.0/
     module Parser
-      # Parses a SIN string into its components.
+      # Parses a SIN string into a cached Identifier.
+      #
+      # Delegates to {.safe_parse} internally. On failure, raises a single
+      # ArgumentError with a descriptive message.
       #
       # @param input [String] The SIN string to parse
-      # @return [Hash] Hash with :style and :side keys
+      # @return [Identifier] A pre-instantiated, frozen Identifier
       # @raise [Errors::Argument] If the input is invalid
       #
       # @example
-      #   Parser.parse("C")  # => { style: :C, side: :first }
-      #   Parser.parse("s")  # => { style: :S, side: :second }
+      #   Parser.parse("C")  # => #<Sashite::Sin::Identifier C>
+      #   Parser.parse("s")  # => #<Sashite::Sin::Identifier s>
       def self.parse(input)
-        validate_input_type!(input)
-        validate_not_empty!(input)
-        validate_length!(input)
-
-        byte = input.getbyte(0)
-        validate_letter!(byte)
+        safe_parse(input) || raise(Errors::Argument, error_message_for(input))
+      end
 
-        extract_components(byte)
+      # Parses a SIN string without raising.
+      #
+      # Returns a cached Identifier on success, nil on failure.
+      # Never allocates exception objects or captures backtraces.
+      #
+      # @param input [String] The string to parse
+      # @return [Identifier, nil] A cached Identifier, or nil if invalid
+      #
+      # @example
+      #   Parser.safe_parse("C")   # => #<Sashite::Sin::Identifier C>
+      #   Parser.safe_parse("")    # => nil
+      #   Parser.safe_parse(nil)   # => nil
+      def self.safe_parse(input)
+        return unless ::String === input
+        return unless input.bytesize == 1
+
+        Identifier::BYTE_POOL[input.getbyte(0)]
       end
 
       # Reports whether the input is a valid SIN string.
       #
+      # Never raises; returns false for any invalid input including non-String.
+      #
       # @param input [String] The string to validate
       # @return [Boolean] true if valid, false otherwise
       #
@@ -51,87 +81,20 @@ module Sashite
       #   Parser.valid?("")    # => false
       #   Parser.valid?("CC")  # => false
       def self.valid?(input)
-        parse(input)
-        true
-      rescue Errors::Argument
-        false
+        !safe_parse(input).nil?
       end
 
-      # @!group Private Class Methods
-
-      # Validates that input is a String.
+      # Determines the appropriate error message for an invalid input.
       #
-      # @param input [Object] The input to validate
-      # @raise [Errors::Argument] If input is not a String
-      # @return [void]
-      private_class_method def self.validate_input_type!(input)
-        return if ::String === input
-
-        raise Errors::Argument, Errors::Argument::Messages::MUST_BE_LETTER
+      # @param input [Object] The invalid input
+      # @return [String] A descriptive error message
+      private_class_method def self.error_message_for(input)
+        return Errors::Argument::Messages::MUST_BE_LETTER unless ::String === input
+        return Errors::Argument::Messages::EMPTY_INPUT    if input.empty?
+        return Errors::Argument::Messages::INPUT_TOO_LONG if input.bytesize > 1
+
+        Errors::Argument::Messages::MUST_BE_LETTER
       end
-
-      # Validates that input is not empty.
-      #
-      # @param input [String] The input to validate
-      # @raise [Errors::Argument] If input is empty
-      # @return [void]
-      private_class_method def self.validate_not_empty!(input)
-        return unless input.empty?
-
-        raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT
-      end
-
-      # Validates that input does not exceed maximum length.
-      #
-      # @param input [String] The input to validate
-      # @raise [Errors::Argument] If input exceeds maximum length
-      # @return [void]
-      private_class_method def self.validate_length!(input)
-        return if input.bytesize <= Constants::MAX_STRING_LENGTH
-
-        raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
-      end
-
-      # Validates that byte is an ASCII letter.
-      #
-      # @param byte [Integer] The byte to validate
-      # @raise [Errors::Argument] If byte is not a letter
-      # @return [void]
-      private_class_method def self.validate_letter!(byte)
-        return if uppercase_letter?(byte) || lowercase_letter?(byte)
-
-        raise Errors::Argument, Errors::Argument::Messages::MUST_BE_LETTER
-      end
-
-      # Extracts style and side from a validated byte.
-      #
-      # @param byte [Integer] A validated ASCII letter byte
-      # @return [Hash] Hash with :style and :side keys
-      private_class_method def self.extract_components(byte)
-        if uppercase_letter?(byte)
-          { style: byte.chr.to_sym, side: :first }
-        else
-          { style: byte.chr.upcase.to_sym, side: :second }
-        end
-      end
-
-      # Reports whether byte is an uppercase ASCII letter (A-Z).
-      #
-      # @param byte [Integer] The byte to check
-      # @return [Boolean] true if A-Z
-      private_class_method def self.uppercase_letter?(byte)
-        byte >= 0x41 && byte <= 0x5A
-      end
-
-      # Reports whether byte is a lowercase ASCII letter (a-z).
-      #
-      # @param byte [Integer] The byte to check
-      # @return [Boolean] true if a-z
-      private_class_method def self.lowercase_letter?(byte)
-        byte >= 0x61 && byte <= 0x7A
-      end
-
-      # @!endgroup
     end
   end
 end

data/lib/sashite/sin.rb

@@ -15,46 +15,101 @@ module Sashite
   # - Uppercase (A-Z) indicates first player
   # - Lowercase (a-z) indicates second player
   #
+  # All 52 valid identifiers are pre-instantiated and frozen at load time.
+  # Every public method returns a cached instance — zero allocation on the
+  # hot path.
+  #
   # @example Parsing SIN strings
   #   sin = Sashite::Sin.parse("C")
-  #   sin.style  # => :C
-  #   sin.side   # => :first
-  #   sin.to_s   # => "C"
-  #
-  # @example Creating identifiers directly
-  #   sin = Sashite::Sin::Identifier.new(:C, :first)
+  #   sin.abbr  # => :C
+  #   sin.side  # => :first
   #   sin.to_s  # => "C"
   #
+  # @example Safe parsing (no exceptions)
+  #   Sashite::Sin.safe_parse("C")   # => #<Sashite::Sin::Identifier C>
+  #   Sashite::Sin.safe_parse("1")   # => nil
+  #   Sashite::Sin.safe_parse(nil)   # => nil
+  #
+  # @example Direct component lookup (fastest path)
+  #   Sashite::Sin.fetch(:C, :first)  # => #<Sashite::Sin::Identifier C>
+  #
+  # @example Identity guarantee (flyweight)
+  #   Sashite::Sin.parse("C").equal?(Sashite::Sin.fetch(:C, :first))  # => true
+  #
   # @example Validation
   #   Sashite::Sin.valid?("C")   # => true
   #   Sashite::Sin.valid?("CC")  # => false
   #
   # @see https://sashite.dev/specs/sin/1.0.0/
   module Sin
-    # Parses a SIN string into an Identifier.
+    # Parses a SIN string into a cached Identifier.
     #
-    # @param input [String] The SIN string to parse
-    # @return [Identifier] The parsed identifier
+    # Returns a pre-instantiated, frozen instance.
+    # Raises ArgumentError if the string is not valid.
+    #
+    # @param input [String] SIN string
+    # @return [Identifier] A cached, frozen Identifier
     # @raise [Errors::Argument] If the input is invalid
     #
     # @example Parsing uppercase (first player)
     #   sin = Sashite::Sin.parse("C")
-    #   sin.style  # => :C
-    #   sin.side   # => :first
+    #   sin.abbr  # => :C
+    #   sin.side  # => :first
     #
     # @example Parsing lowercase (second player)
     #   sin = Sashite::Sin.parse("c")
-    #   sin.style  # => :C
-    #   sin.side   # => :second
+    #   sin.abbr  # => :C
+    #   sin.side  # => :second
     def self.parse(input)
-      components = Parser.parse(input)
+      Parser.parse(input)
+    end
+
+    # Parses a SIN string without raising.
+    #
+    # Returns a cached Identifier on success, nil on failure.
+    # Never allocates exception objects or captures backtraces.
+    #
+    # @param input [String] SIN string
+    # @return [Identifier, nil] A cached Identifier, or nil if invalid
+    #
+    # @example
+    #   Sashite::Sin.safe_parse("C")   # => #<Sashite::Sin::Identifier C>
+    #   Sashite::Sin.safe_parse("")    # => nil
+    #   Sashite::Sin.safe_parse(nil)   # => nil
+    def self.safe_parse(input)
+      Parser.safe_parse(input)
+    end
 
-      Identifier.new(components.fetch(:style), components.fetch(:side))
+    # Retrieves a cached Identifier by abbreviation and side.
+    #
+    # Bypasses string parsing entirely — direct hash lookup into the
+    # flyweight pool. This is the fastest path for callers that already
+    # have structured data.
+    #
+    # @param abbr [Symbol] Style abbreviation (:A through :Z)
+    # @param side [Symbol] Player side (:first or :second)
+    # @return [Identifier] A cached, frozen Identifier
+    # @raise [Errors::Argument] If components are invalid
+    #
+    # @example
+    #   Sashite::Sin.fetch(:C, :first)   # => #<Sashite::Sin::Identifier C>
+    #   Sashite::Sin.fetch(:C, :second)  # => #<Sashite::Sin::Identifier c>
+    def self.fetch(abbr, side)
+      Identifier::POOL.fetch([abbr, side]) do
+        if !Identifier::VALID_ABBRS.include?(abbr)
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_ABBR
+        else
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_SIDE
+        end
+      end
     end
 
-    # Reports whether the input is a valid SIN string.
+    # Reports whether string is a valid SIN identifier.
+    #
+    # Never raises; returns false for any invalid input including non-String.
+    # Uses an exception-free code path internally for performance.
     #
-    # @param input [String] The string to validate
+    # @param input [String] SIN string
     # @return [Boolean] true if valid, false otherwise
     #
     # @example
@@ -63,6 +118,7 @@ module Sashite
     #   Sashite::Sin.valid?("")    # => false
     #   Sashite::Sin.valid?("CC")  # => false
     #   Sashite::Sin.valid?("1")   # => false
+    #   Sashite::Sin.valid?(nil)   # => false
     def self.valid?(input)
       Parser.valid?(input)
     end

data/lib/sashite-sin.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-sin
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -53,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.5
 specification_version: 4
 summary: SIN (Style Identifier Notation) implementation for Ruby with immutable identifier
   objects