qi 11.0.0 → 12.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37ba6c52ebee303a717aa6e218cc7e4c1167658988b883692dbee1691c72df6f
-  data.tar.gz: a63f9d02091f7d379d2fa5d7d7dedbaff1df7eb9505f20bd50dcf228f8b6c319
+  metadata.gz: c916e1be3a5a9e6c40fe3fad735488b69a4663607d55f80989a8daf023fd84b5
+  data.tar.gz: d4ba55868fa1dbfce8cf9d46dde4ed3be9d839cf59320c7f9f90ee9973c60393
 SHA512:
-  metadata.gz: 347722567e95439f0cb818cf929931315fdc081a72b9f50738aace03981e023c094b46b6010163e766e2f4b67476bc78b6a5718656c3b1c61c1aa31525838744
-  data.tar.gz: 4659c8825b38423cbfa539eb0c215b1503f997ce0d0fd972c3ee55cbe71719a6d61d65badb89866ae46cf87b935c4c1d05d4bb95f5f00b6614483548fe2b95cd
+  metadata.gz: a0bd0d10e698c1f80c2cd6d501bb5d5be865f9b4e53de224be4fb4b7b84a0cf1d6ee22428c1c01c5f0904a867923f294bc2beba21701d729d294e39e4323d504
+  data.tar.gz: df8c064144e6194743d3a9bf86f78d958c748d3e6ce8bbdeb792768a3852ce1ba15b3bababb2ce948b7cc8e12be91563b8cfd1e6dfcc5c4b5302bfc0c15777e9

data/README.md

