sashite-ggn 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e471fdf36ded96b18559ff0c7f6ba47b9210624d019452bc4037b93e484cf29c
-  data.tar.gz: cd99ab6b95f0bdc4377c87c67864c861288d0d7dec536450cf36698c6da5b3de
+  metadata.gz: e88e8f3d556981f4bc4484589aedb85101963ac262f5cc81a4c17337418b1994
+  data.tar.gz: 6aedb3c95ed76a094f80c22efaa94d5fd0a3291f25219796b96eb09abbbf02ef
 SHA512:
-  metadata.gz: ce76a683d986574ff72d6830805aa90f636e617349f04514feca2a500b2510d073f59f305a9c666100848a1b5e5806b9d59b97f5bb1aae870eff2fd982f4755e
-  data.tar.gz: 98cc6ac792be2873d3a73fb9154ec0493614f82bcb2d10087224246fbb1d8206b21335f0ab1d175509a815210a4ec22deb8e0103eb5c1c83ad1cfe6f6c65f2ea
+  metadata.gz: 12d4995c1bbc905190ebef8fd054ef615d9edfa1578bd629e375455cacf5794225c25ceb1cf9820d1d71e827caf5152e10583bae7ded85439639bb0d21eafe64
+  data.tar.gz: 63450b84e3b335bcf1236ab91da9203bfdf24db0ccd01cb8f2aef11cda5683aa8fdeb8a27e528d5277f3ac7d232bc529cc15bc9080000a35641ba348504529c9

data/README.md

