sashite-pcn 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4f4d314fd4110d2ae43096e8b1763e69bfaf66bf141d20d8a85f9226fd6bf80
-  data.tar.gz: e4dc01512ae6e3a43a691205158cb375d8ed72e06a60bc1f0a71daf447534bf6
+  metadata.gz: eea8750505e46e5ec350db1cf84dd81d6d18a33fc8ec5da341864145b372eaf0
+  data.tar.gz: 7da291665e2546395a2e2de2333971aa0c5dbb48c583f29b96be2da4ceb245d6
 SHA512:
-  metadata.gz: 5ad2af5a5074be25e88d4173fdebf180e6dfb4213e3fb1f0b85d9cc7360976433cc3e7c36d2b248cd790ce35929c354bc6726601482881a38a5769a73c9fa010
-  data.tar.gz: 9df7d3ac32169ba3c2a3f4491b9f7870ff6ff0388005ee5e896af799d8a8d2d4f47a382c99287918356af683536a8f6e1d3aced38c0accb33ae37e2bc4898f66
+  metadata.gz: 4068049f9c08386d10ff597ca25b51c5e7056ad8e6ff0fef4c40a89058158ae74acb615a50095f389e32dc8c27469e5744eb29d3791fe2c19a46d3c45acd2065
+  data.tar.gz: 378368a1e8cfbcb3718c63aae21a65b69e03e49d46997ef14b8eec180ec64233e0dacfdfe31c19440711c01b73ce5e4056ee873a7b5787d89368be9cde6559d9

data/README.md

