sashite-ggn 0.7.0 → 0.9.0

data/README.md

@@ -1,762 +1,513 @@
 # Ggn.rb
 
-[![Gem Version](https://badge.fury.io/rb/sashite-ggn.svg)](https://badge.fury.io/rb/sashite-ggn)
-[![Ruby](https://github.com/sashite/ggn.rb/workflows/Ruby/badge.svg)](https://github.com/sashite/ggn.rb/actions)
+[![Version](https://img.shields.io/github/v/tag/sashite/ggn.rb?label=Version&logo=github)](https://github.com/sashite/ggn.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/ggn.rb/main)
+![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)
 
-> A Ruby library for **GGN** (General Gameplay Notation) - a rule-agnostic format for describing pseudo-legal moves in abstract strategy board games.
+> **GGN** (General Gameplay Notation) implementation for Ruby — a pure, functional library for evaluating **movement possibilities** in abstract strategy board games.
+
+---
 
 ## What is GGN?
 
-GGN is like having a universal "move library" that works across different board games. Think of it as a detailed catalog that answers: **"Can this piece, currently on this square, reach that square?"** - without worrying about specific game rules like check, ko, or castling rights.
+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.
 
-**Key Features:**
+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.
 
-- **Rule-agnostic**: Works with Chess, Shōgi, Xiangqi, and custom variants
-- **Board-focused**: Describes only board transformations (no hand management)
-- **Pseudo-legal**: Basic movement constraints, not full game legality
-- **JSON-based**: Structured, machine-readable format
-- **Performance-optimized**: Pre-computed move libraries for fast evaluation
-- **Cross-game compatible**: Supports hybrid games mixing different variants
-- **Flexible validation**: Choose between safety and performance
+### Core Philosophy
 
-## Installation
+GGN answers the fundamental question:
+
+> **Can this piece, currently at this location, reach that location?**
 
-Add this line to your application's Gemfile:
+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)
+
+---
+
+## Installation
 
 ```ruby
+# In your Gemfile
 gem "sashite-ggn"
 ```
 
-Or install it directly:
+Or install manually:
 
-```bash
+```sh
 gem install sashite-ggn
 ```
 
-## Quick Start
-
-### Basic Example: Loading Move Rules
-
-```ruby
-require "sashite-ggn"
-
-# Load GGN data from file (with full validation by default)
-ruleset = Sashite::Ggn.load_file("chess_moves.json")
-
-# Query specific piece movement rules
-pawn_source = ruleset.select("CHESS:P")
-destinations = pawn_source.from("e2")
-engine = destinations.to("e4")
+---
 
-# Check if move is valid given current board state
-board_state = {
-  "e2" => "CHESS:P",  # White pawn on e2
-  "e3" => nil,        # Empty square
-  "e4" => nil         # Empty square
-}
+## Dependencies
 
-transitions = engine.where(board_state, "CHESS")
+GGN builds upon foundational Sashité specifications:
 
-if transitions.any?
-  transition = transitions.first
-  puts "Move is valid!"
-  puts "Board changes: #{transition.diff}"
-  # => { "e2" => nil, "e4" => "CHESS:P" }
-else
-  puts "Move blocked or invalid"
-end
+```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
 ```
 
-### Basic Example: Loading from JSON String
+---
+
+## Quick Start
 
 ```ruby
-# Simple pawn double move rule
-ggn_json = {
-  "CHESS:P" => {
+require "sashite/ggn"
+
+# Define GGN data structure
+ggn_data = {
+  "C:P" => {
     "e2" => {
-      "e4" => [{
-        "require" => { "e3" => "empty", "e4" => "empty" },
-        "perform" => { "e2" => nil, "e4" => "CHESS:P" }
-      }]
+      "e4" => [
+        {
+          "must" => { "e3" => "empty", "e4" => "empty" },
+          "deny" => {},
+          "diff" => {
+            "board" => { "e2" => nil, "e4" => "C:P" },
+            "toggle" => true
+          }
+        }
+      ]
     }
   }
 }
 
-ruleset = Sashite::Ggn.load_hash(ggn_json)
-puts "Loaded pawn movement rules!"
-```
+# Validate GGN structure
+Sashite::Ggn.valid?(ggn_data) # => true
 
-## Validation System
+# Parse into ruleset
+ruleset = Sashite::Ggn.parse(ggn_data)
 
-Ggn.rb offers **flexible validation** with two modes:
+# Query movement possibility through method chaining
+source = ruleset.select("C:P")
+destination = source.from("e2")
+engine = destination.to("e4")
 
-### Full Validation (Default)
-```ruby
-# All validations enabled (recommended for development/safety)
-ruleset = Sashite::Ggn.load_file("moves.json")
-# ✓ JSON Schema validation
-# ✓ Logical contradiction detection
-# ✓ Implicit requirement duplication detection
-```
+# Evaluate against position
+active_side = :first
+squares = {
+  "e2" => "C:P",
+  "e3" => nil,
+  "e4" => nil
+}
 
-### Performance Mode
-```ruby
-# All validations disabled (maximum performance)
-ruleset = Sashite::Ggn.load_file("moves.json", validate: false)
-# ✗ No validation (use with pre-validated data)
+transitions = engine.where(active_side, squares)
+transitions.any? # => true
 ```
 
-### Validation Levels
+---
 
-| Validation Type | Purpose | When Enabled |
-|----------------|---------|--------------|
-| **JSON Schema** | Ensures GGN format compliance | `validate: true` in load methods |
-| **Logical Contradictions** | Detects impossible require/prevent conditions | `validate: true` in Ruleset.new |
-| **Implicit Duplications** | Prevents redundant requirements | `validate: true` in Ruleset.new |
+## API Reference
 
-```ruby
-# Selective validation for specific use cases
-if Sashite::Ggn.valid?(data)  # Quick schema check only
-  ruleset = Sashite::Ggn::Ruleset.new(data, validate: false)  # Skip internal validations
-end
-```
+### Module Functions
 
-## Understanding GGN Format
+#### `Sashite::Ggn.parse(data) → Ruleset`
 
-A GGN document has this structure:
+Parses GGN data structure into an immutable Ruleset object.
 
-```json
-{
-  "<piece_identifier>": {
-    "<source_square>": {
-      "<destination_square>": [
-        {
-          "require": { "<square>": "<required_state>" },
-          "prevent": { "<square>": "<forbidden_state>" },
-          "perform": { "<square>": "<new_state_or_null>" }
-        }
-      ]
-    }
-  }
-}
+```ruby
+ruleset = Sashite::Ggn.parse(ggn_data)
 ```
 
-### Core Concepts
-
-- **Piece Identifier**: Uses GAN format like `"CHESS:P"` or `"shogi:+p"`
-- **require**: Conditions that MUST be true (logical AND)
-- **prevent**: Conditions that MUST NOT be true (logical OR)
-- **perform**: Board changes after the move (REQUIRED)
+**Parameters:**
+- `data` (Hash): GGN data structure conforming to specification
 
-### Occupation States
+**Returns:** `Ruleset` — Immutable ruleset object
 
-| State | Meaning |
-|-------|---------|
-| `"empty"` | Square must be empty |
-| `"enemy"` | Square must contain an opposing piece |
-| `"CHESS:K"` | Square must contain exactly this piece |
+**Raises:** `ArgumentError` — If data structure is invalid
 
-## Complete API Reference
+---
 
-### Core Loading Methods
+#### `Sashite::Ggn.valid?(data) → Boolean`
 
-#### `Sashite::Ggn.load_file(filepath, validate: true)`
+Validates GGN data structure against specification.
 
-Loads and validates a GGN JSON file.
+```ruby
+Sashite::Ggn.valid?(ggn_data) # => true
+```
 
 **Parameters:**
-- `filepath` [String] - Path to GGN JSON file
-- `validate` [Boolean] - Whether to perform all validations (default: true)
+- `data` (Hash): Data structure to validate
 
-**Returns:** Ruleset instance
+**Returns:** `Boolean` — True if valid, false otherwise
 
-**Example:**
+---
 
-```ruby
-# Load with full validation (recommended)
-ruleset = Sashite::Ggn.load_file("moves.json")
-
-# Load without validation (faster for large files)
-ruleset = Sashite::Ggn.load_file("large_moves.json", validate: false)
-```
+### `Sashite::Ggn::Ruleset` Class
 
-#### `Sashite::Ggn.load_string(json_string, validate: true)`
+Immutable container for GGN movement rules.
 
-Loads GGN data from a JSON string.
+#### `#select(piece) → Source`
 
-**Example:**
+Selects movement rules for a specific piece type.
 
 ```ruby
-json = '{"CHESS:K": {"e1": {"e2": [{"perform": {"e1": null, "e2": "CHESS:K"}}]}}}'
-ruleset = Sashite::Ggn.load_string(json)
+source = ruleset.select("C:K")
 ```
 
-#### `Sashite::Ggn.load_hash(data, validate: true)`
-
-Creates a ruleset from existing Hash data.
+**Parameters:**
+- `piece` (String): QPI piece identifier
 
-### Navigation Methods
+**Returns:** `Source` — Source selector object
 
-#### `ruleset.select(piece_identifier)`
+**Raises:** `KeyError` — If piece not found in ruleset
 
-Retrieves movement rules for a specific piece type.
+---
 
-**Returns:** Source instance
+#### `#piece?(piece) → Boolean`
 
-**Example:**
+Checks if ruleset contains movement rules for specified piece.
 
 ```ruby
-# Get chess king movement rules
-king_source = ruleset.select("CHESS:K")
-
-# Get promoted shogi pawn rules
-promoted_pawn = ruleset.select("SHOGI:+P")
+ruleset.piece?("C:K") # => true
 ```
 
-#### `source.from(origin_square)`
+**Parameters:**
+- `piece` (String): QPI piece identifier
 
-Gets possible destinations from a source position.
+**Returns:** `Boolean`
 
-**Returns:** Destination instance
+---
 
-#### `destination.to(target_square)`
+#### `#pieces → Array<String>`
 
-Creates an engine for evaluating a specific move.
+Returns all piece identifiers in ruleset.
 
-**Returns:** Engine instance
+```ruby
+ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
+```
 
-#### `engine.where(board_state, active_game)`
+**Returns:** `Array<String>` — QPI piece identifiers
 
-Evaluates move validity and returns transitions.
+---
 
-**Parameters:**
-- `board_state` [Hash] - Current board: `{"square" => "piece_or_nil"}`
-- `active_game` [String] - Current player's game identifier (e.g., "CHESS", "shogi")
+### `Sashite::Ggn::Ruleset::Source` Class
 
-**Returns:** Array of Transition objects
+Represents movement possibilities for a piece type.
 
-**Example:**
+#### `#from(source) → Destination`
 
-```ruby
-board = { "e1" => "CHESS:K", "e2" => nil, "f1" => nil }
-transitions = engine.where(board, "CHESS")
+Specifies the source location for the piece.
 
-transitions.each do |transition|
-  puts "Move result: #{transition.diff}"
-end
+```ruby
+destination = source.from("e1")
 ```
 
-#### `ruleset.pseudo_legal_transitions(board_state, active_game)`
-
-Generates ALL possible moves for the current position.
-
-**Returns:** Array of `[actor, origin, target, transitions]`
+**Parameters:**
+- `source` (String): Source location (CELL coordinate or HAND "*")
 
-**Example:**
+**Returns:** `Destination` — Destination selector object
 
-```ruby
-board = { "e2" => "CHESS:P", "e1" => "CHESS:K" }
-all_moves = ruleset.pseudo_legal_transitions(board, "CHESS")
+**Raises:** `KeyError` — If source not found for this piece
 
-all_moves.each do |actor, origin, target, transitions|
-  puts "#{actor}: #{origin} → #{target} (#{transitions.size} variants)"
-end
-```
+---
 
-## Working with Different Move Types
+#### `#sources → Array<String>`
 
-### Simple Piece Movement
+Returns all valid source locations for this piece.
 
 ```ruby
-# King moves one square in any direction
-{
-  "CHESS:K" => {
-    "e1" => {
-      "e2" => [{ "require" => { "e2" => "empty" }, "perform" => { "e1" => nil, "e2" => "CHESS:K" } }],
-      "f1" => [{ "require" => { "f1" => "empty" }, "perform" => { "e1" => nil, "f1" => "CHESS:K" } }],
-      "d1" => [{ "require" => { "d1" => "empty" }, "perform" => { "e1" => nil, "d1" => "CHESS:K" } }]
-    }
-  }
-}
+source.sources # => ["e1", "d1", "*"]
 ```
 
-### Capturing Moves
+**Returns:** `Array<String>` — Source locations
 
-```ruby
-# Pawn captures diagonally
-{
-  "CHESS:P" => {
-    "e4" => {
-      "f5" => [{
-        "require" => { "f5" => "enemy" },
-        "perform" => { "e4" => nil, "f5" => "CHESS:P" }
-      }]
-    }
-  }
-}
-```
+---
 
-### Sliding Pieces
+#### `#source?(location) → Boolean`
+
+Checks if location is a valid source for this piece.
 
 ```ruby
-# Rook moves along empty file
-{
-  "CHESS:R" => {
-    "a1" => {
-      "a3" => [{
-        "require" => { "a2" => "empty", "a3" => "empty" },
-        "perform" => { "a1" => nil, "a3" => "CHESS:R" }
-      }]
-    }
-  }
-}
+source.source?("e1") # => true
 ```
 
-### Multiple Promotion Choices
+**Parameters:**
+- `location` (String): Source location
 
-```ruby
-# Chess pawn promotion offers 4 choices
-{
-  "CHESS:P" => {
-    "e7" => {
-      "e8" => [
-        { "require" => { "e8" => "empty" }, "perform" => { "e7" => nil, "e8" => "CHESS:Q" } },
-        { "require" => { "e8" => "empty" }, "perform" => { "e7" => nil, "e8" => "CHESS:R" } },
-        { "require" => { "e8" => "empty" }, "perform" => { "e7" => nil, "e8" => "CHESS:B" } },
-        { "require" => { "e8" => "empty" }, "perform" => { "e7" => nil, "e8" => "CHESS:N" } }
-      ]
-    }
-  }
-}
+**Returns:** `Boolean`
 
-# Evaluate promotion
-board = { "e7" => "CHESS:P", "e8" => nil }
-transitions = engine.where(board, "CHESS")
+---
 
-puts "#{transitions.size} promotion choices available"
-transitions.each_with_index do |t, i|
-  piece = t.diff["e8"]
-  puts "Choice #{i + 1}: Promote to #{piece}"
-end
-```
+### `Sashite::Ggn::Ruleset::Source::Destination` Class
 
-### Complex Multi-Square Moves
+Represents movement possibilities from a specific source.
 
-```ruby
-# Castling involves both king and rook
-{
-  "CHESS:K" => {
-    "e1" => {
-      "g1" => [{
-        "require" => { "f1" => "empty", "g1" => "empty", "h1" => "CHESS:R" },
-        "perform" => { "e1" => nil, "f1" => "CHESS:R", "g1" => "CHESS:K", "h1" => nil }
-      }]
-    }
-  }
-}
+#### `#to(destination) → Engine`
 
-# Evaluate castling
-board = { "e1" => "CHESS:K", "f1" => nil, "g1" => nil, "h1" => "CHESS:R" }
-transitions = engine.where(board, "CHESS")
+Specifies the destination location.
 
-if transitions.any?
-  puts "Castling is possible!"
-  puts "Final position: #{transitions.first.diff}"
-end
+```ruby
+engine = destination.to("e2")
 ```
 
-### En Passant Capture
+**Parameters:**
+- `destination` (String): Destination location (CELL coordinate or HAND "*")
 
-```ruby
-# Pawn captures en passant (removes piece from different square)
-{
-  "CHESS:P" => {
-    "d5" => {
-      "e6" => [{
-        "require" => { "e5" => "chess:p", "e6" => "empty" },
-        "perform" => { "d5" => nil, "e5" => nil, "e6" => "CHESS:P" }
-      }]
-    }
-  }
-}
-```
+**Returns:** `Engine` — Movement evaluation engine
 
-### Conditional Moves with Prevention
+**Raises:** `KeyError` — If destination not found from this source
 
-```ruby
-# Move that's blocked by certain pieces
-{
-  "GAME:B" => {
-    "c1" => {
-      "f4" => [{
-        "require" => { "d2" => "empty", "e3" => "empty" },
-        "prevent" => { "g5" => "GAME:K", "h6" => "GAME:Q" },  # Blocked if these pieces present
-        "perform" => { "c1" => nil, "f4" => "GAME:B" }
-      }]
-    }
-  }
-}
-```
+---
 
-## Validation and Error Handling
+#### `#destinations → Array<String>`
 
-### Schema Validation
+Returns all valid destinations from this source.
 
 ```ruby
-# Validate GGN data structure
-if Sashite::Ggn.valid?(ggn_data)
-  puts "Valid GGN format"
-else
-  errors = Sashite::Ggn.validation_errors(ggn_data)
-  puts "Validation errors: #{errors}"
-end
-
-# Validate and raise exception on failure
-begin
-  Sashite::Ggn.validate!(ggn_data)
-  puts "Data is valid"
-rescue Sashite::Ggn::ValidationError => e
-  puts "Invalid: #{e.message}"
-end
+destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
 ```
 
-### Safe Loading for User Input
+**Returns:** `Array<String>` — Destination locations
 
-```ruby
-def load_user_ggn_file(filepath, environment = :development)
-  validate = (environment == :development)  # Full validation in dev only
-
-  ruleset = Sashite::Ggn.load_file(filepath, validate: validate)
-  puts "Successfully loaded #{filepath}"
-  ruleset
-rescue Sashite::Ggn::ValidationError => e
-  puts "Failed to load #{filepath}: #{e.message}"
-  nil
-end
-```
+---
 
-### Logical Validation
+#### `#destination?(location) → Boolean`
 
-The library automatically detects logical inconsistencies when `validate: true`:
+Checks if location is a valid destination from this source.
 
 ```ruby
-# ❌ This will raise ValidationError - logical contradiction
-invalid_data = {
-  "CHESS:B" => {
-    "c1" => {
-      "f4" => [{
-        "require" => { "d2" => "empty" },
-        "prevent" => { "d2" => "empty" },  # Contradiction!
-        "perform" => { "c1" => nil, "f4" => "CHESS:B" }
-      }]
-    }
-  }
-}
-
-# ❌ This will raise ValidationError - redundant implicit requirement
-invalid_data = {
-  "CHESS:K" => {
-    "e1" => {
-      "e2" => [{
-        "require" => { "e1" => "CHESS:K" },  # Redundant!
-        "perform" => { "e1" => nil, "e2" => "CHESS:K" }
-      }]
-    }
-  }
-}
+destination.destination?("e2") # => true
 ```
 
-## Working with Different Games
-
-### Chess Integration
-
-```ruby
-# Load chess move rules
-chess_rules = Sashite::Ggn.load_file("chess.json")
+**Parameters:**
+- `location` (String): Destination location
 
-# Evaluate specific chess position
-board = {
-  "e1" => "CHESS:K", "d1" => "CHESS:Q", "a1" => "CHESS:R", "h1" => "CHESS:R",
-  "e2" => "CHESS:P", "d2" => "CHESS:P", "f2" => "CHESS:P", "g2" => "CHESS:P"
-}
+**Returns:** `Boolean`
 
-all_moves = chess_rules.pseudo_legal_transitions(board, "CHESS")
-puts "White has #{all_moves.size} possible moves"
-```
+---
 
-### Shōgi Integration
+### `Sashite::Ggn::Ruleset::Source::Destination::Engine` Class
 
-```ruby
-# Load shogi move rules
-shogi_rules = Sashite::Ggn.load_file("shogi.json")
+Evaluates movement possibility under given position conditions.
 
-# Query promoted piece movement
-promoted_pawn = shogi_rules.select("SHOGI:+P")
-destinations = promoted_pawn.from("5e")
-```
+#### `#where(active_side, squares) → Array<Transition>`
 
-### Cross-Game Scenarios
+Evaluates movement against position and returns valid transitions.
 
 ```ruby
-# Hybrid game with pieces from different variants
-mixed_data = {
-  "CHESS:K" => { /* chess king rules */ },
-  "SHOGI:G" => { /* shogi gold rules */ },
-  "XIANGQI:E" => { /* xiangqi elephant rules */ }
+active_side = :first
+squares = {
+  "e2" => "C:P",  # White pawn on e2
+  "e3" => nil,    # Empty square
+  "e4" => nil     # Empty square
 }
 
-ruleset = Sashite::Ggn.load_hash(mixed_data)
-
-# All uppercase pieces controlled by same player
-board = { "e1" => "CHESS:K", "f1" => "SHOGI:G", "g1" => "XIANGQI:E" }
-moves = ruleset.pseudo_legal_transitions(board, "MIXED")
+transitions = engine.where(active_side, squares)
 ```
 
-## Advanced Features
+**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
 
-### Performance Optimization
+**Returns:** `Array<Sashite::Stn::Transition>` — Valid state transitions (may be empty)
 
-```ruby
-# Choose validation level based on your needs
-def load_ggn_optimized(filepath, trusted_source: false)
-  if trusted_source
-    # Maximum performance for pre-validated data
-    Sashite::Ggn.load_file(filepath, validate: false)
-  else
-    # Full validation for safety
-    Sashite::Ggn.load_file(filepath, validate: true)
-  end
-end
+---
 
-# Pre-validate once, then use fast loading
-if Sashite::Ggn.valid?(data)
-  fast_ruleset = Sashite::Ggn.load_hash(data, validate: false)
-else
-  puts "Invalid data detected"
-end
-```
+## GGN Format
 
-### Custom Game Development
+### Structure
 
 ```ruby
-# Define movement rules for custom game pieces
-custom_ggn = {
-  "MYGAME:X" => {
-    "a1" => {
-      "c3" => [{
-        "require" => { "b2" => "empty" },
-        "perform" => { "a1" => nil, "c3" => "MYGAME:X" }
-      }]
+{
+  "<qpi-piece>" => {
+    "<source-location>" => {
+      "<destination-location>" => [
+        {
+          "must" => { /* LCN format */ },
+          "deny" => { /* LCN format */ },
+          "diff" => { /* STN format */ }
+        }
+      ]
     }
   }
 }
-
-ruleset = Sashite::Ggn.load_hash(custom_ggn)
 ```
 
-### Database Integration
-
-```ruby
-class MoveDatabase
-  def initialize
-    @rulesets = {}
-  end
-
-  def load_game_rules(game_name, filepath, validate: true)
-    @rulesets[game_name] = Sashite::Ggn.load_file(filepath, validate: validate)
-  rescue Sashite::Ggn::ValidationError => e
-    warn "Failed to load #{game_name}: #{e.message}"
-  end
-
-  def evaluate_position(game_name, board_state, active_player)
-    ruleset = @rulesets[game_name]
-    return [] unless ruleset
-
-    ruleset.pseudo_legal_transitions(board_state, active_player)
-  end
-end
+### Field Specifications
 
-# Usage
-db = MoveDatabase.new
-db.load_game_rules("chess", "rules/chess.json", validate: true)   # Full validation
-db.load_game_rules("shogi", "rules/shogi.json", validate: false)  # Fast loading
+| 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 |
 
-moves = db.evaluate_position("chess", board_state, "CHESS")
-```
+---
 
-## Real-World Examples
+## Usage Examples
 
-### Game Engine Integration
+### Method Chaining
 
 ```ruby
-class GameEngine
-  def initialize(ruleset)
-    @ruleset = ruleset
-  end
+# Query specific movement
+active_side = :first
+squares = {
+  "e2" => "C:P",
+  "e3" => nil,
+  "e4" => nil
+}
 
-  def legal_moves(board_state, active_player)
-    # Get all pseudo-legal moves from GGN
-    pseudo_legal = @ruleset.pseudo_legal_transitions(board_state, active_player)
+transitions = ruleset
+  .select("C:P")
+  .from("e2")
+  .to("e4")
+  .where(active_side, squares)
 
-    # Filter for actual legality (check, etc.) - game-specific logic
-    pseudo_legal.select { |move| actually_legal?(move, board_state) }
-  end
+transitions.size # => 1
+transitions.first.board_changes # => { "e2" => nil, "e4" => "C:P" }
+```
 
-  def make_move(actor, origin, target, board_state, active_player)
-    engine = @ruleset.select(actor).from(origin).to(target)
-    transitions = engine.where(board_state, active_player)
+### Building Board State
 
-    return nil if transitions.empty?
+```ruby
+# Example: Build squares hash from FEEN position
+require "sashite/feen"
 
-    # Apply the first valid transition (or let user choose for promotions)
-    transition = transitions.first
-    apply_transition(board_state, transition.diff)
-  end
+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)
 
-  private
+# Extract active player side
+active_side = position.styles.active.side # => :first
 
-  def apply_transition(board_state, diff)
-    new_board = board_state.dup
-    diff.each { |square, piece| new_board[square] = piece }
-    new_board
+# 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)
 ```
 
-### Move Validation Service
+### Capture Validation
 
 ```ruby
-class MoveValidator
-  def initialize(ggn_filepath, validate_ggn: true)
-    @ruleset = Sashite::Ggn.load_file(ggn_filepath, validate: validate_ggn)
-  end
-
-  def validate_move(piece, from, to, board, player)
-    begin
-      engine = @ruleset.select(piece).from(from).to(to)
-      transitions = engine.where(board, player)
-
-      {
-        valid: transitions.any?,
-        transitions: transitions,
-        error: nil
-      }
-    rescue KeyError
-      { valid: false, transitions: [], error: "Unknown piece or position" }
-    rescue => e
-      { valid: false, transitions: [], error: e.message }
-    end
-  end
-end
+# Check capture possibility
+active_side = :first
+squares = {
+  "e4" => "C:P",  # White pawn
+  "d5" => "c:p",  # Black pawn (enemy)
+  "f5" => "c:p"   # Black pawn (enemy)
+}
 
-# Usage
-validator = MoveValidator.new("chess.json", validate_ggn: true)
-result = validator.validate_move("CHESS:P", "e2", "e4", board_state, "CHESS")
+# Pawn can capture diagonally
+capture_engine = ruleset.select("C:P").from("e4").to("d5")
+transitions = capture_engine.where(active_side, squares)
 
-if result[:valid]
-  puts "Move is valid"
-  puts "#{result[:transitions].size} possible outcomes"
-else
-  puts "Invalid move: #{result[:error]}"
-end
+transitions.any? # => true if capture is allowed
 ```
 
-## Best Practices
-
-### 1. Choose Validation Level Appropriately
+### Existence Checks
 
 ```ruby
-# Development: Always validate for safety
-ruleset = Sashite::Ggn.load_file(filepath, validate: true)
-
-# Production with trusted data: Optimize for performance
-ruleset = Sashite::Ggn.load_file(filepath, validate: false)
-
-# Production with untrusted data: Validate first, then cache
-def load_rules_safely(filepath)
-  # Validate once during deployment
-  Sashite::Ggn.validate!(JSON.parse(File.read(filepath)))
-
-  # Then use fast loading in runtime
-  Sashite::Ggn.load_file(filepath, validate: false)
-rescue Sashite::Ggn::ValidationError => e
-  puts "GGN validation failed: #{e.message}"
-  exit(1)
-end
+# 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
 ```
 
-### 2. Handle Multiple Variants Gracefully
+### Introspection
 
 ```ruby
-# Good: Let users choose promotion pieces
-def handle_promotion(transitions)
-  return transitions.first if transitions.size == 1
-
-  puts "Choose promotion:"
-  transitions.each_with_index do |t, i|
-    piece = t.diff.values.find { |v| v&.include?(":") }
-    puts "#{i + 1}. #{piece}"
-  end
+# List all pieces
+ruleset.pieces # => ["C:K", "C:Q", "C:R", ...]
 
-  choice = gets.to_i - 1
-  transitions[choice] if choice.between?(0, transitions.size - 1)
-end
+# List sources for a piece
+source.sources # => ["e1", "d1", "f1", ...]
+
+# List destinations from a source
+destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
 ```
 
-### 3. Use Consistent Game Identifiers
+---
 
-```ruby
-# Good: Clear, consistent naming
-GAME_IDENTIFIERS = {
-  chess_white: "CHESS",
-  chess_black: "chess",
-  shogi_sente: "SHOGI",
-  shogi_gote: "shogi"
-}.freeze
-```
+## 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
 
-### 4. Error Handling Strategy
+---
+
+## Error Handling
 
 ```ruby
-# Good: Comprehensive error handling
+# Handle missing piece
 begin
-  ruleset = Sashite::Ggn.load_file(filepath, validate: validate_level)
-rescue Sashite::Ggn::ValidationError => e
-  logger.error "GGN validation failed: #{e.message}"
-  raise GameLoadError, "Invalid move rules file"
-rescue Errno::ENOENT
-  logger.error "Move rules file not found: #{filepath}"
-  raise GameLoadError, "Move rules file missing"
+  source = ruleset.select("INVALID:X")
+rescue KeyError => e
+  puts "Piece not found: #{e.message}"
 end
-```
 
-## Compatibility and Performance
+# Handle missing source
+begin
+  destination = source.from("z9")
+rescue KeyError => e
+  puts "Source not found: #{e.message}"
+end
 
-- **Ruby Version**: >= 3.2.0
-- **Thread Safety**: All operations are thread-safe
-- **Memory**: Efficient hash-based lookup
-- **Performance**: O(1) piece selection, O(n) move generation
-- **Validation**: Flexible validation system for different use cases
+# Handle missing destination
+begin
+  engine = destination.to("z9")
+rescue KeyError => e
+  puts "Destination not found: #{e.message}"
+end
 
-## Related Sashité Specifications
+# Safe validation before parsing
+if Sashite::Ggn.valid?(data)
+  ruleset = Sashite::Ggn.parse(data)
+else
+  puts "Invalid GGN structure"
+end
+```
 
-GGN works alongside other Sashité notation standards:
+---
 
-- [GAN v1.0.0](https://sashite.dev/documents/gan/1.0.0/) - General Actor Notation for piece identifiers
-- [FEEN v1.0.0](https://sashite.dev/documents/feen/1.0.0/) - Board position representation
-- [PNN v1.0.0](https://sashite.dev/documents/pnn/1.0.0/) - Piece notation with state modifiers
-- [PMN v1.0.0](https://sashite.dev/documents/pmn/1.0.0/) - Portable move notation for game sequences
+## Related Specifications
 
-## Contributing
+- [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
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sashite/ggn.rb.
+---
 
 ## License
 
-The [gem](https://rubygems.org/gems/sashite-ggn) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
 
-## About Sashité
+## About
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.