@@ -1,41 +1,62 @@
-# Qi
+# qi.rb
 
 [![Version](https://img.shields.io/gem/v/qi.svg)](https://rubygems.org/gems/qi)
 [![Documentation](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/qi)
 [![CI](https://github.com/sashite/qi.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions)
-[![License](https://img.shields.io/gem/l/qi.svg)](https://github.com/sashite/qi.rb/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/sashite/qi.rb/blob/main/LICENSE)
 
-> A minimal, format-agnostic position model for two-player board games.
+> An immutable, format-agnostic position model for two-player board games.
 
-## Overview
+## Quick Start
 
-`Qi` provides an immutable `Qi::Position` object that represents the state of a two-player, turn-based board game as defined by the [Sashité Game Protocol](https://sashite.dev/game-protocol/).
+```ruby
+gem "qi", "~> 12.0"
+```
 
-A position encodes exactly four things:
+```ruby
+require "qi"
 
-| Field    | Type                                        | Description                           |
-|----------|---------------------------------------------|---------------------------------------|
-| `board`  | nested `Array` (1D to 3D)                   | Board structure and occupancy         |
-| `hands`  | `Hash` with `:first` and `:second` keys     | Off-board pieces held by each player  |
-| `styles` | `Hash` with `:first` and `:second` keys     | Player style for each side            |
-| `turn`   | `:first` or `:second`                       | The active player's side              |
+# Create an empty 8×8 board with player styles
+pos = Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
 
-Piece and style representations are **intentionally opaque** — `Qi` validates structure, not semantics. This makes the library reusable across [FEEN](https://sashite.dev/specs/feen/1.0.0/), [PON](https://sashite.dev/specs/pon/1.0.0/), or any other encoding that shares the same positional model.
+# Place pieces and switch turn
+pos2 = pos
+  .board_diff(0 => "r", 1 => "n", 2 => "b", 3 => "q", 4 => "k")
+  .board_diff(60 => "K", 59 => "Q", 58 => "B", 57 => "N", 56 => "R")
+  .toggle
 
-### Implementation Constraints
+pos2.turn  #=> :second
+```
+
+Every transformation returns a **new frozen instance**. The original is never modified.
 
-| Constraint         | Value | Rationale                                 |
-|--------------------|-------|-------------------------------------------|
-| Max dimensions     | 3     | Covers 1D, 2D, 3D boards                 |
-| Max dimension size | 255   | Fits in 8-bit integer; covers 255×255×255 |
-| Board non-empty    | n ≥ 1 | A board must contain at least one square  |
-| Piece cardinality  | p ≤ n | Pieces cannot exceed the number of squares|
+## Overview
+
+`Qi` models a board game position as defined by the [Sashité Game Protocol](https://sashite.dev/game-protocol/). A position encodes exactly four things:
+
+| Component | Accessors | Description |
+|-----------|-----------|-------------|
+| Board | `board` | Multi-dimensional grid (1D, 2D, or 3D) of squares |
+| Hands | `first_player_hand`, `second_player_hand` | Off-board pieces held by each player |
+| Styles | `first_player_style`, `second_player_style` | One style String per player side |
+| Turn | `turn` | The active player (`:first` or `:second`) |
+
+**Pieces and styles are Strings.** Every piece — whether on the board or in a hand — and every style value is stored as a `String`. This aligns naturally with the notation formats in the Sashité ecosystem ([FEEN](https://sashite.dev/specs/feen/1.0.0/), [EPIN](https://sashite.dev/specs/epin/1.0.0/), [PON](https://sashite.dev/specs/pon/1.0.0/), [SIN](https://sashite.dev/specs/sin/1.0.0/)), which all produce string representations. Empty squares are represented by `nil`.
+
+**String normalization.** All inputs (pieces and styles) are normalized to `String` via interpolation (`"#{value}"`). This guarantees internal consistency without relying on type checks, and accepts any value that responds to `to_s`.
+
+```ruby
+pos.board_diff(0 => "K")               # String — stored as "K"
+pos.board_diff(0 => :K)                # Symbol — normalized to "K"
+pos.board_diff(0 => "C:K")             # Namespaced — stored as "C:K"
+pos.board_diff(0 => "+P")              # Promoted — stored as "+P"
+```
 
 ## Installation
 
 ```ruby
 # In your Gemfile
-gem "qi", "~> 11.0"
+gem "qi", "~> 12.0"
 ```
 
 Or install manually:
@@ -44,144 +65,297 @@ Or install manually:
 gem install qi
 ```
 
-## Dependencies
+### Requirements
+
+`Qi` requires **Ruby 3.2+** (tested against 3.2, 3.3, 3.4, and 4.0) and has **zero runtime dependencies**.
+
+## API Reference
+
+### Construction
+
+#### `Qi.new(*shape, first_player_style:, second_player_style:)` → `Qi`
+
+Creates an immutable position with an empty board.
 
-None. `Qi` is a zero-dependency library.
+**Parameters:**
 
-## Usage
+- `*shape` — one to three `Integer` dimension sizes (each 1–255).
+- `first_player_style:` — style for the first player (any non-nil value, normalized to `String`).
+- `second_player_style:` — style for the second player (any non-nil value, normalized to `String`).
 
-### Creating a Position
+The board starts with all squares empty (`nil`), both hands start empty, and the turn defaults to `:first`. Styles are normalized to `String` and frozen at construction.
 
 ```ruby
-# Chess starting position
-board = [
-  [:r, :n, :b, :q, :k, :b, :n, :r],
-  [:p, :p, :p, :p, :p, :p, :p, :p],
-  [nil, nil, nil, nil, nil, nil, nil, nil],
-  [nil, nil, nil, nil, nil, nil, nil, nil],
-  [nil, nil, nil, nil, nil, nil, nil, nil],
-  [nil, nil, nil, nil, nil, nil, nil, nil],
-  [:P, :P, :P, :P, :P, :P, :P, :P],
-  [:R, :N, :B, :Q, :K, :B, :N, :R]
-]
-
-position = Qi.new(
-  board,
-  { first: [], second: [] },
-  { first: "C", second: "c" },
-  :first
-)
-```
-
-### Accessing Fields
+Qi.new(8, 8, first_player_style: "C", second_player_style: "c")   # 2D (8×8)
+Qi.new(8, first_player_style: "G", second_player_style: "g")      # 1D
+Qi.new(5, 5, 5, first_player_style: "R", second_player_style: "r") # 3D
+```
+
+**Raises** `ArgumentError` if shape constraints are violated or if a style is `nil` (see [Validation Errors](#validation-errors)).
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `Qi::MAX_DIMENSIONS` | `3` | Maximum number of board dimensions |
+| `Qi::MAX_DIMENSION_SIZE` | `255` | Maximum size of any single dimension |
+
+### Accessors
+
+All accessors are safe to call from any thread. Collections return independent copies; styles and turn return immutable values.
+
+| Method | Returns | Copy behavior |
+|--------|---------|---------------|
+| `board` | `Array` | Nested array (independent copy). Each leaf is `nil` or `String`. |
+| `first_player_hand` | `Array<String>` | Independent copy. |
+| `second_player_hand` | `Array<String>` | Independent copy. |
+| `turn` | `Symbol` | `:first` or `:second` (immutable). |
+| `first_player_style` | `String` | Frozen value (returned directly, no allocation). |
+| `second_player_style` | `String` | Frozen value (returned directly, no allocation). |
+| `shape` | `Array<Integer>` | Independent copy (e.g., `[8, 8]`). |
+| `inspect` | `String` | Developer-friendly, unstable format. Do not parse. |
 
 ```ruby
-position.board   #=> [[:r, :n, :b, ...], ...]
-position.hands   #=> { first: [], second: [] }
-position.styles  #=> { first: "C", second: "c" }
-position.turn    #=> :first
+pos.board                #=> [["r", "n", "b", ...], ...]
+pos.first_player_hand    #=> []
+pos.second_player_hand   #=> []
+pos.turn                 #=> :first
+pos.first_player_style   #=> "C"
+pos.second_player_style  #=> "c"
+pos.shape                #=> [8, 8]
+pos.inspect              #=> "#<Qi shape=[8, 8] turn=:first>"
 ```
 
-All accessors return **frozen** objects. A `Qi::Position` is immutable once created.
+**Note:** Styles are frozen Strings. Attempting to mutate a returned style raises `FrozenError`. If you need a mutable copy, call `.dup` on the returned value.
+
+### Transformations
+
+All transformation methods return a **new frozen `Qi` instance**. The original is never modified.
+
+#### `board_diff(**squares)` → `Qi`
 
-### Error Handling
+Returns a new position with modified squares.
 
-`Qi.new` raises `ArgumentError` on invalid input:
+Keys are flat indices (`Integer`, 0-based, row-major order). Values are pieces (normalized to `String`) or `nil` (empty square).
 
 ```ruby
-begin
-  Qi.new([], { first: [], second: [] }, { first: "C", second: "c" }, :first)
-rescue ArgumentError => e
-  e.message #=> "board must not be empty"
-end
+pos2 = pos.board_diff(12 => nil, 28 => "P")
 ```
 
-### Pieces as Arbitrary Objects
+**Raises** `ArgumentError` if an index is out of range or if the resulting total piece count exceeds the board size.
+
+See [Flat Indexing](#flat-indexing) for computing flat indices from coordinates.
+
+#### `first_player_hand_diff(**pieces)` → `Qi`
+#### `second_player_hand_diff(**pieces)` → `Qi`
+
+Returns a new position with a modified hand.
 
-Pieces are not restricted to any specific type. You can use symbols, strings (EPIN tokens), arrays, or any non-nil Ruby object:
+Keys are piece identifiers (normalized to `String`); values are integer deltas (positive to add, negative to remove, zero is a no-op). Removal uses **value equality** (`==`).
 
 ```ruby
-# Symbols
-Qi.new([:k, :p, nil, :P, :K], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+pos2 = pos.first_player_hand_diff("P": 1)           # Add one "P"
+pos3 = pos.first_player_hand_diff("B": -1, "P": 1)  # Remove one "B", add one "P"
+pos4 = pos.second_player_hand_diff("p": 1)           # Add one "p" to second hand
+```
+
+**String normalization:** Ruby keyword arguments produce Symbol keys. The hand diff methods normalize these to Strings internally (`"P": 1` becomes key `:P`, stored as `"P"`). This is transparent in normal usage — the example above stores `"P"`, `"B"`, and `"p"` as Strings in the hand.
+
+**Raises** `ArgumentError` if a delta is not an `Integer`, if removing a piece not present, or if the resulting total piece count exceeds the board size.
 
-# EPIN strings
-Qi.new([["K^", nil], [nil, "k^"]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+#### `toggle` → `Qi`
 
-# Arrays as structured piece representations
-Qi.new(
-  [[[:king, :first, true], nil], [nil, [:king, :second, true]]],
-  { first: [], second: [] },
-  { first: :chess, second: :chess },
-  :first
-)
+Returns a new position with the active player swapped. All other fields are preserved.
+
+```ruby
+pos.turn           #=> :first
+pos.toggle.turn    #=> :second
 ```
 
-### Multi-dimensional Boards
+#### Chaining
+
+Transformations compose naturally. A typical move involves modifying the board, optionally updating a hand, and toggling the turn:
 
 ```ruby
-# 1D board
-Qi.new([:a, nil, :b], { first: [], second: [] }, { first: "G", second: "g" }, :first)
+# Simple move: slide a piece from index 12 to index 28
+pos2 = pos
+  .board_diff(12 => nil, 28 => "P")
+  .toggle
+
+# Capture: overwrite defender, add captured piece to hand, toggle
+pos3 = pos
+  .board_diff(12 => nil, 28 => "P")        # Attacker replaces defender
+  .first_player_hand_diff("p": 1)          # Captured piece goes to hand
+  .toggle
+```
+
+The Protocol does not prescribe how captures are modeled. In the example above, `board_diff(12 => nil, 28 => "P")` simultaneously vacates the source and overwrites the destination. The captured piece must be added to the hand separately — `board_diff` does not track what was previously on a square.
+
+## Board Structure
+
+### Shape and Dimensionality
+
+The nesting depth of the array returned by `board` matches the number of dimensions:
+
+| Dimensionality | Constructor | `board` returns |
+|----------------|-------------|-----------------|
+| 1D | `Qi.new(8, ...)` | `[square, square, ...]` |
+| 2D | `Qi.new(8, 8, ...)` | `[[square, ...], [square, ...], ...]` |
+| 3D | `Qi.new(5, 5, 5, ...)` | `[[[square, ...], ...], ...]` |
 
-# 2D board (standard)
-Qi.new([[nil, nil], [nil, nil]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+Each `square` is either `nil` (empty) or a `String` (a piece).
 
-# 3D board (2 layers × 2 ranks × 2 files)
-board_3d = [
-  [[:a, :b], [:c, :d]],
-  [[:A, :B], [:C, :D]]
-]
-Qi.new(board_3d, { first: [], second: [] }, { first: "R", second: "r" }, :first)
+For a shape `[D1, D2, ..., DN]`, the total number of squares is `D1 × D2 × ... × DN`.
+
+### Flat Indexing
+
+`board_diff` addresses squares by **flat index** — a single integer in **row-major order** (C order).
+
+**1D board** with shape `[F]`:
+
+```
+flat_index = f
 ```
 
-### Hands with Captured Pieces
+**2D board** with shape `[R, F]` (R ranks, F files):
+
+```
+flat_index = r × F + f
+```
+
+For example, on a 3×3 board (shape `[3, 3]`):
+
+```
+             file
+           0   1   2
+        ┌────┬────┬────┐
+rank 0  │  0 │  1 │  2 │
+        ├────┼────┼────┤
+rank 1  │  3 │  4 │  5 │
+        ├────┼────┼────┤
+rank 2  │  6 │  7 │  8 │
+        └────┴────┴────┘
+```
+
+Square `(rank=1, file=2)` → flat index `1 × 3 + 2 = 5`.
+
+**3D board** with shape `[L, R, F]` (L layers, R ranks, F files):
+
+```
+flat_index = l × R × F + r × F + f
+```
+
+### Piece Cardinality
+
+The total number of pieces across all locations (board squares + both hands) must never exceed the number of squares on the board. This invariant is enforced on every transformation.
+
+For a board with *n* squares and *p* total pieces: **0 ≤ p ≤ n**.
 
 ```ruby
-# Shogi-like position with pieces in hand
-Qi.new(
-  [[nil, nil, nil], [nil, "K^", nil], [nil, nil, nil]],
-  { first: ["P", "P", "B"], second: ["p"] },
-  { first: "S", second: "s" },
-  :first
-)
+pos = Qi.new(2, first_player_style: "C", second_player_style: "c")
+  .board_diff(0 => "a", 1 => "b")   # 2 pieces on 2 squares: OK
+
+pos.first_player_hand_diff("c": 1)
+# => ArgumentError: too many pieces for board size (3 pieces, 2 squares)
 ```
 
 ## Validation Errors
 
-| Error message                                                        | Cause                                          |
-|----------------------------------------------------------------------|-------------------------------------------------|
-| `"board must be an Array"`                                           | Board is not an Array                           |
-| `"board must not be empty"`                                          | Board is `[]`                                   |
-| `"board exceeds 3 dimensions (got N)"`                               | More than 3 nesting levels                      |
-| `"dimension size N exceeds maximum of 255"`                          | A dimension has more than 255 elements          |
-| `"non-rectangular board: expected N elements, got M"`                | Sub-arrays at the same level differ in length   |
-| `"inconsistent board structure: mixed arrays and non-arrays at same level"` | Mixed arrays and non-arrays at the same nesting level |
-| `"inconsistent board structure: expected flat squares at this level"` | An array found where a leaf square was expected |
-| `"hands must be a Hash with keys :first and :second"`               | Hands is not a Hash                             |
-| `"hands must have exactly keys :first and :second"`                  | Hash has missing or extra keys                  |
-| `"each hand must be an Array"`                                       | Hand value is not an Array                      |
-| `"hand pieces must not be nil"`                                      | `nil` found in a hand Array                     |
-| `"styles must be a Hash with keys :first and :second"`              | Styles is not a Hash                            |
-| `"styles must have exactly keys :first and :second"`                 | Hash has missing or extra keys                  |
-| `"first player style must not be nil"`                               | First style value is `nil`                      |
-| `"second player style must not be nil"`                              | Second style value is `nil`                     |
-| `"turn must be :first or :second"`                                   | Invalid turn value                              |
-| `"too many pieces for board size (P pieces, N squares)"`             | Piece cardinality violation                     |
+### Validation Order
+
+Construction validates fields in a guaranteed order. When multiple errors exist, the **first** failing check determines the error message:
+
+1. **Shape** — dimension count, types, and bounds
+2. **Styles** — nil checks (first, then second)
+
+This order is part of the public API contract.
+
+### Construction Errors
+
+| Error message | Cause |
+|---------------|-------|
+| `"at least one dimension is required"` | No dimension sizes provided |
+| `"board exceeds 3 dimensions (got N)"` | More than 3 dimension sizes |
+| `"dimension size must be an Integer, got C"` | Non-integer dimension size |
+| `"dimension size must be at least 1, got N"` | Dimension size is zero or negative |
+| `"dimension size N exceeds maximum of 255"` | Dimension size exceeds 255 |
+| `"first player style must not be nil"` | First style is `nil` |
+| `"second player style must not be nil"` | Second style is `nil` |
+
+### Transformation Errors
+
+| Error message | Method | Cause |
+|---------------|--------|-------|
+| `"invalid flat index: I (board has N squares)"` | `board_diff` | Index out of range or non-integer key |
+| `"delta must be an Integer, got C for piece P"` | hand diffs | Non-integer delta |
+| `"cannot remove P: not found in hand"` | hand diffs | Removing more pieces than present |
+| `"too many pieces for board size (P pieces, N squares)"` | all | Total pieces would exceed board capacity |
 
 ## Design Principles
 
-- **Format-agnostic**: No dependency on EPIN, SIN, or any specific encoding.
-- **Protocol-aligned**: Structurally compatible with the Game Protocol's Position model.
-- **Immutable**: Positions are frozen at construction; no mutation is possible.
-- **Validated at construction**: All invariants are enforced when building a position.
-- **Zero dependencies**: Only the Ruby standard library.
+**Immutable by construction.** Every `Qi` instance is frozen at creation. Transformation methods return new instances rather than mutating state. This eliminates an entire class of bugs around shared mutable state and makes positions safe to use as hash keys, cache entries, or history snapshots.
+
+**Diff-based transformations.** Rather than rebuilding a full position from scratch, `board_diff` and hand diff methods express changes as deltas against the current state. This keeps the API surface small (four transformation methods cover all possible state transitions) while making the intent of each operation explicit.
+
+**String normalization.** Pieces and styles are normalized to `String` via interpolation (`"#{value}"`). This aligns with the notation formats in the Sashité ecosystem (FEEN, EPIN, PON, SIN) which all produce string representations, and eliminates type conversions between layers. Rather than rejecting non-string inputs, the library coerces them — guaranteeing internal consistency by construction rather than by validation.
+
+**Zero dependencies.** `Qi` relies only on the Ruby standard library. No transitive dependency tree to audit, no version conflicts to resolve.
+
+## Thread Safety
+
+`Qi` instances are frozen at construction. Accessors that return collections (`board`, hands, `shape`) produce independent copies on each call. Styles are frozen Strings returned directly. This makes positions inherently thread-safe: they can be shared freely across threads without synchronization.
+
+## Ecosystem
+
+`Qi` is the positional core of the [Sashité](https://sashite.dev/) ecosystem. It models *what a position is* (board, hands, styles, turn) without prescribing *how positions are serialized* or *what moves are legal*.
+
+Other libraries in the ecosystem build on `Qi` to provide those capabilities: [FEEN](https://sashite.dev/specs/feen/1.0.0/) defines a canonical string encoding for positions, [PON](https://sashite.dev/specs/pon/1.0.0/) provides a JSON-based position format, [EPIN](https://sashite.dev/specs/epin/1.0.0/) specifies piece token syntax, and [SIN](https://sashite.dev/specs/sin/1.0.0/) specifies style token syntax. The [Game Protocol](https://sashite.dev/game-protocol/) describes the conceptual foundation that all these specifications share.
+
+## Notes for Reimplementors
+
+This section provides guidance for porting `Qi` to other languages.
+
+### API Surface
+
+The complete public API consists of:
+
+- **1 constructor** — `Qi.new(*shape, first_player_style:, second_player_style:)`
+- **7 accessors** — `board`, `first_player_hand`, `second_player_hand`, `turn`, `first_player_style`, `second_player_style`, `shape`
+- **4 transformations** — `board_diff`, `first_player_hand_diff`, `second_player_hand_diff`, `toggle`
+- **1 debug** — `inspect`
+- **2 constants** — `MAX_DIMENSIONS`, `MAX_DIMENSION_SIZE`
+
+### API Naming
+
+The Ruby API separates **accessors** (read) from **transformations** (diff) using a `_diff` suffix. In languages where this convention is unusual, alternatives include `with_board(...)` / `with_first_hand(...)` for a fluent style, or `update_board(...)` / `update_hand(side, ...)` for a more imperative style.
+
+### Key Semantic Contracts
+
+**Pieces and styles are strings.** Board squares, hand contents, and style values are all stored as strings. The Ruby implementation normalizes inputs via interpolation (`"#{value}"`), accepting any value that responds to `to_s`. Statically typed languages should accept string parameters directly.
+
+**Piece equality is by value**, not by identity. Hand removal uses value-based matching (Ruby's `==`). Use the equivalent in your language (`Eq` in Rust, `__eq__` in Python, `equals()` in Java).
+
+**Piece cardinality is global.** The constraint `p ≤ n` counts pieces across all locations: board squares plus both hands. A transformation that adds a piece to a hand can exceed the limit even if the board has empty squares.
+
+**Nil means empty.** On the board, `nil` (or the language equivalent) represents an empty square. It is never coerced to a string. Styles must not be nil — this is the only nil-related error at construction.
+
+**Validation order is guaranteed**: shape → styles. Tests assert which error is reported when multiple inputs are invalid simultaneously.
+
+**Positions are immutable**: all transformation methods return a new instance. The original is never modified.
+
+**Accessors protect internal state**: mutable collections (`board`, hands, `shape`) return fresh copies. Styles are frozen Strings returned directly (zero-cost access). `turn` returns an immutable value.
+
+**The constructor creates an empty position**: board all null, hands empty, turn is first player. Pieces are added via `board_diff` and hand diff methods.
+
+### Hand Diff and String Normalization
+
+In Ruby, keyword arguments produce Symbol keys, so `first_player_hand_diff("P": 1)` passes `{P: 1}` with key `:P` (a Symbol). The implementation normalizes this to the String `"P"` before storing.
+
+This is a Ruby-specific concern. In other languages, hand diff methods should accept string keys directly. The important contract is that the hand always contains strings, matching the board's piece type.
 
-## Related Specifications
+### Duplicate Key Policy
 
-- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
-- [PON Specification](https://sashite.dev/specs/pon/1.0.0/) — JSON-based position format
-- [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/) — Canonical string-based position format
-- [EPIN Specification](https://sashite.dev/specs/epin/1.0.0/) — Piece token format
-- [SIN Specification](https://sashite.dev/specs/sin/1.0.0/) — Style token format
+In Ruby, passing the same keyword argument twice keeps only the last value (`board_diff(0 => "a", 0 => "b")` is equivalent to `board_diff(0 => "b")`). Reimplementations should define their own policy: last-write-wins, first-write-wins, or rejection.
 
 ## License