@@ -15,6 +15,7 @@
 - [API Documentation](#api-documentation)
 - [Format Specifications](#format-specifications)
 - [Time Control Examples](#time-control-examples)
+- [Draw Offers](#draw-offers)
 - [Error Handling](#error-handling)
 - [Complete Examples](#complete-examples)
 - [JSON Interoperability](#json-interoperability)
@@ -24,6 +25,7 @@
 PCN (Portable Chess Notation) is a comprehensive, JSON-based format for representing complete chess game records across variants. This Ruby implementation provides:
 
 - **Complete game records** with positions, moves, time tracking, and metadata
+- **Draw offer tracking** for recording draw proposals between players
 - **Time control support** for Fischer, Classical, Byōyomi, Canadian, and more
 - **Rule-agnostic design** supporting all abstract strategy board games
 - **Immutable objects** with functional transformations
@@ -80,11 +82,16 @@ game.status         # => CGSN status object
 # Transform immutably
 new_game = game.add_move(["g1-f3", 1.8])
 final_game = new_game.with_status("checkmate")
+
+# Handle draw offers
+game_with_offer = game.with_draw_offered_by("first")
+game.draw_offered?  # => true
+game.draw_offered_by # => "first"
 ```
 
 ## API Documentation
 
-For complete API documentation, see [API.md](https://github.com/sashite/pcn.rb/blob/v0.4.1/API.md).
+For complete API documentation, see [API Reference](https://rubydoc.info/github/sashite/pcn.rb/main/file/API.md).
 
 The API documentation includes:
 - All classes and methods
@@ -93,6 +100,7 @@ The API documentation includes:
 - Code examples for every method
 - Common usage patterns
 - Time control formats
+- Draw offer handling
 - Error handling
 
 ## Format Specifications
@@ -102,7 +110,7 @@ The API documentation includes:
 ```ruby
 # Standard chess starting position
 "+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"
-# └─ board ─────────────────────────────────────────────────────┘ └┘ └─┘
+# └─ board ──────────────────────────────────────────────┘ └┘ └─┘
 #                                                               turn styles
 
 # Empty board
@@ -150,8 +158,10 @@ The API documentation includes:
 # Explicit only (must be declared)
 "resignation"    # Player resigned
 "time_limit"     # Time expired
-"agreement"      # Mutual agreement
+"agreement"      # Mutual agreement (draw)
 "illegal_move"   # Invalid move played
+"repetition"     # Draw by repetition
+"move_limit"     # Move limit reached
 ```
 
 ### SNN (Styles)
@@ -232,6 +242,74 @@ periods: []      # Empty array
 periods: nil     # Or omit entirely
 ```
 
+## Draw Offers
+
+PCN supports tracking draw offers between players using the `draw_offered_by` field.
+
+### Basic Usage
+
+```ruby
+# Offer a draw
+game = game.with_draw_offered_by("first")  # First player offers
+
+# Check if draw offered
+game.draw_offered?       # => true
+game.draw_offered_by     # => "first"
+
+# Accept the draw
+game = game.with_status("agreement")
+
+# Decline/withdraw draw offer
+game = game.with_draw_offered_by(nil)
+```
+
+### Draw Offer Values
+
+```ruby
+nil        # No draw offer pending (default)
+"first"    # First player has offered a draw
+"second"   # Second player has offered a draw
+```
+
+### Example: Draw Offer During Game
+
+```ruby
+# Game in progress with draw offer
+game = Sashite::Pcn.parse({
+  "setup" => "+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",
+  "moves" => [
+    ["e2-e4", 8.0],
+    ["e7-e5", 12.0],
+    ["g1-f3", 15.0]
+  ],
+  "draw_offered_by" => "first",
+  "status" => "in_progress"
+})
+
+# First player has offered a draw after move 3
+puts "Draw offered by: #{game.draw_offered_by}"  # => "first"
+```
+
+### Example: Accepted Draw
+
+```ruby
+# Draw accepted
+game = Sashite::Pcn.parse({
+  "setup" => "+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",
+  "moves" => [
+    ["e2-e4", 15.0],
+    ["e7-e5", 18.0],
+    ["g1-f3", 22.0],
+    ["b8-c6", 12.0]
+  ],
+  "draw_offered_by" => "first",
+  "status" => "agreement"
+})
+
+# First player offered, second player accepted
+puts "Game result: Draw by agreement"
+```
+
 ## Error Handling
 
 ```ruby
@@ -256,6 +334,16 @@ rescue ArgumentError => e
   puts e.message  # => "Each move must be [PAN string, seconds float] tuple"
 end
 
+# Draw offer validation
+begin
+  Sashite::Pcn::Game.new(
+    setup: "8/8/8/8/8/8/8/8 / U/u",
+    draw_offered_by: "third"  # Invalid: must be nil, "first", or "second"
+  )
+rescue ArgumentError => e
+  puts e.message  # => "draw_offered_by must be nil, 'first', or 'second'"
+end
+
 # Metadata validation
 begin
   Sashite::Pcn::Game.new(
@@ -275,6 +363,7 @@ begin
       ]
     }
   }
+  Sashite::Pcn::Game.new(setup: "8/8/8/8/8/8/8/8 / U/u", sides: sides)
 rescue ArgumentError => e
   puts e.message  # => "time must be a non-negative integer (>= 0)"
 end
@@ -353,14 +442,58 @@ puts "Moves played: #{game.move_count}"
 puts "White time: #{game.first_player_time}s"
 puts "Black time: #{game.second_player_time}s"
 
+# Offer a draw
+game = game.with_draw_offered_by("first")
+
 # Finish game
 if some_condition
   game = game.with_status("checkmate")
-elsif another_condition
+elsif draw_accepted?
+  game = game.with_status("agreement")
+else
   game = game.with_status("resignation")
 end
 ```
 
+### Game with Draw Offer
+
+```ruby
+# Complete game with draw offer and acceptance
+game = Sashite::Pcn::Game.new(
+  meta: {
+    event: "Club Match",
+    round: 5,
+    started_at: "2025-01-27T14:00:00Z"
+  },
+  sides: {
+    first: {
+      name: "Player A",
+      elo: 2200,
+      style: "CHESS"
+    },
+    second: {
+      name: "Player B",
+      elo: 2190,
+      style: "chess"
+    }
+  },
+  setup: "+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",
+  moves: [
+    ["e2-e4", 15.0],
+    ["e7-e5", 18.0],
+    ["g1-f3", 22.0],
+    ["b8-c6", 12.0],
+    ["d2-d4", 31.0],
+    ["e5+d4", 25.0]
+  ],
+  draw_offered_by: "first",
+  status: "agreement"
+)
+
+puts "Result: Draw by agreement"
+puts "Initiated by: #{game.draw_offered_by}"
+```
+
 ### Complex Tournament Game
 
 ```ruby
@@ -437,7 +570,41 @@ puts "Winner: #{game.status == 'resignation' ? 'First player (White)' : 'Unknown
 puts "Total moves: #{game.move_count}"
 
 # Export to JSON file
-File.write("game.json", JSON.generate(game.to_h))
+File.write("game.json", JSON.pretty_generate(game.to_h))
+```
+
+### Draw Offer Scenario
+
+```ruby
+# Game progressing with draw offer
+game = Sashite::Pcn::Game.new(
+  setup: "+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"
+)
+
+# Play several moves
+game = game.add_move(["e2-e4", 8.0])
+game = game.add_move(["e7-e5", 12.0])
+game = game.add_move(["g1-f3", 15.0])
+game = game.add_move(["b8-c6", 5.0])
+
+# First player offers a draw
+game = game.with_draw_offered_by("first")
+
+# Check the offer
+if game.draw_offered?
+  puts "Draw offered by: #{game.draw_offered_by}"
+
+  # Second player can accept
+  if player_accepts_draw?
+    game = game.with_status("agreement")
+    puts "Draw accepted!"
+  else
+    # Or decline and continue
+    game = game.with_draw_offered_by(nil)
+    game = game.add_move(["f1-c4", 9.0])
+    puts "Draw declined, game continues"
+  end
+end
 ```
 
 ## JSON Interoperability
@@ -511,6 +678,7 @@ record.save!
 record = GameRecord.find(id)
 game = record.game
 puts game.move_count
+puts "Draw offered: #{game.draw_offered?}"
 ```
 
 ## Properties
@@ -520,13 +688,14 @@ puts game.move_count
 - **Type-safe**: Strong type checking throughout
 - **Rule-agnostic**: Independent of specific game rules
 - **JSON-native**: Direct serialization to/from JSON
-- **Comprehensive**: Complete game information including time tracking
+- **Comprehensive**: Complete game information including time tracking and draw offers
 - **Extensible**: Custom metadata and player fields supported
 
 ## Documentation
 
 - [Official PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/)
 - [PCN Examples](https://sashite.dev/specs/pcn/1.0.0/examples/)
+- [Draw Offer Examples](https://sashite.dev/specs/pcn/1.0.0/examples/draw-offers/)
 - [API Documentation](https://rubydoc.info/github/sashite/pcn.rb/main)
 - [PAN Specification](https://sashite.dev/specs/pan/) (moves)
 - [FEEN Specification](https://sashite.dev/specs/feen/) (positions)

data/lib/sashite/pcn/game.rb

@@ -13,8 +13,9 @@ module Sashite
     # Represents a complete game record in PCN (Portable Chess Notation) format.
     #
     # A game consists of an initial position (setup), optional move sequence with time tracking,
-    # optional game status, optional metadata, and optional player information with time control.
-    # All instances are immutable - transformations return new instances.
+    # optional game status, optional draw offer tracking, optional winner declaration, optional
+    # metadata, and optional player information with time control. All instances are immutable -
+    # transformations return new instances.
     #
     # All parameters are validated at initialization time. An instance of Game
     # cannot be created with invalid data.
@@ -55,6 +56,22 @@ module Sashite
     #     ],
     #     status: "in_progress"
     #   )
+    #
+    # @example Game with draw offer
+    #   game = Game.new(
+    #     setup: "+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",
+    #     moves: [["e2-e4", 8.0], ["e7-e5", 12.0]],
+    #     draw_offered_by: "first",
+    #     status: "in_progress"
+    #   )
+    #
+    # @example Game with winner
+    #   game = Game.new(
+    #     setup: "+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",
+    #     moves: [["e2-e4", 8.0], ["e7-e5", 12.0]],
+    #     status: "resignation",
+    #     winner: "first"
+    #   )
     class Game
       # Error messages
       ERROR_MISSING_SETUP = "setup is required"
@@ -64,19 +81,29 @@ module Sashite
       ERROR_INVALID_SECONDS = "seconds must be a non-negative number"
       ERROR_INVALID_META = "meta must be a hash"
       ERROR_INVALID_SIDES = "sides must be a hash"
+      ERROR_INVALID_DRAW_OFFERED_BY = "draw_offered_by must be nil, 'first', or 'second'"
+      ERROR_INVALID_WINNER = "winner must be nil, 'first', 'second', or 'none'"
 
       # Status constants
       STATUS_IN_PROGRESS = "in_progress"
 
+      # Valid draw_offered_by values
+      VALID_DRAW_OFFERED_BY = [nil, "first", "second"].freeze
+
+      # Valid winner values
+      VALID_WINNER = [nil, "first", "second", "none"].freeze
+
       # Create a new game instance
       #
       # @param setup [String] initial position in FEEN format (required)
       # @param moves [Array<Array>] sequence of [PAN, seconds] tuples (optional, defaults to [])
       # @param status [String, nil] game status in CGSN format (optional)
+      # @param draw_offered_by [String, nil] draw offer indicator: nil, "first", or "second" (optional)
+      # @param winner [String, nil] competitive outcome: nil, "first", "second", or "none" (optional)
       # @param meta [Hash] game metadata (optional)
       # @param sides [Hash] player information with time control (optional)
       # @raise [ArgumentError] if required fields are missing or invalid
-      def initialize(setup:, moves: [], status: nil, meta: {}, sides: {})
+      def initialize(setup:, moves: [], status: nil, draw_offered_by: nil, winner: nil, meta: {}, sides: {})
         # Validate and parse setup (required)
         raise ::ArgumentError, ERROR_MISSING_SETUP if setup.nil?
         @setup = ::Sashite::Feen.parse(setup)
@@ -88,6 +115,14 @@ module Sashite
         # Validate and parse status (optional)
         @status = status.nil? ? nil : ::Sashite::Cgsn.parse(status)
 
+        # Validate draw_offered_by (optional)
+        validate_draw_offered_by(draw_offered_by)
+        @draw_offered_by = draw_offered_by
+
+        # Validate winner (optional)
+        validate_winner(winner)
+        @winner = winner
+
         # Validate meta (optional)
         raise ::ArgumentError, ERROR_INVALID_META unless meta.is_a?(::Hash)
         @meta = Meta.new(**meta.transform_keys(&:to_sym))
@@ -153,6 +188,30 @@ module Sashite
         @status
       end
 
+      # Get draw offer indicator
+      #
+      # @return [String, nil] "first", "second", or nil
+      #
+      # @example
+      #   game.draw_offered_by  # => "first"
+      #   game.draw_offered_by  # => nil
+      def draw_offered_by
+        @draw_offered_by
+      end
+
+      # Get competitive outcome
+      #
+      # @return [String, nil] "first", "second", "none", or nil
+      #
+      # @example
+      #   game.winner  # => "first"
+      #   game.winner  # => "second"
+      #   game.winner  # => "none"
+      #   game.winner  # => nil
+      def winner
+        @winner
+      end
+
       # ========================================================================
       # Player Access
       # ========================================================================
@@ -221,101 +280,113 @@ module Sashite
           setup: @setup.to_s,
           moves: new_moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
+          winner: @winner,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
       end
 
-      # Get the PAN notation from a move
+      # Get PAN notation at specified index
       #
-      # @param index [Integer] move index
+      # @param index [Integer] move index (0-based)
       # @return [String, nil] PAN notation or nil if out of bounds
       #
       # @example
       #   game.pan_at(0)  # => "e2-e4"
       def pan_at(index)
         move = @moves[index]
-        move ? move[0] : nil
+        move&.first
       end
 
-      # Get the seconds spent on a move
+      # Get seconds at specified index
       #
-      # @param index [Integer] move index
+      # @param index [Integer] move index (0-based)
       # @return [Float, nil] seconds or nil if out of bounds
       #
       # @example
       #   game.seconds_at(0)  # => 2.5
       def seconds_at(index)
         move = @moves[index]
-        move ? move[1] : nil
+        move&.last
       end
 
-      # Get total time spent by first player
+      # Calculate total time spent by first player
       #
-      # @return [Float] sum of seconds for moves at even indices
+      # @return [Float] sum of seconds at even indices
       #
       # @example
-      #   game.first_player_time  # => 125.3
+      #   game.first_player_time  # => 125.7
       def first_player_time
-        @moves.each_with_index
-              .select { |_, i| i.even? }
-              .sum { |move, _| move[1] }
+        @moves.each_with_index.sum do |move, index|
+          index.even? ? move.last : 0.0
+        end
       end
 
-      # Get total time spent by second player
+      # Calculate total time spent by second player
       #
-      # @return [Float] sum of seconds for moves at odd indices
+      # @return [Float] sum of seconds at odd indices
       #
       # @example
-      #   game.second_player_time  # => 132.7
+      #   game.second_player_time  # => 132.3
       def second_player_time
-        @moves.each_with_index
-              .select { |_, i| i.odd? }
-              .sum { |move, _| move[1] }
+        @moves.each_with_index.sum do |move, index|
+          index.odd? ? move.last : 0.0
+        end
       end
 
       # ========================================================================
       # Metadata Shortcuts
       # ========================================================================
 
-      # Get game start timestamp
+      # Get event from metadata
       #
-      # @return [String, nil] start timestamp in ISO 8601 format
+      # @return [String, nil] event name or nil
       #
       # @example
-      #   game.started_at  # => "2025-01-27T14:00:00Z"
-      def started_at
-        @meta[:started_at]
+      #   game.event  # => "World Championship"
+      def event
+        @meta[:event]
       end
 
-      # Get event name
+      # Get round from metadata
       #
-      # @return [String, nil] event name
+      # @return [Integer, nil] round number or nil
       #
       # @example
-      #   game.event  # => "World Championship"
-      def event
-        @meta[:event]
+      #   game.round  # => 5
+      def round
+        @meta[:round]
       end
 
-      # Get event location
+      # Get location from metadata
       #
-      # @return [String, nil] location
+      # @return [String, nil] location or nil
       #
       # @example
-      #   game.location  # => "London"
+      #   game.location  # => "Dubai, UAE"
       def location
         @meta[:location]
       end
 
-      # Get round number
+      # Get started_at from metadata
       #
-      # @return [Integer, nil] round number
+      # @return [String, nil] ISO 8601 datetime or nil
       #
       # @example
-      #   game.round  # => 5
-      def round
-        @meta[:round]
+      #   game.started_at  # => "2025-01-27T14:00:00Z"
+      def started_at
+        @meta[:started_at]
+      end
+
+      # Get href from metadata
+      #
+      # @return [String, nil] URL or nil
+      #
+      # @example
+      #   game.href  # => "https://example.com/game/123"
+      def href
+        @meta[:href]
       end
 
       # ========================================================================
@@ -326,6 +397,7 @@ module Sashite
       #
       # @param new_status [String, nil] new status value
       # @return [Game] new game instance with updated status
+      # @raise [ArgumentError] if status is invalid
       #
       # @example
       #   updated = game.with_status("resignation")
@@ -334,6 +406,62 @@ module Sashite
           setup: @setup.to_s,
           moves: @moves,
           status: new_status,
+          draw_offered_by: @draw_offered_by,
+          winner: @winner,
+          meta: @meta.to_h,
+          sides: @sides.to_h
+        )
+      end
+
+      # Create new game with updated draw offer
+      #
+      # @param player [String, nil] "first", "second", or nil
+      # @return [Game] new game instance with updated draw offer
+      # @raise [ArgumentError] if player is invalid
+      #
+      # @example
+      #   # First player offers a draw
+      #   game_with_offer = game.with_draw_offered_by("first")
+      #
+      #   # Withdraw draw offer
+      #   game_no_offer = game.with_draw_offered_by(nil)
+      def with_draw_offered_by(player)
+        self.class.new(
+          setup: @setup.to_s,
+          moves: @moves,
+          status: @status&.to_s,
+          draw_offered_by: player,
+          winner: @winner,
+          meta: @meta.to_h,
+          sides: @sides.to_h
+        )
+      end
+
+      # Create new game with updated winner
+      #
+      # @param new_winner [String, nil] "first", "second", "none", or nil
+      # @return [Game] new game instance with updated winner
+      # @raise [ArgumentError] if winner is invalid
+      #
+      # @example
+      #   # First player wins
+      #   game_first_wins = game.with_winner("first")
+      #
+      #   # Second player wins
+      #   game_second_wins = game.with_winner("second")
+      #
+      #   # Draw (no winner)
+      #   game_draw = game.with_winner("none")
+      #
+      #   # Clear winner
+      #   game_in_progress = game.with_winner(nil)
+      def with_winner(new_winner)
+        self.class.new(
+          setup: @setup.to_s,
+          moves: @moves,
+          status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
+          winner: new_winner,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
@@ -352,6 +480,8 @@ module Sashite
           setup: @setup.to_s,
           moves: @moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
+          winner: @winner,
           meta: merged_meta,
           sides: @sides.to_h
         )
@@ -370,6 +500,8 @@ module Sashite
           setup: @setup.to_s,
           moves: new_moves,
           status: @status&.to_s,
+          draw_offered_by: @draw_offered_by,
+          winner: @winner,
           meta: @meta.to_h,
           sides: @sides.to_h
         )
@@ -403,6 +535,53 @@ module Sashite
         !in_progress?
       end
 
+      # Check if a draw offer is pending
+      #
+      # @return [Boolean] true if a draw offer is pending
+      #
+      # @example
+      #   game.draw_offered?  # => true (if draw_offered_by is "first" or "second")
+      #   game.draw_offered?  # => false (if draw_offered_by is nil)
+      def draw_offered?
+        !@draw_offered_by.nil?
+      end
+
+      # Check if a winner has been determined
+      #
+      # @return [Boolean] true if winner is determined (first, second, or none)
+      #
+      # @example
+      #   game.has_winner?  # => true (if winner is "first", "second", or "none")
+      #   game.has_winner?  # => false (if winner is nil)
+      def has_winner?
+        !@winner.nil?
+      end
+
+      # Check if the game had a decisive outcome (not a draw)
+      #
+      # @return [Boolean, nil] true if decisive (first or second won), false if draw, nil if no winner
+      #
+      # @example
+      #   game.decisive?  # => true (if winner is "first" or "second")
+      #   game.decisive?  # => false (if winner is "none")
+      #   game.decisive?  # => nil (if winner is nil)
+      def decisive?
+        return nil if @winner.nil?
+
+        @winner != "none"
+      end
+
+      # Check if the game ended in a draw
+      #
+      # @return [Boolean] true if winner is "none" (draw)
+      #
+      # @example
+      #   game.drawn?  # => true (if winner is "none")
+      #   game.drawn?  # => false (if winner is nil, "first", or "second")
+      def drawn?
+        @winner == "none"
+      end
+
       # ========================================================================
       # Serialization
       # ========================================================================
@@ -417,6 +596,8 @@ module Sashite
       #   #   "setup" => "...",
       #   #   "moves" => [["e2-e4", 2.5], ["e7-e5", 3.1]],
       #   #   "status" => "in_progress",
+      #   #   "draw_offered_by" => "first",
+      #   #   "winner" => nil,
       #   #   "meta" => {...},
       #   #   "sides" => {...}
       #   # }
@@ -428,12 +609,62 @@ module Sashite
 
         # Include optional fields if present
         result["status"] = @status.to_s if @status
+        result["draw_offered_by"] = @draw_offered_by if @draw_offered_by
+        result["winner"] = @winner if @winner
         result["meta"] = @meta.to_h unless @meta.empty?
         result["sides"] = @sides.to_h unless @sides.empty?
 
         result
       end
 
+      # Compare with another game
+      #
+      # @param other [Object] object to compare
+      # @return [Boolean] true if equal
+      #
+      # @example
+      #   game1 == game2  # => true if all attributes match
+      def ==(other)
+        return false unless other.is_a?(Game)
+
+        @setup.to_s == other.setup.to_s &&
+          @moves == other.moves &&
+          @status&.to_s == other.status&.to_s &&
+          @draw_offered_by == other.draw_offered_by &&
+          @winner == other.winner &&
+          @meta == other.meta &&
+          @sides == other.sides
+      end
+
+      # Generate hash code
+      #
+      # @return [Integer] hash code for this game
+      #
+      # @example
+      #   game.hash  # => 123456789
+      def hash
+        [@setup.to_s, @moves, @status&.to_s, @draw_offered_by, @winner, @meta, @sides].hash
+      end
+
+      # Generate debug representation
+      #
+      # @return [String] debug string
+      #
+      # @example
+      #   game.inspect
+      #   # => "#<Game setup=\"...\" moves=[...] status=\"in_progress\" draw_offered_by=\"first\" winner=nil>"
+      def inspect
+        parts = ["setup=#{@setup.to_s.inspect}"]
+        parts << "moves=#{@moves.inspect}"
+        parts << "status=#{@status&.to_s.inspect}" if @status
+        parts << "draw_offered_by=#{@draw_offered_by.inspect}" if @draw_offered_by
+        parts << "winner=#{@winner.inspect}" if @winner
+        parts << "meta=#{@meta.inspect}" unless @meta.empty?
+        parts << "sides=#{@sides.inspect}" unless @sides.empty?
+
+        "#<#{self.class.name} #{parts.join(' ')}>"
+      end
+
       private
 
       # Validate and parse moves array
@@ -478,6 +709,26 @@ module Sashite
         # Return the move tuple with seconds as float
         [pan_notation, seconds.to_f].freeze
       end
+
+      # Validate draw_offered_by field
+      #
+      # @param value [String, nil] draw offer value to validate
+      # @raise [ArgumentError] if value is invalid
+      def validate_draw_offered_by(value)
+        return if VALID_DRAW_OFFERED_BY.include?(value)
+
+        raise ::ArgumentError, ERROR_INVALID_DRAW_OFFERED_BY
+      end
+
+      # Validate winner field
+      #
+      # @param value [String, nil] winner value to validate
+      # @raise [ArgumentError] if value is invalid
+      def validate_winner(value)
+        return if VALID_WINNER.include?(value)
+
+        raise ::ArgumentError, ERROR_INVALID_WINNER
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pcn
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -113,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: PCN (Portable Chess Notation) implementation for Ruby with comprehensive
   game record representation