sashite-epin 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8b167c50614f455cefd311bd88371733b9814812cf2f4d088df9e236f3c1750
-  data.tar.gz: 92584852d10ecb7c170c487c8aa6dce7de4f93a554cb65d9b598b465a6045568
+  metadata.gz: 4ac0199440bdaa03bc8fc740c81d9b2dcc3981696cae3918912514f6cf7f9432
+  data.tar.gz: 92c9b3f52c29c94927cdf34cb5693f7809d163b48d5a53afe96c22f58899aa0f
 SHA512:
-  metadata.gz: 53e1413b668e75ae17fdb287b414ca7674da8d8f3b850235901b945ddd9f8d3bc8fa6565b6ab39d93c6b9d967b2989693036a9961656245059195d3ff63015d9
-  data.tar.gz: ac63eae948c8c503d68361ded298793c7798064a17c3e4dc009bf1d757c6651379e0585bd3aa76f3b0617b6a77375101c05e3914bb50dfa78a184d6d0ae030c9
+  metadata.gz: 6164416ce6ebc9a9c3c5b279e065dbf29209b7567b0e0da87d6a10c56801396d1383edcfe91807fb70d79bb776f0bf5059b1f7a589a0b19c0c36385a445b93f3
+  data.tar.gz: 795d504a06ef64d1acc3c246fe3e0ef3055b55b19373baf756a3399f93050bb5c9da6604d917b44a59bd7bda6d547db6d7d4189c8a04bc7b154ffe49d80ee6af

data/README.md

@@ -11,7 +11,17 @@
 
 This library implements the [EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/).
 
