sashite-sin 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '080b65573c2e27e8efe5c2ed79009daf31124b35c88ddc7bbe4023e6fe553acf'
-  data.tar.gz: fc25ce0ac44111a41d764aa8badac8ca2727a163e00accd5d8bf52ca301198d0
+  metadata.gz: 611d7fa815981b0a68443f7641f2f780afe46bca6fd8fed0f6204f35b0c2721b
+  data.tar.gz: c414565ed46cb55375c7ec599424dea459999c2162e458ee62be81a49dcf601b
 SHA512:
-  metadata.gz: 93caf9df6d423fa40562f43971b8ea1c1a0c1bba1d4de9d11ee59184d2906638e2d4aa25639ed40010090dfa2929a658e9ba52f714bb46d1616639b6f2983685
-  data.tar.gz: 3d8c978b778d1210e71c288a41daf9f80a750a5a1f975c22a1536f8499f280a7302f0a51c6641d72522b3cc18b88bca5bb94ab7fdac5f8c7de1920b5444fc700
+  metadata.gz: e8e1fa4bbc10f70ba9e17f01292228d538d639f3de6a4e1fc30207f436a1d72133edf502eef557405fce096ecb30c4c9125cd6919f3dc03cb5005e356fcb11f4
+  data.tar.gz: b3904a0fa64f33251e6db3cf6f454578a3dadccb75f8e3b3e885de834ecd6c9b0e0dd53aeaa62587fe9dde5979b991f0b54dc93e10b835ab9bfdad8cd31f4136

data/README.md

@@ -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
@@ -43,33 +55,70 @@ sin = Sashite::Sin.parse("c")
 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
 ```
 
+### Safe Parsing (String → Identifier | nil)
+
+Parse without raising exceptions. Returns `nil` on invalid input.
+
+```ruby
+# 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
+```
+
+### Fetching by Components (Symbol, Symbol → Identifier)
+
+Retrieve a cached identifier directly by abbreviation and side, bypassing string parsing entirely.
+
+```ruby
+# 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>
+
+# Same cached instance as parse
+Sashite::Sin.fetch(:C, :first).equal?(Sashite::Sin.parse("C"))  # => true
+
+# Invalid components raise ArgumentError
+Sashite::Sin.fetch(:CC, :first)    # => raises ArgumentError
+Sashite::Sin.fetch(:C, :third)     # => raises ArgumentError
+```
+
 ### Formatting (Identifier → String)
 
 Convert an `Identifier` back to a SIN string.
 
 ```ruby
-# From Identifier object
-sin = Sashite::Sin::Identifier.new(:C, :first)
+sin = Sashite::Sin.parse("C")
 sin.to_s  # => "C"
 
-sin = Sashite::Sin::Identifier.new(:C, :second)
+sin = Sashite::Sin.parse("c")
 sin.to_s  # => "c"
 ```
 
 ### Validation
 
 ```ruby
-# Boolean check
+# 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
@@ -89,22 +138,55 @@ sin.same_side?(other)  # => false
 
 ## API Reference
 
-### Types
+### Module Methods
+
+```ruby
+# 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)
+
+# 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)
+
+# 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)
+```
+
+### Identifier
 
 ```ruby
 # 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
-  # Creates an Identifier from abbreviation and side.
-  # Raises ArgumentError if attributes are invalid.
-  #
-  # @param abbr [Symbol] Style abbreviation (:A through :Z)
-  # @param side [Symbol] Player side (:first or :second)
-  # @return [Identifier]
-  def initialize(abbr, side)
-
   # Returns the style abbreviation as an uppercase symbol.
   #
-  # @return [Symbol]
+  # @return [Symbol] :A through :Z
   def abbr
 
   # Returns the player side.
@@ -119,35 +201,6 @@ class Sashite::Sin::Identifier
 end
 ```
 
-### Constants
-
-```ruby
-Sashite::Sin::Identifier::VALID_ABBRS  # => [:A, :B, ..., :Z]
-Sashite::Sin::Identifier::VALID_SIDES  # => [:first, :second]
-```
-
-### Parsing
-
-```ruby
-# Parses a SIN string into an Identifier.
-# 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
-
-```ruby
-# Reports whether string is a valid SIN identifier.
-#
-# @param string [String] SIN string
-# @return [Boolean]
-def Sashite::Sin.valid?(string)
-```
-
 ### Queries
 
 ```ruby
