sashite-ggn 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dab117559875291772b7e8f60077f670928755870b39badd3555f4d66fd8357
-  data.tar.gz: 2fe3fd39dbb288dc140b10c4c9fec523d2ce00a7d33d7802d8612b95e2268ed3
+  metadata.gz: f2933dadd55b72474ca9ab12a6012cdd5dfa7acc6cf82d2f38ed5968c2ee3778
+  data.tar.gz: 49b9c26e3089a2ea0ab46a78129b9d680a9efbfd781437e147d4e7976ff4b2bd
 SHA512:
-  metadata.gz: 805c62503574bbc3b985cc21cb4dfe7a15e03198d97a5e7f0d91508111fd7290ed7382f93f2db6d653f07593f06a65c2640ac4e027127e0bdd964cdc61edab5c
-  data.tar.gz: fc0330900649313e22511f44d391d5a73befdabe4038aa4744de3f8af12684767c410bd6f8aa7e4a88f961cecc6d7be1223e00cfd9736396d92d7c781fa5abea
+  metadata.gz: b665fff9818a2f41dd5623190c69b2904e20bf053730a5f7ca5c48cf51d81a42c62813cd34500d3e13bfaee8bcc41196d8456feaa319bd22d60324e61d04cf5a
+  data.tar.gz: ed68e3ff5e50d0e32908b3d78a96448f5258b071948d3644514dab995f2e3c461367e3bcab65e748c57e6c23f9bebe27f36c112215706991549feedd941e9f39

data/README.md

@@ -1,147 +1,757 @@
 # Ggn.rb
 
-A Ruby implementation of the General Gameplay Notation (GGN) specification for describing pseudo-legal moves in abstract strategy board games.
-
 [![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)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/ggn.rb/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)
 