@@ -5,31 +5,13 @@
 ![Ruby](https://github.com/sashite/ggn.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/ggn.rb?label=License&logo=github)](https://github.com/sashite/ggn.rb/raw/main/LICENSE.md)
 
-> **GGN** (General Gameplay Notation) implementation for Ruby — a pure, functional library for evaluating **movement possibilities** in abstract strategy board games.
-
----
+> **GGN** (General Gameplay Notation) implementation for Ruby — evaluates **movement possibilities** in abstract strategy board games.
 
 ## What is GGN?
 
-GGN (General Gameplay Notation) is a rule-agnostic format for describing **pseudo-legal moves** in abstract strategy board games. GGN serves as a **movement possibility oracle**: given a movement context (piece and source location) plus a destination location, it determines if the movement is feasible under specified pre-conditions.
-
-This gem implements the [GGN Specification v1.0.0](https://sashite.dev/specs/ggn/1.0.0/), providing complete movement possibility evaluation with environmental constraint checking.
-
-### Core Philosophy
-
-GGN answers the fundamental question:
-
-> **Can this piece, currently at this location, reach that location?**
-
-It encodes:
-- **Which piece** (via QPI format)
-- **From where** (source location using CELL or HAND)
-- **To where** (destination location using CELL or HAND)
-- **Which environmental pre-conditions** must hold (`must`)
-- **Which environmental pre-conditions** must not hold (`deny`)
-- **What changes occur** if executed (`diff` in STN format)
+GGN (General Gameplay Notation) is a rule-agnostic format for describing **pseudo-legal moves** in abstract strategy board games. GGN serves as a **movement possibility oracle**: given a piece at a source location and a desired destination, it determines if the movement is feasible based on environmental pre-conditions.
 
----
+This gem implements the [GGN Specification v1.0.0](https://sashite.dev/specs/ggn/1.0.0/).
 
 ## Installation
 
@@ -44,22 +26,6 @@ Or install manually:
 gem install sashite-ggn
 ```
 
----
-
-## Dependencies
-
-GGN builds upon foundational Sashité specifications:
-
-```ruby
-gem "sashite-cell"  # Coordinate Encoding for Layered Locations
-gem "sashite-hand"  # Hold And Notation Designator
-gem "sashite-lcn"   # Location Condition Notation
-gem "sashite-qpi"   # Qualified Piece Identifier
-gem "sashite-stn"   # State Transition Notation
-```
-
----
-
 ## Quick Start
 
 ```ruby
@@ -67,423 +33,322 @@ require "sashite/ggn"
 
 # Define GGN data structure
 ggn_data = {
-  "C:P" => {
-    "e2" => {
-      "e4" => [
+  "C:P" => {                              # Chess pawn
+    "e2" => {                             # From e2
+      "e4" => [                           # To e4
         {
-          "must" => { "e3" => "empty", "e4" => "empty" },
-          "deny" => {},
-          "diff" => {
-            "board" => { "e2" => nil, "e4" => "C:P" },
-            "toggle" => true
-          }
+          "must" => {                     # Required conditions
+            "e3" => "empty",
+            "e4" => "empty"
+          },
+          "deny" => {}                    # Forbidden conditions
         }
       ]
     }
   }
 }
 
-# Validate GGN structure
-Sashite::Ggn.valid?(ggn_data) # => true
-
 # Parse into ruleset
 ruleset = Sashite::Ggn.parse(ggn_data)
 
-# Query movement possibility through method chaining
-source = ruleset.select("C:P")
-destination = source.from("e2")
-engine = destination.to("e4")
-
-# Evaluate against position
+# Query movement through method chaining
 active_side = :first
-squares = {
-  "e2" => "C:P",
-  "e3" => nil,
-  "e4" => nil
-}
-
-transitions = engine.where(active_side, squares)
-transitions.any? # => true
-```
-
----
-
-## API Reference
-
-### Module Functions
-
-#### `Sashite::Ggn.parse(data) → Ruleset`
+squares = { "e2" => "C:P", "e3" => nil, "e4" => nil }
 
-Parses GGN data structure into an immutable Ruleset object.
+possibilities = ruleset
+  .select("C:P")        # Select piece type
+  .from("e2")           # From source location
+  .to("e4")             # To destination location
+  .where(active_side, squares)  # Evaluate conditions
 
-```ruby
-ruleset = Sashite::Ggn.parse(ggn_data)
+possibilities.any?      # => true (movement is possible)
 ```
 
-**Parameters:**
-- `data` (Hash): GGN data structure conforming to specification
-
-**Returns:** `Ruleset` — Immutable ruleset object
-
-**Raises:** `ArgumentError` — If data structure is invalid
-
----
+## Core Concepts
 
-#### `Sashite::Ggn.valid?(data) → Boolean`
+### Navigation Structure
 
-Validates GGN data structure against specification.
+GGN uses a hierarchical structure that naturally maps to method chaining:
 
-```ruby
-Sashite::Ggn.valid?(ggn_data) # => true
 ```
-
-**Parameters:**
-- `data` (Hash): Data structure to validate
-
-**Returns:** `Boolean` — True if valid, false otherwise
-
----
-
-### `Sashite::Ggn::Ruleset` Class
-
-Immutable container for GGN movement rules.
-
-#### `#select(piece) → Source`
-
-Selects movement rules for a specific piece type.
-
-```ruby
-source = ruleset.select("C:K")
+Piece → Source → Destination → Possibilities
 ```
 
-**Parameters:**
-- `piece` (String): QPI piece identifier
-
-**Returns:** `Source` — Source selector object
-
-**Raises:** `KeyError` — If piece not found in ruleset
-
----
-
-#### `#piece?(piece) → Boolean`
-
-Checks if ruleset contains movement rules for specified piece.
+Each level provides introspection methods to explore available options:
 
 ```ruby
-ruleset.piece?("C:K") # => true
-```
-
-**Parameters:**
-- `piece` (String): QPI piece identifier
-
-**Returns:** `Boolean`
+# Explore available pieces
+ruleset.pieces                    # => ["C:K", "C:Q", "C:P", ...]
 
----
+# Explore sources for a piece
+ruleset.select("C:P").sources     # => ["a2", "b2", "c2", ...]
 
-#### `#pieces → Array<String>`
+# Explore destinations from a source
+ruleset.select("C:P").from("e2").destinations  # => ["e3", "e4"]
 
-Returns all piece identifiers in ruleset.
-
-```ruby
-ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
+# Check existence at any level
+ruleset.piece?("C:K")                          # => true
+ruleset.select("C:K").source?("e1")             # => true
+ruleset.select("C:K").from("e1").destination?("e2")  # => true
 ```
 
-**Returns:** `Array<String>` — QPI piece identifiers
+### Condition Evaluation
 
----
-
-### `Sashite::Ggn::Ruleset::Source` Class
-
-Represents movement possibilities for a piece type.
-
-#### `#from(source) → Destination`
-
-Specifies the source location for the piece.
+The `where` method evaluates movement possibilities against the current board state:
 
 ```ruby
-destination = source.from("e1")
-```
-
-**Parameters:**
-- `source` (String): Source location (CELL coordinate or HAND "*")
-
-**Returns:** `Destination` — Destination selector object
+# Returns array of matching possibilities (may be empty)
+possibilities = engine.where(active_side, squares)
 
-**Raises:** `KeyError` — If source not found for this piece
+# Each possibility is a Hash containing the original GGN data
+# that satisfied the conditions
+possibility = possibilities.first
+# => { "must" => {...}, "deny" => {...} }
+```
 
----
+**Key points:**
+- `active_side` (Symbol): `:first` or `:second` - determines enemy evaluation
+- `squares` (Hash): Board state where keys are CELL coordinates, values are QPI identifiers or `nil`
+- Returns an array of possibilities that match the conditions
 
-#### `#sources → Array<String>`
+## API Reference
 
-Returns all valid source locations for this piece.
+### Module Methods
 
 ```ruby
-source.sources # => ["e1", "d1", "*"]
-```
-
-**Returns:** `Array<String>` — Source locations
-
----
+# Parse GGN data into a ruleset
+ruleset = Sashite::Ggn.parse(data)
 
-#### `#source?(location) → Boolean`
+# Validate GGN data structure
+Sashite::Ggn.valid?(data)  # => true/false
+```
 
-Checks if location is a valid source for this piece.
+### Ruleset Class
 
 ```ruby
-source.source?("e1") # => true
-```
+# Select piece movement rules
+source = ruleset.select("C:K")
 
-**Parameters:**
-- `location` (String): Source location
+# Check if piece exists
+ruleset.piece?("C:K")  # => true/false
 
-**Returns:** `Boolean`
+# List all pieces
+ruleset.pieces  # => ["C:K", "C:Q", ...]
+```
 
----
+### Source Class
 
-### `Sashite::Ggn::Ruleset::Source::Destination` Class
+```ruby
+# Select source location
+destination = source.from("e1")
 
-Represents movement possibilities from a specific source.
+# Check if source exists
+source.source?("e1")  # => true/false
 
-#### `#to(destination) → Engine`
+# List all sources
+source.sources  # => ["e1", "d1", ...]
+```
 
-Specifies the destination location.
+### Destination Class
 
 ```ruby
+# Select destination location
 engine = destination.to("e2")
-```
-
-**Parameters:**
-- `destination` (String): Destination location (CELL coordinate or HAND "*")
-
-**Returns:** `Engine` — Movement evaluation engine
-
-**Raises:** `KeyError` — If destination not found from this source
 
----
+# Check if destination exists
+destination.destination?("e2")  # => true/false
 
-#### `#destinations → Array<String>`
-
-Returns all valid destinations from this source.
-
-```ruby
-destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
+# List all destinations
+destination.destinations  # => ["d1", "d2", ...]
 ```
 
-**Returns:** `Array<String>` — Destination locations
-
----
-
-#### `#destination?(location) → Boolean`
-
-Checks if location is a valid destination from this source.
+### Engine Class
 
 ```ruby
-destination.destination?("e2") # => true
+# Evaluate movement possibilities
+possibilities = engine.where(active_side, squares)
+# Returns array of possibility hashes that match conditions
 ```
 
-**Parameters:**
-- `location` (String): Destination location
-
-**Returns:** `Boolean`
-
----
-
-### `Sashite::Ggn::Ruleset::Source::Destination::Engine` Class
-
-Evaluates movement possibility under given position conditions.
-
-#### `#where(active_side, squares) → Array<Transition>`
+## Examples
 
-Evaluates movement against position and returns valid transitions.
+### Chess Pawn Movement
 
 ```ruby
-active_side = :first
-squares = {
-  "e2" => "C:P",  # White pawn on e2
-  "e3" => nil,    # Empty square
-  "e4" => nil     # Empty square
+# Two-square advance from starting position
+ggn_data = {
+  "C:P" => {
+    "e2" => {
+      "e4" => [{
+        "must" => { "e3" => "empty", "e4" => "empty" },
+        "deny" => {}
+      }]
+    }
+  }
 }
 
-transitions = engine.where(active_side, squares)
-```
-
-**Parameters:**
-- `active_side` (Symbol): Active player side (`:first` or `:second`)
-- `squares` (Hash): Board state where keys are CELL coordinates and values are QPI identifiers or `nil` for empty squares
-
-**Returns:** `Array<Sashite::Stn::Transition>` — Valid state transitions (may be empty)
+ruleset = Sashite::Ggn.parse(ggn_data)
 
----
+# Valid: path is clear
+squares = { "e2" => "C:P", "e3" => nil, "e4" => nil }
+possibilities = ruleset.select("C:P").from("e2").to("e4").where(:first, squares)
+possibilities.any?  # => true
 
-## GGN Format
+# Invalid: e3 is blocked
+squares = { "e2" => "C:P", "e3" => "c:p", "e4" => nil }
+possibilities = ruleset.select("C:P").from("e2").to("e4").where(:first, squares)
+possibilities.any?  # => false
+```
 
-### Structure
+### Pawn Capture
 
 ```ruby
-{
-  "<qpi-piece>" => {
-    "<source-location>" => {
-      "<destination-location>" => [
-        {
-          "must" => { /* LCN format */ },
-          "deny" => { /* LCN format */ },
-          "diff" => { /* STN format */ }
-        }
-      ]
+# Diagonal capture
+ggn_data = {
+  "C:P" => {
+    "e4" => {
+      "d5" => [{
+        "must" => { "d5" => "enemy" },
+        "deny" => {}
+      }]
     }
   }
 }
-```
 
-### Field Specifications
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **Piece** | String (QPI) | Piece identifier (e.g., `"C:K"`, `"s:+p"`) |
-| **Source** | String (CELL/HAND) | Origin location (e.g., `"e2"`, `"*"`) |
-| **Destination** | String (CELL/HAND) | Target location (e.g., `"e4"`, `"*"`) |
-| **must** | Hash (LCN) | Pre-conditions that must be satisfied |
-| **deny** | Hash (LCN) | Pre-conditions that must not be satisfied |
-| **diff** | Hash (STN) | State transition specification |
-
-**Note (normative)**: To preserve GGN's board-reachability scope, entries where **`source="*"` and `destination="*"`** (direct **HAND→HAND**) are **forbidden** by the specification.
+ruleset = Sashite::Ggn.parse(ggn_data)
 
----
+# Valid: enemy piece on d5
+squares = { "e4" => "C:P", "d5" => "c:p" }
+possibilities = ruleset.select("C:P").from("e4").to("d5").where(:first, squares)
+possibilities.any?  # => true
 
-## Usage Examples
+# Invalid: friendly piece on d5
+squares = { "e4" => "C:P", "d5" => "C:N" }
+possibilities = ruleset.select("C:P").from("e4").to("d5").where(:first, squares)
+possibilities.any?  # => false
+```
 
-### Method Chaining
+### Castling
 
 ```ruby
-# Query specific movement
-active_side = :first
-squares = {
-  "e2" => "C:P",
-  "e3" => nil,
-  "e4" => nil
+# King-side castling
+ggn_data = {
+  "C:K" => {
+    "e1" => {
+      "g1" => [{
+        "must" => {
+          "f1" => "empty",
+          "g1" => "empty",
+          "h1" => "C:+R"     # Rook with castling rights
+        },
+        "deny" => {}
+      }]
+    }
+  }
 }
 
-transitions = ruleset
-  .select("C:P")
-  .from("e2")
-  .to("e4")
-  .where(active_side, squares)
+ruleset = Sashite::Ggn.parse(ggn_data)
 
-transitions.size # => 1
-transitions.first.board_changes # => { "e2" => nil, "e4" => "C:P" }
+# Valid: all conditions met
+squares = {
+  "e1" => "C:+K",
+  "f1" => nil,
+  "g1" => nil,
+  "h1" => "C:+R"
+}
+possibilities = ruleset.select("C:K").from("e1").to("g1").where(:first, squares)
+possibilities.any?  # => true
 ```
 
-### Building Board State
+### Shogi Drop
 
 ```ruby
-# Example: Build squares hash from FEEN position
-require "sashite/feen"
-
-feen = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
-position = Sashite::Feen.parse(feen)
-
-# Extract active player side
-active_side = position.styles.active.side # => :first
-
-# Build squares hash from placement
-squares = {}
-position.placement.ranks.each_with_index do |rank, rank_idx|
-  rank.each_with_index do |piece, file_idx|
-    # Convert rank_idx and file_idx to CELL coordinate
-    cell = Sashite::Cell.from_indices(file_idx, 7 - rank_idx)
-    squares[cell] = piece&.to_s
-  end
-end
-
-# Use with GGN
-transitions = engine.where(active_side, squares)
-```
+# Pawn drop with file restriction
+ggn_data = {
+  "S:P" => {
+    "*" => {              # From hand
+      "e4" => [{
+        "must" => { "e4" => "empty" },
+        "deny" => {       # No friendly pawn on same file
+          "e1" => "S:P", "e2" => "S:P", "e3" => "S:P",
+          "e5" => "S:P", "e6" => "S:P", "e7" => "S:P",
+          "e8" => "S:P", "e9" => "S:P"
+        }
+      }]
+    }
+  }
+}
 
-### Capture Validation
+ruleset = Sashite::Ggn.parse(ggn_data)
 
-```ruby
-# Check capture possibility
-active_side = :first
+# Valid: no pawn on e-file
 squares = {
-  "e4" => "C:P",  # White pawn
-  "d5" => "c:p",  # Black pawn (enemy)
-  "f5" => "c:p"   # Black pawn (enemy)
+  "e1" => nil, "e2" => nil, "e3" => nil, "e4" => nil,
+  "e5" => nil, "e6" => nil, "e7" => nil, "e8" => nil, "e9" => nil
 }
+possibilities = ruleset.select("S:P").from("*").to("e4").where(:first, squares)
+possibilities.any?  # => true
 
-# Pawn can capture diagonally
-capture_engine = ruleset.select("C:P").from("e4").to("d5")
-transitions = capture_engine.where(active_side, squares)
-
-transitions.any? # => true if capture is allowed
+# Invalid: pawn already on e5
+squares["e5"] = "S:P"
+possibilities = ruleset.select("S:P").from("*").to("e4").where(:first, squares)
+possibilities.any?  # => false
 ```
 
-### Existence Checks
+### En Passant
 
 ```ruby
-# Check if piece exists in ruleset
-ruleset.piece?("C:K") # => true
-
-# Check valid sources
-source = ruleset.select("C:K")
-source.source?("e1") # => true
-
-# Check valid destinations
-destination = source.from("e1")
-destination.destination?("e2") # => true
-```
-
-### Introspection
-
-```ruby
-# List all pieces
-ruleset.pieces # => ["C:K", "C:Q", "C:R", ...]
+# En passant capture
+ggn_data = {
+  "C:P" => {
+    "e5" => {
+      "f6" => [{
+        "must" => {
+          "f6" => "empty",
+          "f5" => "c:-p"    # Enemy pawn vulnerable to en passant
+        },
+        "deny" => {}
+      }]
+    }
+  }
+}
 
-# List sources for a piece
-source.sources # => ["e1", "d1", "f1", ...]
+ruleset = Sashite::Ggn.parse(ggn_data)
 
-# List destinations from a source
-destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
+squares = {
+  "e5" => "C:P",
+  "f5" => "c:-p",
+  "f6" => nil
+}
+possibilities = ruleset.select("C:P").from("e5").to("f6").where(:first, squares)
+possibilities.any?  # => true
 ```
 
----
-
-## Design Properties
-
-- **Functional**: Pure functions with no side effects
-- **Immutable**: All data structures frozen and unchangeable
-- **Composable**: Clean method chaining for natural query flow
-- **Minimal API**: Only exposes what's necessary
-- **Type-safe**: Strict validation of all inputs
-- **Lightweight**: Minimal dependencies, no unnecessary parsing
-- **Spec-compliant**: Strictly follows GGN v1.0.0 specification
-
----
-
 ## Error Handling
 
 ```ruby
-# Handle missing piece
+# Missing piece
 begin
-  source = ruleset.select("INVALID:X")
+  ruleset.select("X:Y")
 rescue KeyError => e
-  puts "Piece not found: #{e.message}"
+  puts e.message  # => "Piece not found: X:Y"
 end
 
-# Handle missing source
+# Missing source
 begin
-  destination = source.from("z9")
+  ruleset.select("C:K").from("z9")
 rescue KeyError => e
-  puts "Source not found: #{e.message}"
+  puts e.message  # => "Source not found: z9"
 end
 
-# Handle missing destination
+# Invalid GGN data
 begin
-  engine = destination.to("z9")
-rescue KeyError => e
-  puts "Destination not found: #{e.message}"
+  Sashite::Ggn.parse({ "invalid" => "data" })
+rescue ArgumentError => e
+  puts e.message  # => "Invalid QPI format: invalid"
 end
 
-# Safe validation before parsing
+# Safe validation
 if Sashite::Ggn.valid?(data)
   ruleset = Sashite::Ggn.parse(data)
 else
@@ -491,25 +356,45 @@ else
 end
 ```
 
----
+## GGN Format Restrictions
+
+### HAND→HAND Prohibition
+
+Direct movements from hand to hand (`source="*"` and `destination="*"`) are **forbidden** by the specification:
+
+```ruby
+# This will raise an error
+invalid_ggn = {
+  "S:P" => {
+    "*" => {
+      "*" => [{ "must" => {}, "deny" => {} }]  # FORBIDDEN!
+    }
+  }
+}
+
+Sashite::Ggn.valid?(invalid_ggn)  # => false
+Sashite::Ggn.parse(invalid_ggn)   # => ArgumentError
+```
+
+## Dependencies
 
-## Related Specifications
+This gem depends on other Sashité specifications:
 
-- [GGN v1.0.0](https://sashite.dev/specs/ggn/1.0.0/) — General Gameplay Notation specification
-- [CELL v1.0.0](https://sashite.dev/specs/cell/1.0.0/) — Coordinate encoding
-- [HAND v1.0.0](https://sashite.dev/specs/hand/1.0.0/) — Reserve notation
-- [LCN v1.0.0](https://sashite.dev/specs/lcn/1.0.0/) — Location conditions
-- [QPI v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) — Piece identification
-- [STN v1.0.0](https://sashite.dev/specs/stn/1.0.0/) — State transitions
+- `sashite-cell` - Coordinate encoding (e.g., `"e4"`)
+- `sashite-hand` - Reserve notation (`"*"`)
+- `sashite-lcn` - Location conditions (e.g., `"empty"`, `"enemy"`)
+- `sashite-qpi` - Piece identification (e.g., `"C:K"`)
 
----
+## Resources
+
+- [GGN Specification v1.0.0](https://sashite.dev/specs/ggn/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/ggn.rb/main)
+- [GitHub Repository](https://github.com/sashite/ggn.rb)
 
 ## 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.

data/lib/sashite/ggn/ruleset/source/destination/engine.rb

@@ -1,115 +1,243 @@
 # frozen_string_literal: true
 
-require "sashite/lcn"
-require "sashite/qpi"
-require "sashite/stn"
+require "sashite-lcn"
+require "sashite-qpi"
 
 module Sashite
   module Ggn
     class Ruleset
       class Source
         class Destination
-          # Evaluates movement possibility under given position conditions
+          # Movement possibility evaluator
+          #
+          # Evaluates whether movements are possible based on environmental
+          # pre-conditions as defined in the GGN specification v1.0.0.
+          #
+          # The Engine acts as the final stage in the GGN navigation chain,
+          # determining which movement possibilities from the GGN data structure
+          # are valid given the current board state.
           #
           # @see https://sashite.dev/specs/ggn/1.0.0/
           class Engine
-            # Create a new Engine
+            # Create a new Engine with movement possibilities
+            #
+            # @note This constructor is typically called internally through the
+            #   navigation chain: ruleset.select(piece).from(source).to(destination)
+            #
+            # @param possibilities [Array<Hash>] Array of movement possibility
+            #   objects from the GGN data structure. Each possibility must contain
+            #   "must" and "deny" fields with LCN-formatted conditions.
             #
-            # @param possibilities [Array<Hash>] Movement possibilities data
+            # @example Structure of a possibility
+            #   {
+            #     "must" => { "e3" => "empty", "e4" => "empty" },
+            #     "deny" => { "f3" => "enemy" }
+            #   }
             def initialize(*possibilities)
-              @possibilities = possibilities
+              @possibilities = validate_and_freeze(possibilities)
+
               freeze
             end
 
-            # Evaluate movement against position and return valid transitions
+            # Evaluate which movement possibilities match the current position
             #
-            # @param active_side [Symbol] Active player side (:first or :second)
-            # @param squares [Hash{String => String, nil}] Board state where keys are CELL coordinates
-            #   and values are QPI identifiers or nil for empty squares
-            # @return [Array<Sashite::Stn::Transition>] Valid state transitions (may be empty)
+            # Returns the subset of movement possibilities whose pre-conditions
+            # are satisfied by the current board state. This is the core evaluation
+            # method that determines if a movement is pseudo-legal.
+            #
+            # Each possibility is evaluated independently with the following logic:
+            # - All "must" conditions must be satisfied (AND logic)
+            # - No "deny" conditions can be satisfied (NOR logic)
+            #
+            # The "enemy" keyword in conditions is evaluated from the active
+            # player's perspective, following the LCN specification's standard
+            # interpretation.
+            #
+            # @param active_side [Symbol] Active player side (:first or :second).
+            #   This determines which pieces are considered "enemy" when evaluating
+            #   the "enemy" keyword in conditions.
+            # @param squares [Hash{String => String, nil}] Current board state mapping
+            #   CELL coordinates to QPI piece identifiers. Use nil for empty squares.
+            #   Only squares referenced in conditions need to be included.
+            #
+            # @return [Array<Hash>] Subset of movement possibilities that satisfy their
+            #   pre-conditions. Each returned Hash is the original possibility from the
+            #   GGN data, containing at minimum "must" and "deny" fields.
+            #   Returns an empty array if no possibilities match.
+            #
+            # @raise [ArgumentError] if active_side is not :first or :second
+            #
+            # @example Chess pawn two-square advance
+            #   active_side = :first
+            #   squares = {
+            #     "e2" => "C:P",  # White pawn on starting square
+            #     "e3" => nil,    # Path must be clear
+            #     "e4" => nil     # Destination must be empty
+            #   }
+            #   possibilities = engine.where(active_side, squares)
+            #   # => [{"must" => {"e3" => "empty", "e4" => "empty"}, "deny" => {}}]
             #
-            # @example
+            # @example Capture evaluation with enemy keyword
             #   active_side = :first
             #   squares = {
-            #     "e2" => "C:P",
-            #     "e3" => nil,
-            #     "e4" => nil
+            #     "e4" => "C:P",  # White pawn
+            #     "d5" => "c:p"   # Black pawn (enemy from white's perspective)
             #   }
-            #   transitions = engine.where(active_side, squares)
+            #   possibilities = engine.where(active_side, squares)
+            #   # => [{"must" => {"d5" => "enemy"}, "deny" => {}}]
+            #
+            # @example No matching possibilities (blocked path)
+            #   squares = { "e2" => "C:P", "e3" => "c:p", "e4" => nil }
+            #   possibilities = engine.where(active_side, squares)
+            #   # => []
             def where(active_side, squares)
+              validate_active_side!(active_side)
+              validate_squares!(squares)
+
               @possibilities.select do |possibility|
-                satisfies_must?(possibility["must"], active_side, squares) &&
-                  satisfies_deny?(possibility["deny"], active_side, squares)
-              end.map do |possibility|
-                Stn.parse(possibility["diff"])
+                satisfies_conditions?(possibility, active_side, squares)
               end
             end
 
             private
 
+            # Validate and freeze the possibilities array
+            #
+            # @param possibilities [Array<Hash>] Possibilities to validate
+            # @return [Array<Hash>] Frozen array of validated possibilities
+            # @raise [ArgumentError] if possibilities structure is invalid
+            def validate_and_freeze(possibilities)
+              raise ::ArgumentError, "Possibilities must be an Array" unless possibilities.is_a?(::Array)
+
+              possibilities.each do |possibility|
+                raise ::ArgumentError, "Each possibility must be a Hash" unless possibility.is_a?(::Hash)
+
+                unless possibility.key?("must") && possibility.key?("deny")
+                  raise ::ArgumentError, "Possibility must have 'must' and 'deny' fields"
+                end
+              end
+
+              possibilities.freeze
+            end
+
+            # Validate the active_side parameter
+            #
+            # @param active_side [Symbol] Side to validate
+            # @raise [ArgumentError] if side is invalid
+            def validate_active_side!(active_side)
+              return if %i[first second].include?(active_side)
+
+              raise ::ArgumentError, "active_side must be :first or :second, got: #{active_side.inspect}"
+            end
+
+            # Validate the squares parameter
+            #
+            # @param squares [Hash] Squares to validate
+            # @raise [ArgumentError] if squares is not a Hash
+            def validate_squares!(squares)
+              return if squares.is_a?(Hash)
+
+              raise ::ArgumentError, "squares must be a Hash, got: #{squares.class}"
+            end
+
+            # Check if a possibility's conditions are satisfied
+            #
+            # @param possibility [Hash] Movement possibility with "must" and "deny"
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
+            # @return [Boolean] true if all conditions are satisfied
+            def satisfies_conditions?(possibility, active_side, squares)
+              must_conditions = possibility.fetch("must", {})
+              deny_conditions = possibility.fetch("deny", {})
+
+              satisfies_must?(must_conditions, active_side, squares) &&
+                satisfies_deny?(deny_conditions, active_side, squares)
+            end
+
             # Check if all 'must' conditions are satisfied
             #
-            # @param conditions [Hash] LCN conditions
+            # @param conditions [Hash] LCN conditions that must be true
             # @param active_side [Symbol] Active player side
             # @param squares [Hash] Board state
-            # @return [Boolean]
+            # @return [Boolean] true if all conditions are met
             def satisfies_must?(conditions, active_side, squares)
-              return true if conditions.empty?
+              return true if conditions.nil? || conditions.empty?
 
-              lcn_conditions = Lcn.parse(conditions)
-
-              lcn_conditions.locations.all? do |location|
-                expected_state = lcn_conditions[location]
-                check_condition(location.to_s, expected_state, active_side, squares)
-              end
+              evaluate_lcn_conditions(conditions, active_side, squares, :all?)
             end
 
-            # Check if all 'deny' conditions are not satisfied
+            # Check if no 'deny' conditions are satisfied
             #
-            # @param conditions [Hash] LCN conditions
+            # @param conditions [Hash] LCN conditions that must be false
             # @param active_side [Symbol] Active player side
             # @param squares [Hash] Board state
-            # @return [Boolean]
+            # @return [Boolean] true if none of the conditions are met
             def satisfies_deny?(conditions, active_side, squares)
-              return true if conditions.empty?
+              return true if conditions.nil? || conditions.empty?
+
+              evaluate_lcn_conditions(conditions, active_side, squares, :none?)
+            end
 
-              lcn_conditions = Lcn.parse(conditions)
+            # Evaluate LCN conditions using specified logic
+            #
+            # @param conditions [Hash] LCN conditions to evaluate
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
+            # @param logic_method [Symbol] :all? or :none? for AND/NOR logic
+            # @return [Boolean] Result of condition evaluation
+            def evaluate_lcn_conditions(conditions, active_side, squares, logic_method)
+              # Parse conditions through LCN for validation
+              lcn = ::Sashite::Lcn.parse(conditions)
 
-              lcn_conditions.locations.none? do |location|
-                expected_state = lcn_conditions[location]
-                check_condition(location.to_s, expected_state, active_side, squares)
+              # Evaluate each location condition using the specified logic
+              lcn.locations.public_send(logic_method) do |location|
+                expected_state = lcn[location]
+                location_matches?(location.to_s, expected_state, active_side, squares)
               end
             end
 
-            # Check if a location satisfies a condition
+            # Check if a specific location matches expected state
             #
-            # @param location [String] Location to check (CELL coordinate)
-            # @param expected_state [String] Expected state value
-            # @param active_side [Symbol] Active player side
+            # Evaluates a single location condition against the board state.
+            # Handles the three types of LCN state values:
+            # - "empty": location must be unoccupied
+            # - "enemy": location must contain an opponent's piece
+            # - QPI identifier: location must contain exactly this piece
+            #
+            # @param location [String] CELL coordinate to check
+            # @param expected_state [String] Expected state value from LCN
+            # @param active_side [Symbol] Active player side for enemy evaluation
             # @param squares [Hash] Board state
-            # @return [Boolean]
-            def check_condition(location, expected_state, active_side, squares)
-              actual_qpi = squares[location]
+            # @return [Boolean] true if location matches expected state
+            def location_matches?(location, expected_state, active_side, squares)
+              actual_value = squares[location]
 
               case expected_state
               when "empty"
-                actual_qpi.nil?
+                # Location must be unoccupied
+                actual_value.nil?
               when "enemy"
-                actual_qpi && enemy?(actual_qpi, active_side)
+                # Location must contain opponent's piece
+                # nil check prevents false positives on empty squares
+                !actual_value.nil? && enemy_piece?(actual_value, active_side)
               else
-                # Expected state is a QPI identifier
-                actual_qpi == expected_state
+                # Direct QPI comparison for specific piece requirement
+                actual_value == expected_state
               end
             end
 
-            # Check if a piece is an enemy relative to active side
+            # Determine if a piece belongs to the opponent
             #
-            # @param qpi_str [String] QPI identifier
-            # @param active_side [Symbol] Active player side
-            # @return [Boolean]
-            def enemy?(qpi_str, active_side)
-              piece_side = Qpi.parse(qpi_str).side
-              piece_side != active_side
+            # Uses QPI parsing to extract the piece's side and compares it
+            # with the active player's side. A piece is considered enemy if
+            # its side differs from the active player's side.
+            #
+            # @param qpi_identifier [String] QPI piece identifier (e.g., "C:K", "c:p")
+            # @param active_side [Symbol] Active player side (:first or :second)
+            # @return [Boolean] true if piece belongs to opponent
+            def enemy_piece?(qpi_identifier, active_side)
+              piece = ::Sashite::Qpi.parse(qpi_identifier)
+              piece.side != active_side
             end
           end
         end

data/lib/sashite/ggn/ruleset/source/destination.rb

@@ -15,6 +15,7 @@ module Sashite
           # @param data [Hash] Destinations data structure
           def initialize(data)
             @data = data
+
             freeze
           end
 

data/lib/sashite/ggn/ruleset/source.rb

@@ -14,6 +14,7 @@ module Sashite
         # @param data [Hash] Sources data structure
         def initialize(data)
           @data = data
+
           freeze
         end
 

data/lib/sashite/ggn/ruleset.rb

@@ -23,6 +23,7 @@ module Sashite
       #   ruleset = Sashite::Ggn::Ruleset.new(data)
       def initialize(data)
         @data = data
+
         freeze
       end
 

data/lib/sashite/ggn.rb

@@ -4,7 +4,6 @@ require "sashite/cell"
 require "sashite/hand"
 require "sashite/lcn"
 require "sashite/qpi"
-require "sashite/stn"
 
 require_relative "ggn/ruleset"
 
@@ -29,11 +28,7 @@ module Sashite
     #         "e4" => [
     #           {
     #             "must" => { "e3" => "empty", "e4" => "empty" },
-    #             "deny" => {},
-    #             "diff" => {
-    #               "board" => { "e2" => nil, "e4" => "C:P" },
-    #               "toggle" => true
-    #             }
+    #             "deny" => {}
     #           }
     #         ]
     #       }
@@ -84,7 +79,7 @@ module Sashite
     # @api private
     def self.validate_piece!(piece)
       raise ::ArgumentError, "Invalid piece identifier: #{piece}" unless piece.is_a?(::String)
-      raise ::ArgumentError, "Invalid QPI format: #{piece}" unless Qpi.valid?(piece)
+      raise ::ArgumentError, "Invalid QPI format: #{piece}" unless ::Sashite::Qpi.valid?(piece)
     end
     private_class_method :validate_piece!
 
@@ -132,7 +127,7 @@ module Sashite
     # @return [void]
     # @api private
     def self.validate_hand_to_hand!(source, destination)
-      return unless Hand.reserve?(source) && Hand.reserve?(destination)
+      return unless ::Sashite::Hand.reserve?(source) && ::Sashite::Hand.reserve?(destination)
 
       raise ::ArgumentError, "Invalid HAND→HAND movement: source and destination cannot both be '*' (forbidden by GGN specification)"
     end
@@ -173,11 +168,9 @@ module Sashite
       end
       raise ::ArgumentError, "Possibility must have 'must' field" unless possibility.key?("must")
       raise ::ArgumentError, "Possibility must have 'deny' field" unless possibility.key?("deny")
-      raise ::ArgumentError, "Possibility must have 'diff' field" unless possibility.key?("diff")
 
       validate_lcn_conditions!(possibility["must"], "must", piece, source, destination)
       validate_lcn_conditions!(possibility["deny"], "deny", piece, source, destination)
-      validate_stn_transition!(possibility["diff"], piece, source, destination)
     end
     private_class_method :validate_possibility!
 
@@ -192,28 +185,12 @@ module Sashite
     # @return [void]
     # @api private
     def self.validate_lcn_conditions!(conditions, field_name, piece, source, destination)
-      Lcn.parse(conditions)
+      ::Sashite::Lcn.parse(conditions)
     rescue ::ArgumentError => e
       raise ::ArgumentError, "Invalid LCN format in '#{field_name}' for #{piece} #{source}→#{destination}: #{e.message}"
     end
     private_class_method :validate_lcn_conditions!
 
-    # Validate STN transition
-    #
-    # @param transition [Hash] Transition to validate
-    # @param piece [String] Piece identifier (for error messages)
-    # @param source [String] Source location (for error messages)
-    # @param destination [String] Destination location (for error messages)
-    # @raise [ArgumentError] If transition is invalid
-    # @return [void]
-    # @api private
-    def self.validate_stn_transition!(transition, piece, source, destination)
-      Stn.parse(transition)
-    rescue ::StandardError => e
-      raise ::ArgumentError, "Invalid STN format in 'diff' for #{piece} #{source}→#{destination}: #{e.message}"
-    end
-    private_class_method :validate_stn_transition!
-
     # Validate location format
     #
     # @param location [String] Location to validate
@@ -224,7 +201,7 @@ module Sashite
     def self.validate_location!(location, piece)
       raise ::ArgumentError, "Location for #{piece} must be a String" unless location.is_a?(::String)
 
-      valid = Cell.valid?(location) || Hand.reserve?(location)
+      valid = ::Sashite::Cell.valid?(location) || ::Sashite::Hand.reserve?(location)
       raise ::ArgumentError, "Invalid location format: #{location}" unless valid
     end
     private_class_method :validate_location!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-ggn
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -65,26 +65,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: sashite-stn
-  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: A pure functional Ruby implementation of the General Gameplay Notation
   (GGN) specification v1.0.0. Provides a movement possibility oracle for evaluating
   pseudo-legal moves in abstract strategy board games. Features include hierarchical
   move navigation (piece → source → destination → transitions), pre-condition evaluation
-  (must/deny), and state transition support via STN format. Works with Chess, Shogi,
-  Xiangqi, and custom variants.
+  (must/deny). Works with Chess, Shogi, Xiangqi, and custom variants.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -122,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.6.9
 specification_version: 4
 summary: General Gameplay Notation (GGN) - movement possibilities for board games
 test_files: []