@@ -160,9 +213,16 @@ 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 |
 |---------|-------|
@@ -172,12 +232,28 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 
 ## Design Principles
 
-- **Bounded values**: Explicit validation of abbreviations 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**: Instances are frozen after creation
+- **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,13 +4,8 @@ module Sashite
   module Sin
     # Constants for the SIN (Style Identifier Notation) specification.
     #
-    # Defines valid values for abbreviations and sides, as well as formatting constants.
-    #
-    # @example Accessing valid abbreviations
-    #   Constants::VALID_ABBRS  # => [: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
@@ -24,15 +19,38 @@ module Sashite
       # @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/identifier.rb

@@ -11,15 +11,16 @@ module Sashite
     # - 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
@@ -42,15 +43,16 @@ module Sashite
       # @return [Identifier] A new frozen Identifier instance
       # @raise [Errors::Argument] If any attribute is invalid
       #
-      # @example
-      #   Identifier.new(:C, :first)
-      #   Identifier.new(:S, :second)
+      # @api private
       def initialize(abbr, side)
         validate_abbr!(abbr)
         validate_side!(side)
 
         @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,18 +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
-        base = String(abbr)
-
-        case side
-        when :first  then base.upcase
-        when :second then base.downcase
-        end
+        @string
       end
 
       # ========================================================================
@@ -84,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
@@ -94,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
@@ -109,8 +108,8 @@ module Sashite
       # @return [Boolean] true if same abbreviation
       #
       # @example
-      #   sin1 = Identifier.new(:C, :first)
-      #   sin2 = Identifier.new(:C, :second)
+      #   sin1 = Sashite::Sin.parse("C")
+      #   sin2 = Sashite::Sin.parse("c")
       #   sin1.same_abbr?(sin2)  # => true
       def same_abbr?(other)
         abbr.equal?(other.abbr)
@@ -122,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)
@@ -135,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
-
-        abbr.equal?(other.abbr) && 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
-        [abbr, 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
@@ -184,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")  # => { abbr: :C, side: :first }
-    #   Parser.parse("c")  # => { abbr: :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 :abbr and :side keys
+      # @return [Identifier] A pre-instantiated, frozen Identifier
       # @raise [Errors::Argument] If the input is invalid
       #
       # @example
-      #   Parser.parse("C")  # => { abbr: :C, side: :first }
-      #   Parser.parse("s")  # => { abbr: :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 abbr and side from a validated byte.
-      #
-      # @param byte [Integer] A validated ASCII letter byte
-      # @return [Hash] Hash with :abbr and :side keys
-      private_class_method def self.extract_components(byte)
-        if uppercase_letter?(byte)
-          { abbr: byte.chr.to_sym, side: :first }
-        else
-          { abbr: 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,15 +15,26 @@ 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.abbr  # => :C
   #   sin.side  # => :first
   #   sin.to_s  # => "C"
   #
-  # @example Creating identifiers directly
-  #   sin = Sashite::Sin::Identifier.new(:C, :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
@@ -31,10 +42,13 @@ module Sashite
   #
   # @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.
+    #
+    # Returns a pre-instantiated, frozen instance.
+    # Raises ArgumentError if the string is not valid.
     #
-    # @param input [String] The SIN string to parse
-    # @return [Identifier] The parsed identifier
+    # @param input [String] SIN string
+    # @return [Identifier] A cached, frozen Identifier
     # @raise [Errors::Argument] If the input is invalid
     #
     # @example Parsing uppercase (first player)
@@ -47,14 +61,55 @@ module Sashite
     #   sin.abbr  # => :C
     #   sin.side  # => :second
     def self.parse(input)
-      components = Parser.parse(input)
+      Parser.parse(input)
+    end
 
-      Identifier.new(components.fetch(:abbr), components.fetch(:side))
+    # 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
+
+    # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-sin
 version: !ruby/object:Gem::Version
-  version: 3.1.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