-## What is GGN?
+> 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) is a rule-agnostic, JSON-based format for representing pseudo-legal moves in abstract strategy board games. This gem implements the [GGN Specification v1.0.0](https://sashite.dev/documents/ggn/1.0.0/).
+## What is GGN?
 
-GGN focuses exclusively on **board-to-board transformations**: pieces moving, capturing, or transforming on the game board. It describes basic movement constraints rather than game-specific legality rules, making it suitable for:
+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.
 
-- Cross-game move analysis and engine development
-- Hybrid games combining elements from different chess variants
-- Database systems requiring piece disambiguation across game types
-- Performance-critical applications with pre-computed move libraries
+**Key Features:**
 
-**Note**: GGN does not support hand management, piece drops, or captures-to-hand. These mechanics should be handled at a higher level by game engines.
+- **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
 
 ## Installation
 
+Add this line to your application's Gemfile:
+
 ```ruby
-gem 'sashite-ggn'
+gem "sashite-ggn"
+```
+
+Or install it directly:
+
+```bash
+gem install sashite-ggn
 ```
 
-## Basic Usage
+## Quick Start
 
-### Loading GGN Data
+### Basic Example: Loading Move Rules
 
 ```ruby
 require "sashite-ggn"
 
-# Load from file
+# Load GGN data from file (with full validation by default)
 ruleset = Sashite::Ggn.load_file("chess_moves.json")
 
-# Load from string
-json = '{"CHESS:P": {"e2": {"e4": [{"perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
+# 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
+}
+
+transitions = engine.where(board_state, "CHESS")
+
+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
+```
+
+### Basic Example: Loading from JSON String
+
+```ruby
+# Simple pawn double move rule
+ggn_json = {
+  "CHESS:P" => {
+    "e2" => {
+      "e4" => [{
+        "require" => { "e3" => "empty", "e4" => "empty" },
+        "perform" => { "e2" => nil, "e4" => "CHESS:P" }
+      }]
+    }
+  }
+}
+
+ruleset = Sashite::Ggn.load_hash(ggn_json)
+puts "Loaded pawn movement rules!"
+```
+
+## Validation System
+
+Ggn.rb offers **flexible validation** with two modes:
+
+### 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
+```
+
+### Performance Mode
+```ruby
+# All validations disabled (maximum performance)
+ruleset = Sashite::Ggn.load_file("moves.json", validate: false)
+# ✗ No validation (use with pre-validated data)
+```
+
+### 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 |
+
+```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
+```
+
+## Understanding GGN Format
+
+A GGN document has this structure:
+
+```json
+{
+  "<piece_identifier>": {
+    "<source_square>": {
+      "<destination_square>": [
+        {
+          "require": { "<square>": "<required_state>" },
+          "prevent": { "<square>": "<forbidden_state>" },
+          "perform": { "<square>": "<new_state_or_null>" }
+        }
+      ]
+    }
+  }
+}
+```
+
+### 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)
+
+### Occupation States
+
+| State | Meaning |
+|-------|---------|
+| `"empty"` | Square must be empty |
+| `"enemy"` | Square must contain an opposing piece |
+| `"CHESS:K"` | Square must contain exactly this piece |
+
+## Complete API Reference
+
+### Core Loading Methods
+
+#### `Sashite::Ggn.load_file(filepath, validate: true)`
+
+Loads and validates a GGN JSON file.
+
+**Parameters:**
+- `filepath` [String] - Path to GGN JSON file
+- `validate` [Boolean] - Whether to perform all validations (default: true)
+
+**Returns:** Ruleset instance
+
+**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.load_string(json_string, validate: true)`
+
+Loads GGN data from a JSON string.
+
+**Example:**
+
+```ruby
+json = '{"CHESS:K": {"e1": {"e2": [{"perform": {"e1": null, "e2": "CHESS:K"}}]}}}'
 ruleset = Sashite::Ggn.load_string(json)
 ```
 
-### Evaluating Moves
+#### `Sashite::Ggn.load_hash(data, validate: true)`
+
+Creates a ruleset from existing Hash data.
+
+### Navigation Methods
+
+#### `ruleset.select(piece_identifier)`
+
+Retrieves movement rules for a specific piece type.
+
+**Returns:** Source instance
+
+**Example:**
 
 ```ruby
-# Query specific move
-engine = ruleset.select("CHESS:P").from("e2").to("e4")
+# Get chess king movement rules
+king_source = ruleset.select("CHESS:K")
+
+# Get promoted shogi pawn rules
+promoted_pawn = ruleset.select("SHOGI:+P")
+```
 
-# Define board state
-board_state = { "e2" => "CHESS:P", "e3" => nil, "e4" => nil }
+#### `source.from(origin_square)`
 
-# Evaluate move
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"e2"=>nil, "e4"=>"CHESS:P"}>]
+Gets possible destinations from a source position.
+
+**Returns:** Destination instance
+
+#### `destination.to(target_square)`
+
+Creates an engine for evaluating a specific move.
+
+**Returns:** Engine instance
+
+#### `engine.where(board_state, active_game)`
+
+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")
+
+**Returns:** Array of Transition objects
+
+**Example:**
+
+```ruby
+board = { "e1" => "CHESS:K", "e2" => nil, "f1" => nil }
+transitions = engine.where(board, "CHESS")
+
+transitions.each do |transition|
+  puts "Move result: #{transition.diff}"
+end
 ```
 
-### Generating All Moves
+#### `ruleset.pseudo_legal_transitions(board_state, active_game)`
+
+Generates ALL possible moves for the current position.
+
+**Returns:** Array of `[actor, origin, target, transitions]`
+
+**Example:**
 
 ```ruby
-# Get all pseudo-legal moves for current position
-all_moves = ruleset.pseudo_legal_transitions(board_state, "CHESS")
+board = { "e2" => "CHESS:P", "e1" => "CHESS:K" }
+all_moves = ruleset.pseudo_legal_transitions(board, "CHESS")
 
-# Each move is represented as [actor, origin, target, transitions]
 all_moves.each do |actor, origin, target, transitions|
   puts "#{actor}: #{origin} → #{target} (#{transitions.size} variants)"
 end
 ```
 
-## Move Variants
+## Working with Different Move Types
 