-EPIN extends [PIN](https://sashite.dev/specs/pin/1.0.0/) with an optional derivation marker (`'`) that flags whether a piece uses a native or derived style.
+EPIN extends [PIN](https://sashite.dev/specs/pin/1.0.0/) with an optional derivation marker (`'`) that flags whether a piece uses a native or derived style. Every valid PIN token is also a valid EPIN token (native by default).
+
+### Implementation Constraints
+
+| Constraint | Value | Rationale |
+|------------|-------|-----------|
+| Token length | 1–4 characters | `[+-]?[A-Za-z]\^?'?` per spec |
+| Character space | 624 tokens | 312 PIN tokens × 2 derivation statuses |
+| Instance pool | 624 objects | All identifiers are pre-instantiated and frozen |
+
+The closed domain of 624 possible values enables a flyweight architecture with zero allocation on the hot path.
 
 ## Installation
 
@@ -55,60 +65,78 @@ epin.pin.terminal?  # => true
 epin.derived?  # => true
 epin.native?   # => false
 
-# PIN component is a full Sashite::Pin::Identifier instance
+# PIN component is a cached Sashite::Pin::Identifier instance
 epin.pin.enhanced?      # => false
 epin.pin.first_player?  # => true
 
+# Returns a cached instance — no allocation
+Sashite::Epin.parse("K^'").equal?(Sashite::Epin.parse("K^'"))  # => true
+
 # Invalid input raises ArgumentError
 Sashite::Epin.parse("invalid")  # => raises ArgumentError
 ```
 
-### Formatting (Identifier → String)
+### Safe Parsing (String → Identifier | nil)
 
-Convert an `Identifier` back to an EPIN string.
+Parse without raising exceptions. Returns `nil` on invalid input.
 
 ```ruby
-# From PIN component
+# Valid input returns an Identifier
+Sashite::Epin.safe_parse("K^'")   # => #<Sashite::Epin::Identifier K^'>
+Sashite::Epin.safe_parse("+R")    # => #<Sashite::Epin::Identifier +R>
+
+# Invalid input returns nil — no exception allocated
+Sashite::Epin.safe_parse("")        # => nil
+Sashite::Epin.safe_parse("invalid") # => nil
+Sashite::Epin.safe_parse("K''")     # => nil
+Sashite::Epin.safe_parse(nil)       # => nil
+```
+
+### Fetching by Components (Pin::Identifier, ... → Identifier)
+
+Retrieve a cached identifier directly by components, bypassing string parsing entirely.
+
+```ruby
+# From a cached PIN instance — direct hash lookup, no allocation
 pin = Sashite::Pin.parse("K^")
-epin = Sashite::Epin::Identifier.new(pin)
-epin.to_s  # => "K^"
+Sashite::Epin.fetch(pin)                  # => #<Sashite::Epin::Identifier K^>
+Sashite::Epin.fetch(pin, derived: true)   # => #<Sashite::Epin::Identifier K^'>
+
+# Same cached instance as parse
+Sashite::Epin.fetch(pin, derived: true).equal?(Sashite::Epin.parse("K^'"))  # => true
+
+# Invalid PIN raises ArgumentError
+Sashite::Epin.fetch(nil)  # => raises ArgumentError
+```
+
+### Formatting (Identifier → String)
 
-# With derivation
-epin = Sashite::Epin::Identifier.new(pin, derived: true)
+Convert an `Identifier` back to an EPIN string.
+
+```ruby
+epin = Sashite::Epin.parse("K^'")
 epin.to_s  # => "K^'"
+
+epin = Sashite::Epin.parse("+r")
+epin.to_s  # => "+r"
 ```
 
 ### Validation
 
 ```ruby
-# Boolean check
+# Boolean check (never raises)
+# Uses an exception-free code path internally for performance.
 Sashite::Epin.valid?("K")         # => true
 Sashite::Epin.valid?("+R^'")      # => true
 Sashite::Epin.valid?("invalid")   # => false
 Sashite::Epin.valid?("K''")       # => false
 Sashite::Epin.valid?("K'^")       # => false
-```
-
-### Accessing Components
-
-```ruby
-epin = Sashite::Epin.parse("+R^'")
-
-# Get PIN component
-epin.pin       # => #<Sashite::Pin::Identifier +R^>
-epin.pin.to_s  # => "+R^"
-
-# Check derivation
-epin.derived?  # => true
-epin.native?   # => false
-
-# Serialize
-epin.to_s  # => "+R^'"
+Sashite::Epin.valid?(nil)         # => false
 ```
 
 ### Transformations
 
-All transformations return new immutable instances.
+All transformations return cached instances from the flyweight pool — no new object is ever allocated.
 
 ```ruby
 epin = Sashite::Epin.parse("K^")
@@ -120,10 +148,15 @@ epin.native.to_s  # => "K^"
 # Replace PIN component
 new_pin = Sashite::Pin.parse("+Q^")
 epin.with_pin(new_pin).to_s  # => "+Q^"
+
+# Transformations return cached instances
+epin.derive.equal?(Sashite::Epin.parse("K^'"))  # => true
 ```
 
 ### Transform via PIN Component
 
+PIN transformations also return cached instances, so the entire chain is allocation-free.
+
 ```ruby
 epin = Sashite::Epin.parse("K^'")
 
@@ -140,6 +173,23 @@ epin.with_pin(epin.pin.flip).to_s  # => "k^'"
 epin.with_pin(epin.pin.non_terminal).to_s  # => "K'"
 ```
 
+### Accessing Components
+
+```ruby
+epin = Sashite::Epin.parse("+R^'")
+
+# Get PIN component (cached Pin::Identifier instance)
+epin.pin       # => #<Sashite::Pin::Identifier +R^>
+epin.pin.to_s  # => "+R^"
+
+# Check derivation
+epin.derived?  # => true
+epin.native?   # => false
+
+# Serialize
+epin.to_s  # => "+R^'"
+```
+
 ### Component Queries
 
 Use the PIN API directly:
@@ -166,22 +216,68 @@ epin.pin.same_state?(other.pin)  # => true
 epin.same_derived?(other)        # => false
 ```
 
+### PIN Compatibility
+
+Every valid PIN is a valid EPIN (native by default):
+
+```ruby
+%w[K +R -p K^ +R^].each do |pin_token|
+  epin = Sashite::Epin.parse(pin_token)
+  epin.native?  # => true
+  epin.to_s     # => pin_token
+end
+```
+
 ## API Reference
 
-### Types
+### Module Methods
+
+```ruby
+# Parses an EPIN string into a cached Identifier.
+# Returns a pre-instantiated, frozen instance.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] EPIN string
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Epin.parse(string)
+
+# Parses an EPIN string without raising.
+# Returns a cached Identifier on success, nil on failure.
+# Never allocates exception objects or captures backtraces.
+# Delegates to Pin.safe_parse for the PIN component.
+#
+# @param string [String] EPIN string
+# @return [Identifier, nil]
+def Sashite::Epin.safe_parse(string)
+
+# Retrieves a cached Identifier by PIN component and derivation status.
+# Bypasses string parsing entirely — direct hash lookup.
+# Raises ArgumentError if the PIN is invalid.
+#
+# @param pin [Sashite::Pin::Identifier] PIN component
+# @param derived [Boolean] Derived status
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Epin.fetch(pin, derived: false)
+
+# Reports whether string is a valid EPIN.
+# Never raises; returns false for any invalid input.
+# Uses an exception-free code path internally for performance.
+#
+# @param string [String] EPIN string
+# @return [Boolean]
+def Sashite::Epin.valid?(string)
+```
+
+### Identifier
 
 ```ruby
 # Identifier represents a parsed EPIN combining PIN with derivation status.
+# All instances are frozen and pre-instantiated — never construct directly,
+# use Sashite::Epin.parse, .safe_parse, or .fetch instead.
 class Sashite::Epin::Identifier
-  # Creates an Identifier from a PIN component.
-  # Raises ArgumentError if the PIN is invalid.
-  #
-  # @param pin [Sashite::Pin::Identifier] PIN component
-  # @param derived [Boolean] Derived status
-  # @return [Identifier]
-  def initialize(pin, derived: false)
-
-  # Returns the PIN component.
+  # Returns the PIN component (a cached Sashite::Pin::Identifier instance).
   #
   # @return [Sashite::Pin::Identifier]
   def pin
@@ -203,32 +299,12 @@ class Sashite::Epin::Identifier
 end
 ```
 
-### Parsing
-
-```ruby
-# Parses an EPIN string into an Identifier.
-# Raises ArgumentError if the string is not valid.
-#
-# @param string [String] EPIN string
-# @return [Identifier]
-# @raise [ArgumentError] if invalid
-def Sashite::Epin.parse(string)
-```
-
-### Validation
-
-```ruby
-# Reports whether string is a valid EPIN.
-#
-# @param string [String] EPIN string
-# @return [Boolean]
-def Sashite::Epin.valid?(string)
-```
-
 ### Transformations
 
+All transformations return cached `Sashite::Epin::Identifier` instances from the flyweight pool:
+
 ```ruby
-# PIN replacement (returns new Identifier)
+# PIN replacement (returns cached Identifier)
 def with_pin(new_pin)  # => Identifier with different PIN
 
 # Derivation transformations
@@ -238,32 +314,39 @@ def native  # => Identifier with derived: false
 
 ### Errors
 
-All parsing and validation errors raise `ArgumentError` with descriptive messages:
+All errors raise `ArgumentError` with descriptive messages:
 
 | Message | Cause |
 |---------|-------|
 | `"invalid derivation marker"` | Derivation marker misplaced or duplicated |
 | `"invalid PIN component: ..."` | PIN parsing failed |
 
-## PIN Compatibility
-
-Every valid PIN is a valid EPIN (native by default):
-
-```ruby
-%w[K +R -p K^ +R^].each do |pin_token|
-  epin = Sashite::Epin.parse(pin_token)
-  epin.native?  # => true
-  epin.to_s     # => pin_token
-end
-```
-
 ## Design Principles
 
-- **Pure composition**: EPIN composes PIN without reimplementing features
-- **Minimal API**: Core methods (`pin`, `derived?`, `native?`, `to_s`) plus transformations
+- **Spec conformance**: Strict adherence to EPIN v1.0.0
+- **Flyweight identifiers**: All 624 possible instances are pre-built and frozen; parsing, fetching, and transformations return cached objects with zero allocation
+- **Pure composition**: EPIN composes PIN without reimplementing features; each EPIN instance holds a cached `Pin::Identifier` from PIN's own flyweight pool
+- **Performance-oriented internals**: Exception-free validation path; exceptions only at the public API boundary
 - **Component transparency**: Access PIN directly, no wrapper methods
-- **Immutable identifiers**: Frozen instances prevent mutation
 - **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Immutable identifiers**: All instances are frozen after creation
+
+### Performance Architecture
+
+EPIN has a closed domain of exactly 624 valid tokens (312 PIN tokens × 2 derivation statuses). The implementation exploits this constraint through three complementary strategies, composing cleanly with PIN's own flyweight pool.
+
+**Flyweight instance pool** — All 624 `Identifier` objects are pre-instantiated and frozen at load time. Each holds a reference to a cached `Pin::Identifier` from PIN's own pool — no duplication of PIN objects. `parse`, `safe_parse`, `fetch`, and all transformation methods return these cached instances via hash lookup. No `Identifier` is ever allocated after the module loads.
+
+**Dual-path parsing** — Parsing is split into two layers to avoid using exceptions for control flow:
+
+- **Validation layer** — `safe_parse` strips the trailing `'` if present, delegates to `Pin.safe_parse` for the core token, and returns the cached `Identifier` on success or `nil` on failure. The entire path — EPIN and PIN combined — never raises, never allocates exception objects, and never captures 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.
+
+**Zero-allocation transformations** — `derive`, `native`, and `with_pin` compute the target components and perform a direct lookup into the instance pool. Since PIN transformations (`flip`, `enhance`, etc.) also return cached instances, chaining like `epin.with_pin(epin.pin.flip.enhance).derive` performs only hash lookups across both pools — zero allocations end to end.
+
+**Direct component lookup** — `fetch` accepts a `Pin::Identifier` and a derivation flag, performing a single hash lookup. This is the fastest path for callers that already have structured data (e.g., FEEN's piece placement parser constructing EPIN identifiers from already-parsed PIN components).
+
+This architecture ensures that the full SIN → PIN → EPIN → FEEN stack maintains allocation-free hot paths from bottom to top.
 
 ## Related Specifications
 

data/lib/sashite/epin/constants.rb

@@ -5,11 +5,17 @@ module Sashite
     # Constants for EPIN (Extended Piece Identifier Notation).
     #
     # EPIN extends PIN with a single derivation marker.
-    # PIN constants (VALID_TYPES, VALID_SIDES, VALID_STATES, etc.)
+    # PIN constants (VALID_ABBRS, VALID_SIDES, VALID_STATES, etc.)
     # are accessed through the sashite-pin dependency.
     module Constants
       # Derivation marker suffix.
       DERIVATION_SUFFIX = "'"
+
+      # Maximum length of a valid EPIN string: [+-]?[A-Za-z]\^?'?
+      MAX_STRING_LENGTH = 4
+
+      # Total number of valid EPIN tokens (312 PIN tokens × 2 derivation statuses).
+      POOL_SIZE = 624
     end
   end
 end

data/lib/sashite/epin/identifier.rb

@@ -13,17 +13,20 @@ module Sashite
     # - PIN: encodes abbr, side, state, and terminal status
     # - Derived: indicates whether the piece uses native or derived style
     #
-    # Instances are immutable (frozen after creation).
+    # All 624 possible instances (312 PIN tokens × 2 derivation statuses) are
+    # pre-instantiated and frozen at load time. Parsing, fetching, and all
+    # transformation methods return these cached instances via hash lookup —
+    # no Identifier is ever allocated after the module loads.
     #
-    # @example Creating identifiers
+    # @example Access via module methods (recommended)
+    #   epin = Sashite::Epin.parse("K^'")
+    #   epin = Sashite::Epin.fetch(pin, derived: true)
+    #
+    # @example Direct construction (mainly for tests / pool building)
     #   pin = Sashite::Pin.parse("K^")
     #   epin = Identifier.new(pin)
     #   epin = Identifier.new(pin, derived: true)
     #
-    # @example String conversion
-    #   Identifier.new(pin).to_s                  # => "K^"
-    #   Identifier.new(pin, derived: true).to_s   # => "K^'"
-    #
     # @see https://sashite.dev/specs/epin/1.0.0/
     class Identifier
       # @return [Sashite::Pin::Identifier] PIN component
@@ -41,11 +44,13 @@ module Sashite
       #   Identifier.new(pin)
       #   Identifier.new(pin, derived: true)
       def initialize(pin, derived: false)
-        validate_pin!(pin)
-        validate_derived!(derived)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN unless ::Sashite::Pin::Identifier === pin
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVED unless true == derived || false == derived
 
         @pin = pin
         @derived = derived
+        @string = (derived ? "#{pin}#{Constants::DERIVATION_SUFFIX}" : pin.to_s).freeze
+        @hash = (pin.hash ^ (derived ? 1 : 0).hash).freeze
 
         freeze
       end
@@ -77,6 +82,7 @@ module Sashite
       # ========================================================================
 
       # Returns the EPIN string representation.
+      # Pre-computed at construction time — zero allocation.
       #
       # @return [String] The EPIN string
       #
@@ -84,53 +90,55 @@ module Sashite
       #   Identifier.new(pin).to_s                  # => "K^"
       #   Identifier.new(pin, derived: true).to_s   # => "K^'"
       def to_s
-        derived? ? "#{pin}#{Constants::DERIVATION_SUFFIX}" : pin.to_s
+        @string
       end
 
       # ========================================================================
-      # Transformations
+      # Transformations (pool lookups — zero allocation)
       # ========================================================================
 
-      # Returns a new Identifier with a different PIN component.
+      # Returns a cached Identifier with a different PIN component.
       #
       # @param new_pin [Sashite::Pin::Identifier] The new PIN component
-      # @return [Identifier] A new Identifier with the specified PIN
+      # @return [Identifier] A cached Identifier with the specified PIN
       # @raise [Errors::Argument] If the PIN is invalid
       #
       # @example
-      #   epin = Identifier.new(pin, derived: true)
+      #   epin = Sashite::Epin.parse("K^'")
       #   new_pin = Sashite::Pin.parse("+Q^")
       #   epin.with_pin(new_pin).to_s  # => "+Q^'"
       def with_pin(new_pin)
-        return self if pin == new_pin
+        return self if pin.equal?(new_pin)
 
-        self.class.new(new_pin, derived: @derived)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN unless ::Sashite::Pin::Identifier === new_pin
+
+        self.class.fetch(new_pin, @derived)
       end
 
-      # Returns a new Identifier marked as derived.
+      # Returns a cached Identifier marked as derived.
       #
-      # @return [Identifier] A new Identifier with derived: true
+      # @return [Identifier] A cached Identifier with derived: true
       #
       # @example
-      #   epin = Identifier.new(pin)
+      #   epin = Sashite::Epin.parse("K^")
       #   epin.derive.to_s  # => "K^'"
       def derive
-        return self if derived?
+        return self if @derived
 
-        self.class.new(pin, derived: true)
+        self.class.fetch(pin, true)
       end
 
-      # Returns a new Identifier marked as native.
+      # Returns a cached Identifier marked as native.
       #
-      # @return [Identifier] A new Identifier with derived: false
+      # @return [Identifier] A cached Identifier with derived: false
       #
       # @example
-      #   epin = Identifier.new(pin, derived: true)
+      #   epin = Sashite::Epin.parse("K^'")
       #   epin.native.to_s  # => "K^"
       def native
-        return self if native?
+        return self if !@derived
 
-        self.class.new(pin, derived: false)
+        self.class.fetch(pin, false)
       end
 
       # ========================================================================
@@ -143,8 +151,8 @@ module Sashite
       # @return [Boolean] true if same derived status
       #
       # @example
-      #   epin1 = Identifier.new(pin1, derived: true)
-      #   epin2 = Identifier.new(pin2, derived: true)
+      #   epin1 = Sashite::Epin.parse("K'")
+      #   epin2 = Sashite::Epin.parse("Q'")
       #   epin1.same_derived?(epin2)  # => true
       def same_derived?(other)
         @derived == other.derived?
@@ -166,11 +174,11 @@ module Sashite
 
       alias eql? ==
 
-      # Returns a hash code for the Identifier.
+      # Returns a pre-computed hash code for the Identifier.
       #
       # @return [Integer] Hash code
       def hash
-        [pin, @derived].hash
+        @hash
       end
 
       # Returns an inspect string for the Identifier.
@@ -180,23 +188,43 @@ module Sashite
         "#<#{self.class} #{self}>"
       end
 
-      private
-
       # ========================================================================
-      # Private Validation
+      # Flyweight Pool (class-level)
       # ========================================================================
 
-      def validate_pin!(pin)
-        return if ::Sashite::Pin::Identifier === pin
-
-        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN
+      class << self
+        # Retrieves a cached Identifier from the flyweight pool.
+        # Direct hash lookup — no validation, no allocation.
+        #
+        # @param pin [Sashite::Pin::Identifier] PIN component (must be from PIN's pool)
+        # @param derived [Boolean] Derived status
+        # @return [Identifier] A cached Identifier
+        # @api private
+        def fetch(pin, derived)
+          derived ? @derived_pool[pin] : @native_pool[pin]
+        end
       end
 
-      def validate_derived!(derived)
-        return if ::TrueClass === derived || ::FalseClass === derived
-
-        raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVED
+      # Build the flyweight pool at load time.
+      # Two separate hashes (native/derived) keyed by PIN instance
+      # for single-lookup access with no Array allocation for the key.
+      @native_pool = {}
+      @derived_pool = {}
+
+      ::Sashite::Pin::Constants::VALID_ABBRS.each do |abbr|
+        ::Sashite::Pin::Constants::VALID_SIDES.each do |side|
+          ::Sashite::Pin::Constants::VALID_STATES.each do |state|
+            [false, true].each do |terminal|
+              pin = ::Sashite::Pin.fetch(abbr, side, state, terminal: terminal)
+              @native_pool[pin]  = new(pin, derived: false)
+              @derived_pool[pin] = new(pin, derived: true)
+            end
+          end
+        end
       end
+
+      @native_pool.freeze
+      @derived_pool.freeze
     end
   end
 end

data/lib/sashite/epin/parser.rb

@@ -4,40 +4,69 @@ require "sashite/pin"
 
 require_relative "constants"
 require_relative "errors"
+require_relative "identifier"
 
 module Sashite
   module Epin
     # Parser for EPIN (Extended Piece Identifier Notation) strings.
     #
-    # This parser extracts the derivation marker and delegates PIN parsing
-    # to the sashite-pin library.
+    # Dual-path architecture for performance:
+    # - {safe_parse}: core path — returns a cached Identifier or nil.
+    #   Never raises, never allocates exceptions, never captures backtraces.
+    # - {parse}: public API — delegates to safe_parse, raises once at boundary on failure.
+    # - {valid?}: boolean wrapper around safe_parse — never raises.
     #
     # @example
-    #   Parser.parse("K")    # => { pin: { abbr: :K, side: :first, ... }, derived: false }
-    #   Parser.parse("K^'")  # => { pin: { abbr: :K, side: :first, ..., terminal: true }, derived: true }
+    #   Parser.safe_parse("K^'")  # => #<Sashite::Epin::Identifier K^'>
+    #   Parser.safe_parse("bad")  # => nil
+    #   Parser.parse("K^'")      # => #<Sashite::Epin::Identifier K^'>
+    #   Parser.valid?("K^'")     # => true
     #
     # @see https://sashite.dev/specs/epin/1.0.0/
     module Parser
-      # Parses an EPIN string into its components.
+      # ASCII byte value of the derivation marker.
+      APOSTROPHE_BYTE = 39 # ' = 0x27
+
+      private_constant :APOSTROPHE_BYTE
+
+      # Parses an EPIN string without raising an exception.
+      # This is the core parsing path — all other methods delegate here.
       #
       # @param input [String] The EPIN string to parse
-      # @return [Hash] A hash with :pin (PIN components hash) and :derived keys
-      # @raise [Errors::Argument] If the input is not a valid EPIN string
-      def self.parse(input)
-        validate_string!(input)
+      # @return [Identifier, nil] A cached Identifier on success, nil on failure
+      def self.safe_parse(input)
+        return nil unless ::String === input
+
+        len = input.bytesize
+        return nil if len == 0 || len > Constants::MAX_STRING_LENGTH
 
-        derived = has_derivation_marker?(input)
+        # Check derivation marker: single byte check on last position.
+        if input.getbyte(len - 1) == APOSTROPHE_BYTE
+          pin = ::Sashite::Pin.safe_parse(input.byteslice(0, len - 1))
+          return nil if pin.nil?
 
-        if derived
-          validate_derivation_marker!(input)
-          pin_string = input.chop
+          Identifier.fetch(pin, true)
         else
-          pin_string = input
+          pin = ::Sashite::Pin.safe_parse(input)
+          return nil if pin.nil?
+
+          Identifier.fetch(pin, false)
         end
+      end
 
-        pin_components = parse_pin_component(pin_string)
+      # Parses an EPIN string into a cached Identifier.
+      # Delegates to {safe_parse} for the happy path.
+      # On failure, performs detailed validation to raise a precise error.
+      #
+      # @param input [String] The EPIN string to parse
+      # @return [Identifier] A cached Identifier
+      # @raise [Errors::Argument] If the input is not a valid EPIN string
+      def self.parse(input)
+        result = safe_parse(input)
+        return result unless result.nil?
 
-        { pin: pin_components, derived: derived }
+        # Slow path: detailed validation for precise error messages.
+        raise_parse_error!(input)
       end
 
       # Validates an EPIN string without raising an exception.
@@ -45,57 +74,45 @@ module Sashite
       # @param input [String] The EPIN string to validate
       # @return [Boolean] true if valid, false otherwise
       def self.valid?(input)
-        return false unless ::String === input
-
-        parse(input)
-        true
-      rescue Errors::Argument
-        false
+        !safe_parse(input).nil?
       end
 
       class << self
         private
 
-        # Validates that input is a String.
-        #
-        # @param input [Object] The input to validate
-        # @raise [Errors::Argument] If input is not a String
-        def validate_string!(input)
-          return if ::String === input
-
-          raise Errors::Argument, "invalid PIN component: must contain exactly one letter"
-        end
-
-        # Checks if the input contains a derivation marker.
-        #
-        # @param input [String] The input to check
-        # @return [Boolean] true if contains derivation marker
-        def has_derivation_marker?(input)
-          input.include?(Constants::DERIVATION_SUFFIX)
-        end
-
-        # Validates derivation marker position and uniqueness.
-        #
-        # @param input [String] The input to validate
-        # @raise [Errors::Argument] If derivation marker is invalid
-        def validate_derivation_marker!(input)
-          count = input.count(Constants::DERIVATION_SUFFIX)
-          last_char = input[-1]
-
-          return if count == 1 && last_char == Constants::DERIVATION_SUFFIX
-
-          raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVATION_MARKER
-        end
-
-        # Parses the PIN component using sashite-pin.
+        # Performs detailed validation on an already-known-invalid input
+        # to produce a precise error message.
         #
-        # @param pin_string [String] The PIN string to parse
-        # @return [Hash] PIN components hash
-        # @raise [Errors::Argument] If PIN parsing fails
-        def parse_pin_component(pin_string)
-          ::Sashite::Pin::Parser.parse(pin_string)
-        rescue ::Sashite::Pin::Errors::Argument => e
-          raise Errors::Argument, "invalid PIN component: #{e.message}"
+        # @param input [Object] The invalid input
+        # @raise [Errors::Argument] Always raises with a descriptive message
+        def raise_parse_error!(input)
+          unless ::String === input
+            raise Errors::Argument, "invalid PIN component: must contain exactly one letter"
+          end
+
+          # Check derivation marker issues first.
+          if input.include?(Constants::DERIVATION_SUFFIX)
+            count = input.count(Constants::DERIVATION_SUFFIX)
+
+            unless count == 1 && input.getbyte(input.bytesize - 1) == APOSTROPHE_BYTE
+              raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVATION_MARKER
+            end
+
+            pin_string = input.chop
+          else
+            pin_string = input
+          end
+
+          # Delegate to PIN's raising parser for a precise PIN error message.
+          begin
+            ::Sashite::Pin::Parser.parse(pin_string)
+          rescue ::Sashite::Pin::Errors::Argument => e
+            raise Errors::Argument, "invalid PIN component: #{e.message}"
+          end
+
+          # Unreachable in normal operation: if safe_parse returned nil,
+          # one of the checks above should have raised. Guard against edge cases.
+          raise Errors::Argument, "invalid EPIN token"
         end
       end
     end

data/lib/sashite/epin.rb

@@ -13,6 +13,10 @@ module Sashite
   # EPIN extends PIN with an optional derivation marker (') that flags
   # whether a piece uses a native or derived style.
   #
+  # All 624 possible identifiers (312 PIN tokens × 2 derivation statuses)
+  # are pre-instantiated and frozen at load time. Every public method
+  # returns a cached instance — zero allocation on the hot path.
+  #
   # == Format
   #
   #   <pin>[']
@@ -36,10 +40,12 @@ module Sashite
   #
   # @see https://sashite.dev/specs/epin/1.0.0/
   module Epin
-    # Parses an EPIN string into an Identifier.
+    # Parses an EPIN string into a cached Identifier.
+    # Returns a pre-instantiated, frozen instance.
+    # Raises ArgumentError if the string is not valid.
     #
     # @param string [String] The EPIN string to parse
-    # @return [Identifier] A new Identifier instance
+    # @return [Identifier] A cached Identifier instance
     # @raise [Errors::Argument] If the string is not a valid EPIN
     #
     # @example
@@ -52,27 +58,59 @@ module Sashite
     #   Sashite::Epin.parse("invalid")
     #   # => raises Errors::Argument
     def self.parse(string)
-      components = Parser.parse(string)
+      Parser.parse(string)
+    end
 
-      pin = ::Sashite::Pin::Identifier.new(
-        components[:pin][:abbr],
-        components[:pin][:side],
-        components[:pin][:state],
-        terminal: components[:pin][:terminal]
-      )
+    # Parses an EPIN string without raising.
+    # Returns a cached Identifier on success, nil on failure.
+    # Never allocates exception objects or captures backtraces.
+    # Delegates to Pin.safe_parse for the PIN component.
+    #
+    # @param string [String] The EPIN string to parse
+    # @return [Identifier, nil] A cached Identifier or nil
+    #
+    # @example
+    #   Sashite::Epin.safe_parse("K^'")    # => #<Sashite::Epin::Identifier K^'>
+    #   Sashite::Epin.safe_parse("+R")     # => #<Sashite::Epin::Identifier +R>
+    #   Sashite::Epin.safe_parse("")       # => nil
+    #   Sashite::Epin.safe_parse("K''")    # => nil
+    #   Sashite::Epin.safe_parse(nil)      # => nil
+    def self.safe_parse(string)
+      Parser.safe_parse(string)
+    end
+
+    # Retrieves a cached Identifier by PIN component and derivation status.
+    # Bypasses string parsing entirely — direct hash lookup.
+    # Raises ArgumentError if the PIN is invalid.
+    #
+    # @param pin [Sashite::Pin::Identifier] PIN component
+    # @param derived [Boolean] Derived status (default: false)
+    # @return [Identifier] A cached Identifier
+    # @raise [Errors::Argument] If the PIN is not a Sashite::Pin::Identifier
+    #
+    # @example
+    #   pin = Sashite::Pin.parse("K^")
+    #   Sashite::Epin.fetch(pin)                  # => #<Sashite::Epin::Identifier K^>
+    #   Sashite::Epin.fetch(pin, derived: true)   # => #<Sashite::Epin::Identifier K^'>
+    def self.fetch(pin, derived: false)
+      raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN unless ::Sashite::Pin::Identifier === pin
+      raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVED unless true == derived || false == derived
 
-      Identifier.new(pin, derived: components[:derived])
+      Identifier.fetch(pin, derived)
     end
 
-    # Checks if a string is a valid EPIN notation.
+    # Reports whether string is a valid EPIN.
+    # Never raises; returns false for any invalid input.
+    # Uses an exception-free code path internally for performance.
     #
-    # @param string [String] The string to validate
+    # @param string [String] The EPIN string to validate
     # @return [Boolean] true if valid, false otherwise
     #
     # @example
     #   Sashite::Epin.valid?("K")        # => true
     #   Sashite::Epin.valid?("K^'")      # => true
     #   Sashite::Epin.valid?("invalid")  # => false
+    #   Sashite::Epin.valid?(nil)        # => false
     def self.valid?(string)
       Parser.valid?(string)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-epin
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 4.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 4.2.0
 description: |
   EPIN (Extended Piece Identifier Notation) implementation for Ruby.
   Extends PIN by adding a derivation marker to track piece style in cross-style
@@ -43,7 +43,7 @@ files:
 - lib/sashite/epin/parser.rb
 homepage: https://github.com/sashite/epin.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/sashite/epin.rb/issues
   documentation_uri: https://rubydoc.info/github/sashite/epin.rb/main
@@ -65,7 +65,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: EPIN (Extended Piece Identifier Notation) implementation for Ruby extending
   PIN with style derivation markers.