sashite-sin 2.1.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28dcd89f0b19451fd1f6455117c8094083dd0da16300e59c3b8aad0987353cc2
-  data.tar.gz: a21dd87d8a1437cad75f0c55c74e7cce93a3d69897384346dcb0ecedf5f7f6c1
+  metadata.gz: '080b65573c2e27e8efe5c2ed79009daf31124b35c88ddc7bbe4023e6fe553acf'
+  data.tar.gz: fc25ce0ac44111a41d764aa8badac8ca2727a163e00accd5d8bf52ca301198d0
 SHA512:
-  metadata.gz: dc4c9ae269c163a60e65c052013154c1709b79e781077ccf16c084a540e13f1303d2122de46f956e2e79d312d6ff106b4081ce0200bfa4296fe0a9e9402dda49
-  data.tar.gz: bcfa66181f441356daa3f7bfb5dfaf609b629728d17c8c798d0ac4af26da3d159954e13e9aa9fb87483c0979ab8f3cb54b7f6bdb3cca870d2ae0a2819a0a0f89
+  metadata.gz: 93caf9df6d423fa40562f43971b8ea1c1a0c1bba1d4de9d11ee59184d2906638e2d4aa25639ed40010090dfa2929a658e9ba52f714bb46d1616639b6f2983685
+  data.tar.gz: 3d8c978b778d1210e71c288a41daf9f80a750a5a1f975c22a1536f8499f280a7302f0a51c6641d72522b3cc18b88bca5bb94ab7fdac5f8c7de1920b5444fc700

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   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.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,17 +1,15 @@
-# Sin.rb
+# sin.rb
 
 [![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)
-![Ruby](https://github.com/sashite/sin.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/sin.rb?label=License&logo=github)](https://github.com/sashite/sin.rb/raw/main/LICENSE.md)
+[![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 the Ruby language.
+> **SIN** (Style Identifier Notation) implementation for Ruby.
 
-## What is SIN?
+## Overview
 
-SIN (Style Identifier Notation) provides a compact, ASCII-based format for identifying **styles** in abstract strategy board games. SIN uses single-character identifiers with case encoding to represent both style identity and player assignment simultaneously.
-
-This gem implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) exactly, providing a rule-agnostic notation system for style identification in board games.
+This library implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/).
 
 ## Installation
 
@@ -28,321 +26,164 @@ gem install sashite-sin
 
 ## Usage
 
-### Basic Operations
-
-```ruby
-require "sashite/sin"
-
-# Parse SIN strings into identifier objects
-identifier = Sashite::Sin.parse("C")           # Family=:C, Side=:first
-identifier.to_s                                # => "C"
-identifier.family                              # => :C
-identifier.side                                # => :first
-identifier.letter                              # => "C" (combined representation)
-
-# Create identifiers directly
-identifier = Sashite::Sin.identifier(:C, :first)           # Family=:C, Side=:first
-identifier = Sashite::Sin::Identifier.new(:C, :second)     # Family=:C, Side=:second
-
-# Validate SIN strings
-Sashite::Sin.valid?("C")                 # => true
-Sashite::Sin.valid?("c")                 # => true
-Sashite::Sin.valid?("1")                 # => false (not a letter)
-Sashite::Sin.valid?("CC")                # => false (not single character)
-```
+### Parsing (String → Identifier)
 
-### Identifier Transformations
+Convert a SIN string into an `Identifier` object.
 
 ```ruby
-# All transformations return new immutable instances
-identifier = Sashite::Sin.parse("C")
-
-# Flip player assignment
-flipped = identifier.flip # Family=:C, Side=:second
-flipped.to_s # => "c"
+require "sashite/sin"
 
-# Change family
-changed = identifier.with_family(:S) # Family=:S, Side=:first
-changed.to_s # => "S"
+# Standard parsing (raises on error)
+sin = Sashite::Sin.parse("C")
+sin.abbr  # => :C
+sin.side  # => :first
 
-# Change side
-other_side = identifier.with_side(:second) # Family=:C, Side=:second
-other_side.to_s # => "c"
+# Lowercase indicates second player
+sin = Sashite::Sin.parse("c")
+sin.abbr  # => :C
+sin.side  # => :second
 
-# Chain transformations
-result = identifier.flip.with_family(:M) # Family=:M, Side=:second
-result.to_s # => "m"
+# Invalid input raises ArgumentError
+Sashite::Sin.parse("")    # => raises ArgumentError
+Sashite::Sin.parse("CC")  # => raises ArgumentError
 ```
 
-### Player and Style Queries
+### Formatting (Identifier → String)
 
-```ruby
-identifier = Sashite::Sin.parse("C")
-opposite = Sashite::Sin.parse("s")
-
-# Player identification
-identifier.first_player?                       # => true
-identifier.second_player?                      # => false
-opposite.first_player?                         # => false
-opposite.second_player?                        # => true
-
-# Family and side comparison
-chess1 = Sashite::Sin.parse("C")
-chess2 = Sashite::Sin.parse("c")
-shogi = Sashite::Sin.parse("S")
-
-chess1.same_family?(chess2)               # => true (both Chess family)
-chess1.same_side?(shogi)                  # => true (both first player)
-chess1.same_family?(shogi)                # => false (different families)
-```
-
-### Identifier Collections
+Convert an `Identifier` back to a SIN string.
 
 ```ruby
-# Working with multiple identifiers
-identifiers = %w[C c S s M m].map { |sin| Sashite::Sin.parse(sin) }
-
-# Filter by player
-first_player_identifiers = identifiers.select(&:first_player?)
-first_player_identifiers.map(&:to_s) # => ["C", "S", "M"]
+# From Identifier object
+sin = Sashite::Sin::Identifier.new(:C, :first)
+sin.to_s  # => "C"
 
-# Group by family
-by_family = identifiers.group_by(&:family)
-by_family[:C].size # => 2 (both C and c)
-
-# Find specific families
-chess_identifiers = identifiers.select { |i| i.family == :C }
-chess_identifiers.map(&:to_s) # => ["C", "c"]
+sin = Sashite::Sin::Identifier.new(:C, :second)
+sin.to_s  # => "c"
 ```
 
-## Format Specification
+### Validation
 
-### Structure
-```
-<style-letter>
-```
-
-### Grammar (BNF)
-```bnf
-<sin> ::= <uppercase-letter> | <lowercase-letter>
-
-<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
-<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
-```
-
-### Regular Expression
 ```ruby
-/\A[A-Za-z]\z/
+# 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
 ```
 
-### Style Attribute Mapping
-
-SIN encodes style attributes using the following correspondence:
-
-| Style Attribute | SIN Encoding | Examples |
-|-----------------|--------------|----------|
-| **Family** | Style family symbol | `:C`, `:S`, `:X` |
-| **Side** | Player assignment | `:first`, `:second` |
-| **Letter** | Combined representation | `"C"`, `"c"`, `"S"`, `"s"` |
-
-#### Dual-Purpose Encoding
-
-The **Letter** combines two distinct semantic components:
-- **Style Family**: The underlying family symbol (:A-:Z), representing the game tradition or rule system
-- **Player Assignment**: The side (:first or :second), encoded as case in the letter representation
-
-**Examples**:
-- Family `:C` + Side `:first` → Letter `"C"` (Chess, First player)
-- Family `:C` + Side `:second` → Letter `"c"` (Chess, Second player)
-- Family `:S` + Side `:first` → Letter `"S"` (Shōgi, First player)
-- Family `:S` + Side `:second` → Letter `"s"` (Shōgi, Second player)
-
-## Traditional Game Style Examples
-
-The SIN specification is rule-agnostic and does not define specific letter assignments. However, here are common usage patterns following [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/):
+### Queries
 
 ```ruby
-# Chess (8×8 board)
-chess_white = Sashite::Sin.parse("C")    # First player (White pieces)
-chess_black = Sashite::Sin.parse("c")    # Second player (Black pieces)
+sin = Sashite::Sin.parse("C")
 
-# Shōgi (9×9 board)
-shogi_sente = Sashite::Sin.parse("S")    # First player (Sente 先手)
-shogi_gote = Sashite::Sin.parse("s")     # Second player (Gote 後手)
+# Side queries
+sin.first_player?   # => true
+sin.second_player?  # => false
 
-# Xiangqi (9×10 board)
-xiangqi_red = Sashite::Sin.parse("X")    # First player (Red pieces)
-xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)
-
-# Makruk (8×8 board)
-makruk_white = Sashite::Sin.parse("M")   # First player (White pieces)
-makruk_black = Sashite::Sin.parse("m")   # Second player (Black pieces)
-
-# Janggi (9×10 board)
-janggi_cho = Sashite::Sin.parse("J")     # First player (Cho 초)
-janggi_han = Sashite::Sin.parse("j")     # Second player (Han 한)
+# Comparison queries
+other = Sashite::Sin.parse("c")
+sin.same_abbr?(other)  # => true
+sin.same_side?(other)  # => false
 ```
 
-## Cross-Style Scenarios
+## API Reference
+
+### Types
 
 ```ruby
-# Chess vs. Ōgi Match (both 8×8 compatible)
-chess_white = Sashite::Sin.parse("C")    # Chess style, first player
-ogi_black = Sashite::Sin.parse("o")      # Ōgi style, second player
-
-# Cross-Style Match Setup
-def create_hybrid_match
-  [
-    Sashite::Sin.parse("C"),             # First player uses Chess family
-    Sashite::Sin.parse("s")              # Second player uses Shōgi family
-  ]
+# Identifier represents a parsed SIN identifier with abbreviation and side.
+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]
+  def abbr
+
+  # Returns the player side.
+  #
+  # @return [Symbol] :first or :second
+  def side
+
+  # Returns the SIN string representation.
+  #
+  # @return [String]
+  def to_s
 end
-
-identifiers = create_hybrid_match
-identifiers[0].same_side?(identifiers[1])    # => false (different players)
-identifiers[0].same_family?(identifiers[1])  # => false (different families)
 ```
 
-## System Constraints
-
-### Character Limitation
-SIN provides **26 possible identifiers** per player using ASCII letters (A-Z, a-z).
-
-### Player Limitation
-SIN supports exactly **two players** through case distinction:
-- **First player**: Uppercase letters (A-Z) → `:first`
-- **Second player**: Lowercase letters (a-z) → `:second`
-
-### Context Dependency
-The specific SIN assignment for a style may vary between different game contexts based on collision avoidance, historical precedence, and community conventions.
-
-## API Reference
-
-### Main Module Methods
-
-- `Sashite::Sin.valid?(sin_string)` - Check if string is valid SIN notation
-- `Sashite::Sin.parse(sin_string)` - Parse SIN string into Identifier object
-- `Sashite::Sin.identifier(family, side)` - Create identifier instance directly
-
-### Identifier Class
-
-#### Creation and Parsing
-- `Sashite::Sin::Identifier.new(family, side)` - Create identifier instance
-- `Sashite::Sin::Identifier.parse(sin_string)` - Parse SIN string
-
-#### Attribute Access
-- `#family` - Get style family (symbol :A through :Z)
-- `#side` - Get player side (:first or :second)
-- `#letter` - Get combined letter representation (string)
-- `#to_s` - Convert to SIN string representation
-
-#### Player Queries
-- `#first_player?` - Check if first player identifier
-- `#second_player?` - Check if second player identifier
-
-#### Transformations (immutable - return new instances)
-- `#flip` - Switch player assignment
-- `#with_family(new_family)` - Create identifier with different family
-- `#with_side(new_side)` - Create identifier with different side
-
-#### Comparison Methods
-- `#same_family?(other)` - Check if same style family
-- `#same_side?(other)` - Check if same player side
-- `#==(other)` - Full equality comparison
-- `#same_letter?(other)` - Alias for `same_family?` (deprecated)
-
 ### Constants
 
-- `Sashite::Sin::Identifier::FIRST_PLAYER` - Symbol for first player (`:first`)
-- `Sashite::Sin::Identifier::SECOND_PLAYER` - Symbol for second player (`:second`)
-- `Sashite::Sin::Identifier::VALID_FAMILIES` - Array of valid families (`:A` to `:Z`)
-- `Sashite::Sin::Identifier::VALID_SIDES` - Array of valid sides
-- `Sashite::Sin::Identifier::SIN_PATTERN` - Regular expression for SIN validation
-
-## Advanced Usage
-
-### Family and Side Separation
-
 ```ruby
-# Clear separation of concerns
-identifier = Sashite::Sin.parse("C")
-identifier.family  # => :C (Style Family - invariant)
-identifier.side    # => :first (Player Assignment)
-identifier.letter  # => "C" (Combined representation)
-
-# Transformations are explicit
-chess_white = Sashite::Sin.identifier(:C, :first)
-shogi_white = chess_white.with_family(:S) # Change family, keep side
-chess_black = chess_white.with_side(:second) # Change side, keep family
+Sashite::Sin::Identifier::VALID_ABBRS  # => [:A, :B, ..., :Z]
+Sashite::Sin::Identifier::VALID_SIDES  # => [:first, :second]
 ```
 
-### Immutable Transformations
+### Parsing
 
 ```ruby
-# All transformations return new instances
-original = Sashite::Sin.identifier(:C, :first)
-flipped = original.flip
-changed_family = original.with_family(:S)
-
-# Original identifier is never modified
-original.to_s         # => "C" (unchanged)
-flipped.to_s          # => "c"
-changed_family.to_s   # => "S"
-
-# Transformations can be chained
-result = original.flip.with_family(:M).flip
-result.to_s # => "M"
+# 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)
 ```
 
-## Design Properties
+### Validation
 
-Following the SIN v1.0.0 specification, this implementation provides:
+```ruby
+# Reports whether string is a valid SIN identifier.
+#
+# @param string [String] SIN string
+# @return [Boolean]
+def Sashite::Sin.valid?(string)
+```
 
-- **ASCII compatibility**: Maximum portability across systems
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Minimal overhead**: Single character per style-player combination
-- **Flexible collision resolution**: Systematic approaches for identifier conflicts
-- **Semantic clarity**: Distinct concepts for Family, Side, and Letter
-- **SNN coordination**: Works harmoniously with formal style naming
-- **Context-aware**: Adapts to avoid conflicts within specific game scenarios
-- **Canonical representation**: Each style-player combination has exactly one SIN identifier
-- **Immutable**: All identifier instances are frozen and transformations return new objects
-- **Functional**: Pure functions with no side effects
+### Queries
 
-## Related Specifications
+```ruby
+# Side queries
+def first_player?   # => Boolean
+def second_player?  # => Boolean
 
-- [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Complete technical specification
-- [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/) - Practical implementation examples
-- [Style Name Notation (SNN)](https://sashite.dev/specs/snn/) - Formal naming for game styles
-- [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation for abstract strategy board games
+# Comparison queries
+def same_abbr?(other)  # => Boolean
+def same_side?(other)  # => Boolean
+```
 
-## Documentation
+### Errors
 
-- [Official SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/)
-- [SIN Examples Documentation](https://sashite.dev/specs/sin/1.0.0/examples/)
-- [API Documentation](https://rubydoc.info/github/sashite/sin.rb/main)
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-## Development
+| Message | Cause |
+|---------|-------|
+| `"empty input"` | String length is 0 |
+| `"input exceeds 1 character"` | String too long |
+| `"must be a letter"` | Character is not A-Z or a-z |
 
-```sh
-# Clone the repository
-git clone https://github.com/sashite/sin.rb.git
-cd sin.rb
+## Design Principles
 
-# Install dependencies
-bundle install
+- **Bounded values**: Explicit validation of abbreviations and sides
+- **Object-oriented**: `Identifier` class enables methods and encapsulation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Immutable identifiers**: Instances are frozen after creation
+- **No dependencies**: Pure Ruby standard library only
 
-# Run tests
-ruby test.rb
+## Related Specifications
 
-# Generate documentation
-yard doc
-```
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [SIN Specification](https://sashite.dev/specs/sin/1.0.0/) — Official specification
+- [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/) — Usage examples
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
-
-## About
-
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).