-GGN supports multiple outcomes for a single move (e.g., promotion choices):
+### Simple Piece Movement
 
 ```ruby
-# Chess pawn promotion
-engine = ruleset.select("CHESS:P").from("e7").to("e8")
-transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, "CHESS")
+# 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" } }]
+    }
+  }
+}
+```
 
-transitions.each do |transition|
-  promoted_piece = transition.diff["e8"]
-  puts "Promote to #{promoted_piece}"
+### Capturing Moves
+
+```ruby
+# Pawn captures diagonally
+{
+  "CHESS:P" => {
+    "e4" => {
+      "f5" => [{
+        "require" => { "f5" => "enemy" },
+        "perform" => { "e4" => nil, "f5" => "CHESS:P" }
+      }]
+    }
+  }
+}
+```
+
+### Sliding Pieces
+
+```ruby
+# Rook moves along empty file
+{
+  "CHESS:R" => {
+    "a1" => {
+      "a3" => [{
+        "require" => { "a2" => "empty", "a3" => "empty" },
+        "perform" => { "a1" => nil, "a3" => "CHESS:R" }
+      }]
+    }
+  }
+}
+```
+
+### Multiple Promotion Choices
+
+```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" } }
+      ]
+    }
+  }
+}
+
+# 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
+```
+
+### Complex Multi-Square Moves
+
+```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 }
+      }]
+    }
+  }
+}
+
+# Evaluate castling
+board = { "e1" => "CHESS:K", "f1" => nil, "g1" => nil, "h1" => "CHESS:R" }
+transitions = engine.where(board, "CHESS")
+
+if transitions.any?
+  puts "Castling is possible!"
+  puts "Final position: #{transitions.first.diff}"
 end
-# Output: CHESS:Q, CHESS:R, CHESS:B, CHESS:N
 ```
 
-## Complex Moves
+### En Passant Capture
 
-GGN can represent multi-square moves like castling:
+```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" }
+      }]
+    }
+  }
+}
+```
+
+### Conditional Moves with Prevention
 
 ```ruby
-# Castling (king and rook move simultaneously)
-engine = ruleset.select("CHESS:K").from("e1").to("g1")
-board_state = {
-  "e1" => "CHESS:K", "f1" => nil, "g1" => nil, "h1" => "CHESS:R"
+# 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" }
+      }]
+    }
+  }
 }
+```
 
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"e1"=>nil, "f1"=>"CHESS:R", "g1"=>"CHESS:K", "h1"=>nil}>]
+## Validation and Error Handling
+
+### Schema Validation
+
+```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
 ```
 
-## Conditional Moves
+### Safe Loading for User Input
 
-GGN supports moves with complex requirements and prevent conditions:
+```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
+
+The library automatically detects logical inconsistencies when `validate: true`:
 
 ```ruby
