sashite-stn 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b48125db1fd57d6ba5948b52e8fe536052723109acdfecac3c4320f46639666e
+  data.tar.gz: b788b0474fb0508a062d219158453f02cd4ef87940d7e7f75e3d8e55f127373d
+SHA512:
+  metadata.gz: 5b231420023e33171adabf4c879bbe5c17fd75848e7d85d79aca0d15cad0e379bef80ed2ceab44dbbb5bd1edfeccf08c293896a45f79b5d7d5e3f1a3a162f80c
+  data.tar.gz: 9ee42fbd65679988afb845b970f1d1e836562b6a72f06e1c8320c04653c8b51e72774eda5cb8072127a95eaf22ace3c14e42d0c95b75d9075052c331c1099fd2

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Sashite
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# Stn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/stn.rb?label=Version&logo=github)](https://github.com/sashite/stn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/stn.rb/main)
+![Ruby](https://github.com/sashite/stn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/stn.rb?label=License&logo=github)](https://github.com/sashite/stn.rb/raw/main/LICENSE.md)
+
+> **STN** (State Transition Notation) for Ruby — a small, pure, functional core to describe **position deltas** (board, hands/reserve, and active player toggle) in a **rule-agnostic** way.
+
+- **Functional & Immutable**: no side effects, no in-place mutation.
+- **Object-oriented surface**: simple module + value object (`Transition`).
+- **Spec-accurate**: strictly follows the STN specification.
+- **Minimalist**: no JSON (de)serialization inside the gem.
+
+---
+
+## What is STN?
+
+**STN** encodes the **net difference** between two positions in abstract strategy games:
+
+- `board`: map of **CELL** → `QPI or nil` (final state per cell)
+- `hands`: map of **QPI** → `Integer delta` (non-zero)
+- `toggle`: `true` when the active player switches, else `false`
+
+STN is **rule-agnostic**: it does not prescribe legal moves or game rules; it only describes what changes.
+
+This gem builds upon:
+
+- [CELL] — *Coordinate Encoding for Layered Locations*
+- [QPI]  — *Qualified Piece Identifier*
+
+> JSON (de)serialization is intentionally **out of scope**: keep it at your app boundary.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "sashite-stn"
+````
+
+Then:
+
+```sh
+bundle install
+```
+
+This gem depends on:
+
+```ruby
+gem "sashite-cell"
+gem "sashite-qpi"
+```
+
+Bundler will install them automatically when you use `sashite-stn`.
+
+---
+
+## STN format at a glance
+
+```ruby
+{
+  "board"  => { "e2" => nil, "e4" => "C:P" }, # e2 empties, e4 now has white pawn
+  "hands"  => { "c:p" => 1 },                  # add one black pawn to reserve
+  "toggle" => true                             # switch active player
+}
+```
+
+* All top-level keys are optional.
+* Empty object `{}` means “no changes”.
+
+---
+
+## Quick start
+
+```ruby
+require "sashite/stn"
+
+# Validate a payload (Hash) or an instance (Transition)
+Sashite::Stn.valid?({ "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true })
+# => true
+
+# Parse into an immutable Transition (raises on invalid)
+tr = Sashite::Stn.parse({ "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true })
+tr.toggle?        # => true
+tr.board_changes  # => { "e2" => nil, "e4" => "C:P" }
+
+# Construct directly (keywords)
+castle = Sashite::Stn.transition(
+  board:  { "e1" => nil, "g1" => "C:K", "h1" => nil, "f1" => "C:R" },
+  toggle: true
+)
+
+# Compose transitions (left → right)
+op_reply = Sashite::Stn.transition(board: { "e7" => nil, "e5" => "c:p" }, toggle: true)
+combined = Sashite::Stn.combine(castle, op_reply)
+combined.toggle? # => false  (true XOR true)
+
+# Canonical helpers
+Sashite::Stn.empty.to_h # => {}
+Sashite::Stn.pass.to_h  # => { :toggle=>true }
+```
+
+---
+
+## API
+
+### Module: `Sashite::Stn`
+
+* `Sashite::Stn.valid?(data) → Boolean`
+  Validate a payload (`Hash`) or a `Transition`.
+
+* `Sashite::Stn.parse(data) → Transition`
+  Parse a payload (`Hash`) or return the same `Transition`.
+  Raises `Sashite::Stn::Error::Validation` on invalid input.
+
+* `Sashite::Stn.transition(board: {}, hands: {}, toggle: false) → Transition`
+  Build a transition from keyword args. Keys are normalized to strings.
+
+* `Sashite::Stn.empty → Transition`
+  Canonical empty transition (no board/hands changes, no toggle).
+
+* `Sashite::Stn.pass → Transition`
+  Canonical pass transition (toggle only).
+
+* `Sashite::Stn.combine(*transitions) → Transition` (alias: `compose`)
+  Compose left-to-right using STN semantics:
+
+  * **board**: *last write wins* per cell
+  * **hands**: sum deltas; drop zero results
+  * **toggle**: XOR across the sequence
+
+### Class: `Sashite::Stn::Transition`
+
+**Construction & parsing**
+
+* `Transition.new(board: {}, hands: {}, toggle: false)`
+  Validates and freezes the instance.
+* `Transition.parse(hash) → Transition`
+  Parses a top-level Hash with `"board"`, `"hands"`, `"toggle"`.
+* `Transition.valid?(hash) → Boolean`
+  True/false wrapper over `parse`.
+
+**Accessors & queries**
+
+* `#board_changes → Hash{String=>String|nil}`
+* `#hand_changes  → Hash{String=>Integer}`
+* `#toggle?       → Boolean`
+* `#empty?        → Boolean`
+* `#pass_move?    → Boolean`
+* `#board_change(cell) → String|nil`
+* `#hand_change(qpi)   → Integer|nil`
+* `#has_board_change?(cell) → Boolean`
+* `#has_hand_change?(qpi)   → Boolean`
+
+**Transformations (return new instances)**
+
+* `#with_board_change(cell, value) → Transition`
+* `#with_hand_change(qpi, delta)   → Transition`
+* `#with_toggle(bool)              → Transition`
+* `#without_board_change(cell)     → Transition`
+* `#without_hand_change(qpi)       → Transition`
+
+**Composition & inversion**
+
+* `#combine(other) → Transition`
+  STN composition semantics (board last-write, summed hands, XOR toggle).
+* `#invert → Transition`
+  Invert **hands** and keep **toggle** as is (board left untouched).
+* `#invert_board_against(previous_board:) → Transition`
+  Build a board inverse using the provided *previous* snapshot.
+  Also inverts **hands** and keeps **toggle**.
+
+**Conversion & equality**
+
+* `#to_h → Hash` — omits empty fields; top-level keys are symbols
+* `#==`, `#eql?`, `#hash` — structural equality
+
+---
+
+## Error handling
+
+All exceptions are scoped under `Sashite::Stn::Error`:
+
+* `Sashite::Stn::Error` *(base class)*
+
+  * `Sashite::Stn::Error::Validation` — structural/semantic validation failures
+  * `Sashite::Stn::Error::Coordinate` — invalid **CELL** keys in `board`
+  * `Sashite::Stn::Error::Piece` — invalid **QPI** values/keys in `board`/`hands`
+  * `Sashite::Stn::Error::Delta` — invalid **hands** deltas (must be non-zero integers)
+
+```ruby
+begin
+  tr = Sashite::Stn.parse({ "board" => { "a0" => "C:P" } })
+rescue Sashite::Stn::Error::Coordinate => e
+  warn "Invalid CELL: #{e.message}"
+rescue Sashite::Stn::Error::Piece => e
+  warn "Invalid QPI: #{e.message}"
+rescue Sashite::Stn::Error::Delta => e
+  warn "Invalid delta: #{e.message}"
+rescue Sashite::Stn::Error::Validation => e
+  warn "STN validation failed: #{e.message}"
+end
+```
+
+---
+
+## Design properties
+
+* **Rule-agnostic**: independent from game rules and engines
+* **Pure & Immutable**: no mutation of inputs; instances are frozen
+* **Composable**: transitions merge cleanly and predictably
+* **Minimal surface**: no JSON (de)serialization built-in
+* **CELL/QPI-strict**: delegates coordinate/piece validation to their specs
+
+---
+
+## Development
+
+```sh
+# Clone
+git clone https://github.com/sashite/stn.rb.git
+cd stn.rb
+
+# Install
+bundle install
+
+# Run smoke tests (if you keep a simple test.rb)
+ruby test.rb
+
+# Generate YARD docs
+yard doc
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-change`
+3. Add tests covering your changes
+4. Ensure everything is green (lint, tests, docs)
+5. Commit with a conventional message
+6. Push and open a Pull Request
+
+---
+
+## License
+
+Open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## About
+
+Maintained by **Sashité** — promoting chess variants and sharing the beauty of board-game cultures.
+
+---
+
+[CELL]: https://sashite.dev/specs/cell/1.0.0/
+[QPI]: https://sashite.dev/specs/qpi/1.0.0/

data/lib/sashite/stn/error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Stn
+    # Base error namespace for STN.
+    #
+    # Usage patterns:
+    #   rescue Sashite::Stn::Error => e
+    #   rescue Sashite::Stn::Error::Validation
+    #   rescue Sashite::Stn::Error::Coordinate, Sashite::Stn::Error::Piece
+    class Error < StandardError
+      # Raised when an STN payload fails structural or semantic validation.
+      #
+      # @example
+      #   begin
+      #     Sashite::Stn.parse("not a hash")
+      #   rescue Sashite::Stn::Error::Validation => e
+      #     warn "Validation failed: #{e.message}"
+      #   end
+      class Validation < Error; end
+
+      # Raised when a CELL coordinate used as a board key is invalid.
+      #
+      # @example
+      #   begin
+      #     Sashite::Stn.parse({ "board" => { "a0" => "C:P" } })
+      #   rescue Sashite::Stn::Error::Coordinate => e
+      #     warn "Bad CELL: #{e.message}"
+      #   end
+      class Coordinate < Validation; end
+
+      # Raised when a QPI identifier (in board values or hand keys) is invalid.
+      #
+      # @example
+      #   begin
+      #     Sashite::Stn.parse({ "board" => { "e4" => "C:k" } }) # semantic mismatch
+      #   rescue Sashite::Stn::Error::Piece => e
+      #     warn "Bad QPI: #{e.message}"
+      #   end
+      class Piece < Validation; end
+
+      # Raised when a hand delta is not a non-zero Integer.
+      #
+      # @example
+      #   begin
+      #     Sashite::Stn.parse({ "hands" => { "c:p" => 0 } })
+      #   rescue Sashite::Stn::Error::Delta => e
+      #     warn "Bad delta: #{e.message}"
+      #   end
+      class Delta < Validation; end
+    end
+  end
+end

data/lib/sashite/stn/transition.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require "sashite/cell"
+require "sashite/qpi"
+
+module Sashite
+  module Stn
+    # Immutable representation of an STN delta.
+    #
+    # A Transition encodes the *net* differences between two positions:
+    # - board changes (CELL => QPI or nil)
+    # - hand/reserve deltas (QPI => non-zero Integer)
+    # - active player toggle (Boolean)
+    #
+    # All instances are frozen; any "mutation" returns a new Transition.
+    #
+    # @example Board-only change with toggle
+    #   t = Sashite::Stn::Transition.new(
+    #         board: { "e2" => nil, "e4" => "C:P" },
+    #         toggle: true
+    #       )
+    #   t.toggle?        # => true
+    #   t.board_changes  # => { "e2" => nil, "e4" => "C:P" }
+    #
+    # @example Hand-only delta (add one black pawn to reserve)
+    #   t = Sashite::Stn::Transition.new(hands: { "c:p" => 1 })
+    #   t.hand_changes   # => { "c:p" => 1 }
+    #
+    # @example Empty transition
+    #   Sashite::Stn::Transition.new.empty? # => true
+    class Transition
+      # @return [Hash{String=>String,nil}] board final states by CELL
+      attr_reader :board_changes
+      # @return [Hash{String=>Integer}] hand deltas by QPI (non-zero)
+      attr_reader :hand_changes
+      # @return [Boolean] true if active player should switch
+      attr_reader :toggle
+
+      # Build an immutable transition.
+      #
+      # Keys for +board+ and +hands+ are *stringified* and values are validated.
+      # Inputs are never mutated.
+      #
+      # @param board [Hash{String,Symbol=>String,nil}]
+      # @param hands [Hash{String,Symbol=>Integer}]
+      # @param toggle [Boolean]
+      #
+      # @raise [Sashite::Stn::Error::Coordinate] if a CELL key is invalid
+      # @raise [Sashite::Stn::Error::Piece]      if a QPI value/key is invalid
+      # @raise [Sashite::Stn::Error::Delta]      if a hand delta is not a non-zero Integer
+      #
+      # @example
+      #   Sashite::Stn::Transition.new(board: { "e1" => nil, "g1" => "C:K" }, toggle: true)
+      def initialize(board: {}, hands: {}, toggle: false)
+        @board_changes = _stringify_map(board).freeze
+        @hand_changes  = _stringify_map(hands).freeze
+        @toggle        = toggle
+
+        _validate!
+        freeze
+      end
+
+      # Parse a Ruby Hash (with "board", "hands", "toggle") into a Transition.
+      # Keys inside "board"/"hands" may be symbols or strings.
+      #
+      # @param data [Hash]
+      # @return [Transition]
+      #
+      # @example
+      #   Sashite::Stn::Transition.parse(
+      #     "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true
+      #   )
+      def self.parse(data)
+        raise Error::Validation, "STN must be a Hash" unless data.is_a?(::Hash)
+
+        board  = data.key?("board")  ? data["board"]  : (data[:board]  if data.key?(:board))
+        hands  = data.key?("hands")  ? data["hands"]  : (data[:hands]  if data.key?(:hands))
+        toggle = data.key?("toggle") ? data["toggle"] : (data[:toggle] if data.key?(:toggle))
+
+        new(board: board || {}, hands: hands || {}, toggle: !!toggle)
+      end
+
+      # Predicate wrapper for +parse+ that traps validation errors.
+      #
+      # @param data [Hash]
+      # @return [Boolean]
+      #
+      # @example
+      #   Sashite::Stn::Transition.valid?({ "board" => { "a0" => "C:P" } }) # => false
+      def self.valid?(data)
+        !!parse(data)
+      rescue ::Sashite::Stn::Error
+        false
+      end
+
+      # @return [Boolean] true if +toggle+ is set.
+      def toggle?
+        @toggle
+      end
+
+      # @return [Boolean] true when no changes at all and no toggle.
+      def empty?
+        @board_changes.empty? && @hand_changes.empty? && !@toggle
+      end
+
+      # @return [Boolean] true when there is a toggle only (no board/hands).
+      def pass_move?
+        @board_changes.empty? && @hand_changes.empty? && @toggle
+      end
+
+      # Read a single board change for a given CELL.
+      #
+      # @param cell [String]
+      # @return [String,nil] QPI or nil for empty; nil if the cell is not changed by this transition
+      def board_change(cell)
+        @board_changes[cell]
+      end
+
+      # Read a single hand delta for a given QPI key.
+      #
+      # @param qpi [String]
+      # @return [Integer,nil]
+      def hand_change(qpi)
+        @hand_changes[qpi]
+      end
+
+      # Whether a CELL is present in the board delta.
+      #
+      # @param cell [String]
+      # @return [Boolean]
+      def has_board_change?(cell)
+        @board_changes.key?(cell)
+      end
+
+      # Whether a QPI key is present in the hand delta.
+      #
+      # @param qpi [String]
+      # @return [Boolean]
+      def has_hand_change?(qpi)
+        @hand_changes.key?(qpi)
+      end
+
+      # Replace or add a board entry (CELL => value) and return a new Transition.
+      #
+      # @param cell [String,Symbol]
+      # @param value [String,nil] QPI or nil
+      # @return [Transition]
+      #
+      # @example
+      #   t2 = t1.with_board_change("f3", "S:+N")
+      def with_board_change(cell, value)
+        self.class.new(
+          board:  @board_changes.merge(cell.to_s => value),
+          hands:  @hand_changes,
+          toggle: @toggle
+        )
+      end
+
+      # Replace or add a single hand delta and return a new Transition.
+      #
+      # @param qpi [String,Symbol]
+      # @param delta [Integer] non-zero
+      # @return [Transition]
+      #
+      # @example
+      #   t2 = t1.with_hand_change("c:b", 1)
+      def with_hand_change(qpi, delta)
+        self.class.new(
+          board:  @board_changes,
+          hands:  @hand_changes.merge(qpi.to_s => delta),
+          toggle: @toggle
+        )
+      end
+
+      # Return a new Transition with the given toggle flag.
+      #
+      # @param value [Boolean]
+      # @return [Transition]
+      #
+      # @example
+      #   t2 = t1.with_toggle(false)
+      def with_toggle(value)
+        self.class.new(
+          board:  @board_changes,
+          hands:  @hand_changes,
+          toggle: value
+        )
+      end
+
+      # Remove a board entry (if present) and return a new Transition.
+      #
+      # @param cell [String,Symbol]
+      # @return [Transition]
+      def without_board_change(cell)
+        key = cell.to_s
+        return self unless @board_changes.key?(key)
+
+        self.class.new(
+          board:  @board_changes.reject { |k, _| k == key },
+          hands:  @hand_changes,
+          toggle: @toggle
+        )
+      end
+
+      # Remove a hand entry (if present) and return a new Transition.
+      #
+      # @param qpi [String,Symbol]
+      # @return [Transition]
+      def without_hand_change(qpi)
+        key = qpi.to_s
+        return self unless @hand_changes.key?(key)
+
+        self.class.new(
+          board:  @board_changes,
+          hands:  @hand_changes.reject { |k, _| k == key },
+          toggle: @toggle
+        )
+      end
+
+      # Combine this transition with another one, left-to-right.
+      # STN composition semantics:
+      # - board: last write wins per CELL
+      # - hands: deltas are summed; entries summing to zero are removed
+      # - toggle: XOR
+      #
+      # @param other [Transition]
+      # @return [Transition]
+      #
+      # @example
+      #   t = t1.combine(t2)
+      def combine(other)
+        raise Error::Validation, "Expected Transition, got: #{other.class}" unless other.is_a?(Transition)
+
+        combined_board = @board_changes.merge(other.board_changes)
+
+        combined_hands = ::Hash.new(0)
+        (@hand_changes.keys | other.hand_changes.keys).each do |k|
+          sum = (@hand_changes[k] || 0) + (other.hand_changes[k] || 0)
+          combined_hands[k] = sum unless sum.zero?
+        end
+
+        self.class.new(
+          board:  combined_board,
+          hands:  combined_hands,
+          toggle: (@toggle ^ other.toggle?)
+        )
+      end
+
+      # Produce a Ruby Hash representation suitable for serialization.
+      # Keys at the top level use Ruby symbols (:board, :hands, :toggle).
+      # Omitted fields are not present in the result.
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   Sashite::Stn::Transition.new(toggle: true).to_h # => { :toggle=>true }
+      def to_h
+        h = {}
+        h[:board]  = @board_changes unless @board_changes.empty?
+        h[:hands]  = @hand_changes  unless @hand_changes.empty?
+        h[:toggle] = true if @toggle
+        h
+      end
+
+      # Structural equality.
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Transition) &&
+          board_changes == other.board_changes &&
+          hand_changes == other.hand_changes &&
+          toggle? == other.toggle?
+      end
+      alias eql? ==
+
+      # Hash code consistent with #==.
+      #
+      # @return [Integer]
+      def hash
+        [@board_changes, @hand_changes, @toggle].hash
+      end
+
+      # --------- Advanced helpers (optional) ---------
+
+      # Compute an inverse transition for *hands* and *toggle* only.
+      # Board inversion requires knowledge of the surrounding positions and
+      # therefore is not attempted here (board delta left untouched).
+      #
+      # If you need a full board inverse, use {#invert_board_against}.
+      #
+      # @return [Transition]
+      #
+      # @example
+      #   t  = Sashite::Stn::Transition.new(hands: { "c:p" => 2 }, toggle: true)
+      #   ti = t.invert
+      #   ti.hand_changes # => { "c:p" => -2 }
+      #   ti.toggle?      # => true
+      def invert
+        inv_hands = @hand_changes.transform_values(&:-@)
+        self.class.new(board: @board_changes, hands: inv_hands, toggle: @toggle)
+      end
+
+      # Build a board inverse against a known *before* position snapshot.
+      # Given a map of *previous* CELL states (QPI or nil), construct a transition
+      # that would restore those cells. Hands and toggle are inverted like {#invert}.
+      #
+      # @param previous_board [Hash{String=>String,nil}] canonical "before" snapshot
+      # @return [Transition]
+      #
+      # @example
+      #   # Suppose before: e2 => "C:P", e4 => nil   and t sets e2=>nil, e4=>"C:P"
+      #   before = { "e2" => "C:P", "e4" => nil }
+      #   t  = Sashite::Stn::Transition.new(board: { "e2" => nil, "e4" => "C:P" }, toggle: true)
+      #   ti = t.invert_board_against(previous_board: before)
+      #   ti.board_changes # => { "e2" => "C:P", "e4" => nil }
+      def invert_board_against(previous_board:)
+        raise Error::Validation, "previous_board must be a Hash of CELL=>QPI/nil" unless previous_board.is_a?(::Hash)
+
+        inv_board = {}
+        @board_changes.each_key do |cell|
+          inv_board[cell] = previous_board[cell]
+        end
+
+        self.class.new(
+          board:  inv_board,
+          hands:  @hand_changes.transform_values(&:-@),
+          toggle: @toggle
+        )
+      end
+
+      private
+
+      # -- Validation ---------------------------------------------------------
+
+      def _validate!
+        _validate_board!
+        _validate_hands!
+        _validate_toggle!
+      end
+
+      def _validate_board!
+        raise Error::Validation, "board must be a Hash" unless @board_changes.is_a?(::Hash)
+
+        @board_changes.each do |cell, qpi|
+          raise Error::Coordinate, "Invalid CELL coordinate: #{cell.inspect}" unless ::Sashite::Cell.valid?(cell)
+          unless qpi.nil? || ::Sashite::Qpi.valid?(qpi)
+            raise Error::Piece, "Invalid QPI for board cell #{cell}: #{qpi.inspect}"
+          end
+        end
+      end
+
+      def _validate_hands!
+        raise Error::Validation, "hands must be a Hash" unless @hand_changes.is_a?(::Hash)
+
+        @hand_changes.each do |qpi, delta|
+          raise Error::Piece, "Invalid QPI in hands: #{qpi.inspect}" unless ::Sashite::Qpi.valid?(qpi)
+          unless delta.is_a?(Integer) && !delta.zero?
+            raise Error::Delta, "Hand delta must be a non-zero Integer for #{qpi.inspect}, got: #{delta.inspect}"
+          end
+        end
+      end
+
+      def _validate_toggle!
+        return if [true, false].include?(@toggle)
+
+        raise Error::Validation, "toggle must be a Boolean, got: #{@toggle.inspect}"
+      end
+
+      # -- Utilities ----------------------------------------------------------
+
+      def _stringify_map(h)
+        return {} if h.nil? || h == {}
+
+        raise Error::Validation, "Expected a Hash, got: #{h.class}" unless h.is_a?(::Hash)
+
+        h.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/sashite/stn.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "stn/error"
+require_relative "stn/transition"
+
+module Sashite
+  module Stn
+    # Canonical, immutable transitions reused across calls.
+    EMPTY_TRANSITION = Transition.new.freeze
+    PASS_TRANSITION  = Transition.new(toggle: true).freeze
+
+    class << self
+      # Validate an STN payload (Hash) or a Transition instance.
+      #
+      # The validation is strict and delegated to {Transition.parse}.
+      # It accepts top-level keys as strings ("board", "hands", "toggle")
+      # or symbols (:board, :hands, :toggle). Nested keys are normalized to strings.
+      #
+      # @param data [Hash, Transition]
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example Hash – board-only change with turn toggle
+      #   Sashite::Stn.valid?({ "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true })
+      #   # => true
+      #
+      # @example Hash – invalid CELL coordinate
+      #   Sashite::Stn.valid?({ "board" => { "a0" => "C:P" } })
+      #   # => false
+      #
+      # @example Transition – already parsed
+      #   tr = Sashite::Stn.transition(board: { "e2" => nil, "e4" => "C:P" }, toggle: true)
+      #   Sashite::Stn.valid?(tr)  # => true
+      def valid?(data)
+        case data
+        when Transition
+          true
+        when ::Hash
+          begin
+            Transition.parse(_normalize_root(data))
+            true
+          rescue Error
+            false
+          end
+        else
+          false
+        end
+      end
+
+      # Parse an STN payload (Hash) into a {Transition}, or return the
+      # same {Transition} if one is passed. Raises on invalid input.
+      #
+      # Top-level keys may be symbols or strings and are normalized.
+      #
+      # @param data [Hash, Transition]
+      # @return [Transition]
+      # @raise [Sashite::Stn::Error::Validation]
+      #
+      # @example Parse from Hash
+      #   tr = Sashite::Stn.parse({ "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true })
+      #   tr.toggle?        # => true
+      #   tr.board_changes  # => { "e2" => nil, "e4" => "C:P" }
+      #
+      # @example Passing a Transition returns it unchanged
+      #   tr = Sashite::Stn.transition(toggle: true)
+      #   Sashite::Stn.parse(tr).equal?(tr)  # => true
+      def parse(data)
+        case data
+        when Transition
+          data
+        when ::Hash
+          Transition.parse(_normalize_root(data))
+        else
+          raise Error::Validation,
+                "STN must be provided as a Hash or a Transition, got: #{data.class}"
+        end
+      end
+
+      # Construct a {Transition} directly from keyword arguments.
+      # Inputs are not mutated; keys are normalized to strings.
+      #
+      # @param board [Hash{String,Symbol=>String,nil}] CELL -> (QPI or nil)
+      # @param hands [Hash{String,Symbol=>Integer}]    QPI  -> delta (non-zero)
+      # @param toggle [Boolean] switch active player if true
+      # @return [Transition]
+      #
+      # @example Build a standard move (e2->e4) with toggle
+      #   tr = Sashite::Stn.transition(board: { "e2" => nil, "e4" => "C:P" }, toggle: true)
+      #   tr.to_h
+      #   # => { :board=>{"e2"=>nil,"e4"=>"C:P"}, :toggle=>true }
+      #
+      # @example Drop from hand (hand-only + board change)
+      #   tr = Sashite::Stn.transition(
+      #          board: { "e5" => "S:P" },
+      #          hands: { "S:P" => -1 },
+      #          toggle: true
+      #        )
+      def transition(board: {}, hands: {}, toggle: false)
+        board_norm = _stringify_map(board)
+        hands_norm = _stringify_map(hands)
+        Transition.new(board: board_norm, hands: hands_norm, toggle: !!toggle)
+      end
+
+      # Return the canonical empty transition: no board changes, no hand changes,
+      # no toggle. This instance is immutable and safe to reuse.
+      #
+      # @return [Transition]
+      #
+      # @example
+      #   Sashite::Stn.empty.empty?   # => true
+      #   Sashite::Stn.empty.toggle?  # => false
+      def empty
+        EMPTY_TRANSITION
+      end
+
+      # Return the canonical pass transition: toggle only, no board/hands changes.
+      # This instance is immutable and safe to reuse.
+      #
+      # @return [Transition]
+      #
+      # @example
+      #   Sashite::Stn.pass.pass_move?  # => true
+      #   Sashite::Stn.pass.to_h        # => { :toggle=>true }
+      def pass
+        PASS_TRANSITION
+      end
+
+      # Combine (compose) several transitions or Hash payloads left-to-right.
+      # Composition semantics follow STN rules:
+      #  - board: last value wins per cell
+      #  - hands: deltas are summed; entries summing to zero are removed
+      #  - toggle: XOR across the sequence
+      #
+      # @param transitions [Array<Transition,Hash>]
+      # @return [Transition]
+      #
+      # @example Combine two moves into a cumulative delta
+      #   t1 = { "board" => { "e2" => nil, "e4" => "C:P" }, "toggle" => true }
+      #   t2 = { "board" => { "e7" => nil, "e5" => "c:p" }, "toggle" => true }
+      #   Sashite::Stn.combine(t1, t2).to_h
+      #   # => { :board=>{"e2"=>nil,"e4"=>"C:P","e7"=>nil,"e5"=>"c:p"} }
+      #
+      # @example Mixed inputs (Hash and Transition)
+      #   t1 = Sashite::Stn.transition(board: { "e1" => nil, "g1" => "C:K", "h1" => nil, "f1" => "C:R" }, toggle: true)
+      #   t2 = { "hands" => { "c:b" => 1 }, "toggle" => true }
+      #   combo = Sashite::Stn.combine(t1, t2)
+      #   combo.toggle? # => false (true XOR true)
+      def combine(*transitions)
+        parsed = transitions.flatten.compact.map { |t| parse(t) }
+        parsed.reduce(EMPTY_TRANSITION) { |acc, t| acc.combine(t) }
+      end
+
+      # Friendly alias for {combine}.
+      #
+      # @see #combine
+      def compose(*transitions)
+        combine(*transitions)
+      end
+    end
+
+    # ---------------------
+    # Private helpers
+    # ---------------------
+
+    # Normalize top-level keys to strings ("board", "hands", "toggle")
+    # and stringify nested keys of board/hands maps. Input is not mutated.
+    #
+    # @param data [Hash]
+    # @return [Hash]
+    # @raise [Sashite::Stn::Error::Validation]
+    def self._normalize_root(data)
+      raise Error::Validation, "STN must be a Hash" unless data.is_a?(::Hash)
+
+      board_key  = if data.key?("board")
+                     "board"
+                   else
+                     (data.key?(:board) ? :board : nil)
+                   end
+      hands_key  = if data.key?("hands")
+                     "hands"
+                   else
+                     (data.key?(:hands) ? :hands : nil)
+                   end
+      toggle_key = if data.key?("toggle")
+                     "toggle"
+                   else
+                     (data.key?(:toggle) ? :toggle : nil)
+                   end
+
+      normalized = {}
+      normalized["board"]  = _stringify_map(data[board_key]) if board_key
+      normalized["hands"]  = _stringify_map(data[hands_key]) if hands_key
+
+      if toggle_key
+        val = data[toggle_key]
+        raise Error::Validation, "toggle must be a boolean" unless [true, false].include?(val)
+
+        normalized["toggle"] = val
+      end
+
+      normalized
+    end
+    private_class_method :_normalize_root
+
+    # Stringify keys of a map (or return empty Hash for nil/{}).
+    # Raises if a non-Hash is provided.
+    #
+    # @param h [Hash,nil]
+    # @return [Hash]
+    # @raise [Sashite::Stn::Error::Validation]
+    def self._stringify_map(h)
+      return {} if h.nil? || h == {}
+
+      unless h.is_a?(::Hash)
+        raise Error::Validation,
+              "Expected a Hash for board/hands, got: #{h.class}"
+      end
+
+      h.transform_keys(&:to_s)
+    end
+    private_class_method :_stringify_map
+  end
+end

data/lib/sashite-stn.rb

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

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: sashite-stn
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sashite-cell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sashite-qpi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  STN (State Transition Notation) provides a rule-agnostic format for describing state transitions
+  in abstract strategy board games. This gem implements the STN Specification v1.0.0 with a modern
+  Ruby interface featuring immutable transition objects and functional programming principles. STN
+  captures net changes between game positions by recording modifications in piece locations, hand/reserve
+  contents, and active player status using standardized CELL coordinates and QPI piece identification.
+  Perfect for game engines, position diff tracking, undo/redo systems, and network synchronization
+  requiring efficient state delta representation across multiple game types and traditions.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-stn.rb
+- lib/sashite/stn.rb
+- lib/sashite/stn/error.rb
+- lib/sashite/stn/transition.rb
+homepage: https://github.com/sashite/stn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/stn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/stn.rb/main
+  homepage_uri: https://github.com/sashite/stn.rb
+  source_code_uri: https://github.com/sashite/stn.rb
+  specification_uri: https://sashite.dev/specs/stn/1.0.0/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: STN (State Transition Notation) implementation for Ruby with immutable transition
+  objects
+test_files: []