-# En passant capture (removes pawn from different square)
-engine = ruleset.select("CHESS:P").from("d5").to("e6")
-board_state = {
-  "d5" => "CHESS:P", "e5" => "chess:p", "e6" => nil
+# ❌ 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" }
+      }]
+    }
+  }
 }
 
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"d5"=>nil, "e5"=>nil, "e6"=>"CHESS:P"}>]
+# ❌ This will raise ValidationError - redundant implicit requirement
+invalid_data = {
+  "CHESS:K" => {
+    "e1" => {
+      "e2" => [{
+        "require" => { "e1" => "CHESS:K" },  # Redundant!
+        "perform" => { "e1" => nil, "e2" => "CHESS:K" }
+      }]
+    }
+  }
+}
+```
+
+## Working with Different Games
+
+### Chess Integration
+
+```ruby
+# Load chess move rules
+chess_rules = Sashite::Ggn.load_file("chess.json")
+
+# 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"
+}
+
+all_moves = chess_rules.pseudo_legal_transitions(board, "CHESS")
+puts "White has #{all_moves.size} possible moves"
+```
+
+### Shōgi Integration
+
+```ruby
+# Load shogi move rules
+shogi_rules = Sashite::Ggn.load_file("shogi.json")
+
+# Query promoted piece movement
+promoted_pawn = shogi_rules.select("SHOGI:+P")
+destinations = promoted_pawn.from("5e")
+```
+
+### Cross-Game Scenarios
+
+```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 */ }
+}
+
+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")
+```
+
+## Advanced Features
+
+### Performance Optimization
+
+```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
+```
+
+### Custom Game Development
+
+```ruby
+# Define movement rules for custom game pieces
+custom_ggn = {
+  "MYGAME:X" => {
+    "a1" => {
+      "c3" => [{
+        "require" => { "b2" => "empty" },
+        "perform" => { "a1" => nil, "c3" => "MYGAME:X" }
+      }]
+    }
+  }
+}
+
+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
+
+# 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
+
+moves = db.evaluate_position("chess", board_state, "CHESS")
+```
+
+## Real-World Examples
+
+### Game Engine Integration
+
+```ruby
+class GameEngine
+  def initialize(ruleset)
+    @ruleset = ruleset
+  end
+
+  def legal_moves(board_state, active_player)
+    # Get all pseudo-legal moves from GGN
+    pseudo_legal = @ruleset.pseudo_legal_transitions(board_state, active_player)
+
+    # Filter for actual legality (check, etc.) - game-specific logic
+    pseudo_legal.select { |move| actually_legal?(move, board_state) }
+  end
+
+  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)
+
+    return nil if transitions.empty?
+
+    # Apply the first valid transition (or let user choose for promotions)
+    transition = transitions.first
+    apply_transition(board_state, transition.diff)
+  end
+
+  private
+
+  def apply_transition(board_state, diff)
+    new_board = board_state.dup
+    diff.each { |square, piece| new_board[square] = piece }
+    new_board
+  end
+end
+```
+
+### Move Validation Service
+
+```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
+
+# Usage
+validator = MoveValidator.new("chess.json", validate_ggn: true)
+result = validator.validate_move("CHESS:P", "e2", "e4", board_state, "CHESS")
+
+if result[:valid]
+  puts "Move is valid"
+  puts "#{result[:transitions].size} possible outcomes"
+else
+  puts "Invalid move: #{result[:error]}"
+end
+```
+
+## Best Practices
+
+### 1. Choose Validation Level Appropriately
+
+```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
 ```
 
-## Validation
+### 2. Handle Multiple Variants Gracefully
 
 ```ruby
-# Validate GGN data
-Sashite::Ggn.validate!(data)  # Raises exception on failure
-Sashite::Ggn.valid?(data)     # Returns boolean
+# 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
+
+  choice = gets.to_i - 1
+  transitions[choice] if choice.between?(0, transitions.size - 1)
+end
 ```
 
-## API Reference
+### 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
+```
+
+### 4. Error Handling Strategy
+
+```ruby
+# Good: Comprehensive error handling
+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"
+end
+```
 
-### Core Classes
+## Compatibility and Performance
 
-- `Sashite::Ggn::Ruleset` - Main entry point for querying moves
-- `Sashite::Ggn::Ruleset::Source` - Piece type with source positions
-- `Sashite::Ggn::Ruleset::Source::Destination` - Available destinations
-- `Sashite::Ggn::Ruleset::Source::Destination::Engine` - Move evaluator
-- `Sashite::Ggn::Ruleset::Source::Destination::Engine::Transition` - Move result
+- **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
 
-### Key Methods
+## Related Sashité Specifications
 
-- `#pseudo_legal_transitions(board_state, active_game)` - Generate all moves
-- `#select(actor).from(origin).to(target)` - Query specific move
-- `#where(board_state, active_game)` - Evaluate move validity
+GGN works alongside other Sashité notation standards:
 
-## Related Specifications
+- [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
 
-GGN works alongside other Sashité specifications:
+## Contributing
 
-- [GAN](https://sashite.dev/documents/gan/1.0.0/) - General Actor Notation for piece identifiers
-- [FEEN](https://sashite.dev/documents/feen/1.0.0/) - Board position representation
-- [PMN](https://sashite.dev/documents/pmn/1.0.0/) - Move sequence representation
+Bug reports and pull requests are welcome on GitHub at https://github.com/sashite/ggn.rb.
 
 ## License
 

data/lib/sashite/ggn/ruleset.rb

@@ -21,6 +21,14 @@ module Sashite
     # GGN focuses exclusively on board-to-board transformations. All moves
     # represent pieces moving, capturing, or transforming on the game board.
     #
+    # = Validation Behavior
+    #
+    # When `validate: true` (default), performs:
+    # - Logical contradiction detection in require/prevent conditions
+    # - Implicit requirement duplication detection
+    #
+    # When `validate: false`, skips all internal validations for maximum performance.
+    #
     # @example Basic usage
     #   piece_data = Sashite::Ggn.load_file('chess.json')
     #   chess_king = piece_data.select('CHESS:K')
@@ -51,17 +59,31 @@ module Sashite
       #
       # @param data [Hash] The parsed GGN JSON data structure, where keys are
       #   GAN identifiers and values contain the movement definitions.
+      # @param validate [Boolean] Whether to perform internal validations (default: true).
+      #   When false, skips logical contradiction and implicit requirement checks
+      #   for maximum performance.
       #
       # @raise [ArgumentError] If data is not a Hash
+      # @raise [ValidationError] If validation is enabled and logical issues are found
       #
-      # @example Creating from parsed JSON data
+      # @example Creating from parsed JSON data with full validation
       #   ggn_data = JSON.parse(File.read('chess.json'))
-      #   ruleset = Ruleset.new(ggn_data)
-      def initialize(data)
+      #   ruleset = Ruleset.new(ggn_data)  # validate: true by default
+      #
+      # @example Creating without validation for performance
+      #   ggn_data = JSON.parse(File.read('large_dataset.json'))
+      #   ruleset = Ruleset.new(ggn_data, validate: false)
+      def initialize(data, validate: true)
         raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
 
         @data = data
 
+        if validate
+          # Perform enhanced validations for logical consistency
+          validate_no_implicit_requirement_duplications!
+          validate_no_logical_contradictions!
+        end
+
         freeze
       end
 
@@ -92,7 +114,7 @@ module Sashite
       #   GAME:piece (e.g., CHESS:K, shogi:p, XIANGQI:E)
       def select(actor)
         data = @data.fetch(actor)
-        Source.new(data, actor:)
+        Source.new(data, actor: actor)
       end
 
       # Returns all pseudo-legal move transitions for the given position.
@@ -283,26 +305,162 @@ module Sashite
           raise ::ArgumentError, "Invalid active_game format: #{active_game.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
         end
 
-        # Validate board_state structure (optional deep validation)
-        validate_board_state_structure!(board_state) if ENV['GGN_STRICT_VALIDATION']
+        # Validate board_state structure
+        validate_board_state_structure!(board_state)
       end
 
-      # Validates board_state structure in strict mode.
+      # Validates board_state structure.
       #
-      # This optional validation can be enabled via environment variable
-      # to catch malformed board states during development and testing.
+      # Ensures all square labels are valid strings and all pieces are either nil
+      # or valid strings. This validation helps catch common integration errors
+      # where malformed board states are passed to the GGN engine.
       #
       # @param board_state [Hash] Board state to validate
       #
       # @raise [ArgumentError] If board_state contains invalid data
+      #
+      # @example Valid board state
+      #   { "e1" => "CHESS:K", "e2" => nil, "d1" => "CHESS:Q" }
+      #
+      # @example Invalid board states (would raise ArgumentError)
+      #   { 123 => "CHESS:K" }           # Invalid square label
+      #   { "e1" => "" }                 # Empty piece string
+      #   { "e1" => 456 }                # Non-string piece
       def validate_board_state_structure!(board_state)
         board_state.each do |square, piece|
           unless square.is_a?(::String) && !square.empty?
-            raise ::ArgumentError, "Invalid square label: #{square.inspect}"
+            raise ::ArgumentError, "Invalid square label: #{square.inspect}. Must be a non-empty String."
           end
 
           if piece && (!piece.is_a?(::String) || piece.empty?)
-            raise ::ArgumentError, "Invalid piece at #{square}: #{piece.inspect}"
+            raise ::ArgumentError, "Invalid piece at #{square}: #{piece.inspect}. Must be a String or nil."
+          end
+        end
+      end
+
+      # Validates that transitions don't duplicate implicit requirements in the require field.
+      #
+      # According to GGN specification, implicit requirements (like the source piece
+      # being present at the source square) should NOT be explicitly specified in
+      # the require field, as this creates redundancy and potential inconsistency.
+      #
+      # @raise [ValidationError] If any transition duplicates implicit requirements
+      #
+      # @example Invalid GGN that would be rejected
+      #   {
+      #     "CHESS:K": {
+      #       "e1": {
+      #         "e2": [{
+      #           "require": { "e1": "CHESS:K" },  # ❌ Redundant implicit requirement
+      #           "perform": { "e1": null, "e2": "CHESS:K" }
+      #         }]
+      #       }
+      #     }
+      #   }
+      def validate_no_implicit_requirement_duplications!
+        @data.each do |actor, source_data|
+          source_data.each do |origin, destination_data|
+            destination_data.each do |target, transition_list|
+              transition_list.each_with_index do |transition, index|
+                validate_single_transition_implicit_requirements!(
+                  transition, actor, origin, target, index
+                )
+              end
+            end
+          end
+        end
+      end
+
+      # Validates a single transition for implicit requirement duplication.
+      #
+      # @param transition [Hash] The transition rule to validate
+      # @param actor [String] GAN identifier of the piece
+      # @param origin [String] Source square
+      # @param target [String] Destination square
+      # @param index [Integer] Index of transition for error reporting
+      #
+      # @raise [ValidationError] If implicit requirements are duplicated
+      def validate_single_transition_implicit_requirements!(transition, actor, origin, target, index)
+        return unless transition.is_a?(::Hash) && transition["require"].is_a?(::Hash)
+
+        require_conditions = transition["require"]
+
+        # Check if the source square requirement is explicitly specified
+        if require_conditions.key?(origin) && require_conditions[origin] == actor
+          raise ValidationError,
+            "Implicit requirement duplication detected in #{actor} from #{origin} to #{target} " \
+            "(transition #{index}): 'require' field explicitly specifies that #{origin} contains #{actor}, " \
+            "but this is already implicit from the move structure. Remove this redundant requirement."
+        end
+      end
+
+      # Validates that transitions don't contain logical contradictions between require and prevent.
+      #
+      # A logical contradiction occurs when the same square is required to be in
+      # the same state in both require and prevent fields. This creates an impossible
+      # condition that can never be satisfied.
+      #
+      # @raise [ValidationError] If any transition contains logical contradictions
+      #
+      # @example Invalid GGN that would be rejected
+      #   {
+      #     "CHESS:B": {
+      #       "c1": {
+      #         "f4": [{
+      #           "require": { "d2": "empty" },
+      #           "prevent": { "d2": "empty" },  # ❌ Logical contradiction
+      #           "perform": { "c1": null, "f4": "CHESS:B" }
+      #         }]
+      #       }
+      #     }
+      #   }
+      def validate_no_logical_contradictions!
+        @data.each do |actor, source_data|
+          source_data.each do |origin, destination_data|
+            destination_data.each do |target, transition_list|
+              transition_list.each_with_index do |transition, index|
+                validate_single_transition_logical_consistency!(
+                  transition, actor, origin, target, index
+                )
+              end
+            end
+          end
+        end
+      end
+
+      # Validates a single transition for logical contradictions.
+      #
+      # @param transition [Hash] The transition rule to validate
+      # @param actor [String] GAN identifier of the piece
+      # @param origin [String] Source square
+      # @param target [String] Destination square
+      # @param index [Integer] Index of transition for error reporting
+      #
+      # @raise [ValidationError] If logical contradictions are found
+      def validate_single_transition_logical_consistency!(transition, actor, origin, target, index)
+        return unless transition.is_a?(::Hash)
+
+        require_conditions = transition["require"]
+        prevent_conditions = transition["prevent"]
+
+        # Skip if either field is missing or not a hash
+        return unless require_conditions.is_a?(::Hash) && prevent_conditions.is_a?(::Hash)
+
+        # Find squares that appear in both require and prevent
+        conflicting_squares = require_conditions.keys & prevent_conditions.keys
+
+        # Check each conflicting square for state contradictions
+        conflicting_squares.each do |square|
+          required_state = require_conditions[square]
+          prevented_state = prevent_conditions[square]
+
+          # Logical contradiction: same state required and prevented
+          if required_state == prevented_state
+            raise ValidationError,
+              "Logical contradiction detected in #{actor} from #{origin} to #{target} " \
+              "(transition #{index}): square #{square} cannot simultaneously " \
+              "require state '#{required_state}' and prevent state '#{prevented_state}'. " \
+              "This creates an impossible condition that can never be satisfied."
           end
         end
       end

data/lib/sashite/ggn.rb

@@ -23,10 +23,19 @@ module Sashite
   # - **Board-focused**: Describes only board transformations, no hand management
   # - **Pseudo-legal** focus: Describes basic movement constraints only
   # - **JSON-based**: Structured, machine-readable format
-  # - **Validation** support: Built-in schema validation
+  # - **Validation** support: Built-in schema validation and logical consistency checks
   # - **Performance** optimized: Optional validation for large datasets
   # - **Cross-game** compatible: Supports hybrid games and variants
   #
+  # = Validation Levels
+  #
+  # When `validate: true` (default), performs:
+  # - JSON Schema validation against GGN specification
+  # - Logical contradiction detection in require/prevent conditions
+  # - Implicit requirement duplication detection
+  #
+  # When `validate: false`, skips all validations for maximum performance.
+  #
   # = Related Specifications
   #
   # GGN works alongside other Sashité specifications:
@@ -46,16 +55,18 @@ module Sashite
       # 1. Reads the JSON file from the filesystem with proper encoding
       # 2. Parses the JSON content into a Ruby Hash with error handling
       # 3. Optionally validates the structure against the GGN JSON Schema
-      # 4. Creates and returns a Ruleset instance for querying moves
+      # 4. Optionally performs logical consistency validation
+      # 5. Creates and returns a Ruleset instance for querying moves
       #
       # @param filepath [String, Pathname] Path to the GGN JSON file to load.
       #   Supports both relative and absolute paths.
-      # @param validate [Boolean] Whether to validate against GGN schema (default: true).
-      #   Set to false to skip validation for improved performance on large documents.
+      # @param validate [Boolean] Whether to perform all validations (default: true).
+      #   When false, skips JSON schema validation AND internal logical validations
+      #   for maximum performance.
       # @param encoding [String] File encoding to use when reading (default: 'UTF-8').
       #   Most GGN files should use UTF-8 encoding.
       #
-      # @return [Ruleset] A Ruleset instance containing the parsed and validated GGN data.
+      # @return [Ruleset] A Ruleset instance containing the parsed GGN data.
       #   Use this instance to query pseudo-legal moves for specific pieces and positions.
       #
       # @raise [ValidationError] If any of the following conditions occur:
@@ -63,6 +74,7 @@ module Sashite
       #   - File contains invalid JSON syntax
       #   - File permissions prevent reading
       #   - When validation is enabled: data doesn't conform to GGN schema
+      #   - When validation is enabled: logical contradictions or implicit duplications found
       #
       # @example Loading a chess piece definition with full validation
       #   begin
@@ -89,7 +101,7 @@ module Sashite
       #
       # @example Loading large datasets without validation for performance
       #   begin
-      #     # Skip validation for large files to improve loading performance
+      #     # Skip all validations for large files to improve loading performance
       #     large_dataset = Sashite::Ggn.load_file('data/all_variants.json', validate: false)
       #     puts "Loaded GGN data without validation"
       #   rescue Sashite::Ggn::ValidationError => e
@@ -123,8 +135,8 @@ module Sashite
         # Validate against GGN schema if requested
         validate_schema(data, file_path) if validate
 
-        # Create and return Ruleset instance
-        Ruleset.new(data)
+        # Create and return Ruleset instance with validation option
+        Ruleset.new(data, validate: validate)
       end
 
       # Loads GGN data directly from a JSON string.
@@ -133,7 +145,8 @@ module Sashite
       # database, API response, or embedded in your application) rather than a file.
       #
       # @param json_string [String] JSON string containing GGN data
-      # @param validate [Boolean] Whether to validate against GGN schema (default: true)
+      # @param validate [Boolean] Whether to perform all validations (default: true).
+      #   When false, skips JSON schema validation AND internal logical validations.
       #
       # @return [Ruleset] A Ruleset instance containing the parsed GGN data
       #
@@ -164,8 +177,8 @@ module Sashite
         # Validate against GGN schema if requested
         validate_schema(data, "<string>") if validate
 
-        # Create and return Ruleset instance
-        Ruleset.new(data)
+        # Create and return Ruleset instance with validation option
+        Ruleset.new(data, validate: validate)
       end
 
       # Loads GGN data from a Ruby Hash.
@@ -174,7 +187,8 @@ module Sashite
       # and want to create a GGN Ruleset instance with optional validation.
       #
       # @param data [Hash] Ruby Hash containing GGN data structure
-      # @param validate [Boolean] Whether to validate against GGN schema (default: true)
+      # @param validate [Boolean] Whether to perform all validations (default: true).
+      #   When false, skips JSON schema validation AND internal logical validations.
       #
       # @return [Ruleset] A Ruleset instance containing the GGN data
       #
@@ -200,14 +214,16 @@ module Sashite
         # Validate against GGN schema if requested
         validate_schema(data, "<hash>") if validate
 
-        # Create and return Ruleset instance
-        Ruleset.new(data)
+        # Create and return Ruleset instance with validation option
+        Ruleset.new(data, validate: validate)
       end
 
       # Validates a data structure against the GGN JSON Schema.
       #
       # This method can be used independently to validate GGN data without
       # creating a Ruleset instance. Useful for pre-validation or testing.
+      # Note: This only performs JSON Schema validation, not the internal
+      # logical consistency checks that Ruleset.new performs.
       #
       # @param data [Hash] The data structure to validate
       # @param context [String] Context information for error messages (default: "<data>")
@@ -230,6 +246,9 @@ module Sashite
 
       # Checks if a data structure is valid GGN format.
       #
+      # Note: This only performs JSON Schema validation, not the internal
+      # logical consistency checks that Ruleset.new performs.
+      #
       # @param data [Hash] The data structure to validate
       #
       # @return [Boolean] true if valid, false otherwise
@@ -247,6 +266,9 @@ module Sashite
 
       # Returns detailed validation errors for a data structure.
       #
+      # Note: This only performs JSON Schema validation, not the internal
+      # logical consistency checks that Ruleset.new performs.
+      #
       # @param data [Hash] The data structure to validate
       #
       # @return [Array<String>] Array of validation error messages (empty if valid)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-ggn
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -27,8 +27,9 @@ description: A Ruby implementation of the General Gameplay Notation (GGN) specif
   GGN is a rule-agnostic, JSON-based format for describing pseudo-legal board-to-board
   transformations in abstract strategy board games. This library provides parsing,
   validation, and evaluation capabilities for GGN documents, focusing exclusively
-  on piece movements, captures, and transformations on the game board. Supports Chess,
-  Shogi, Xiangqi, and custom variants without hand management or piece drops.
+  on piece movements, captures, and transformations on the game board. Features flexible
+  validation system for both safety and performance. Supports Chess, Shogi, Xiangqi,
+  and custom variants without hand management or piece drops.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -56,6 +57,9 @@ metadata:
   source_code_uri: https://github.com/sashite/ggn.rb
   specification_uri: https://sashite.dev/documents/ggn/1.0.0/
   rubygems_mfa_required: 'true'
+  keywords: board-game, chess, game, gameplay, json, makruk, notation, performance,
+    pseudo-legal-move, rule-agnostic, serialization, shogi, strategy, validation,
+    xiangqi
 rdoc_options: []
 require_paths:
 - lib