sashite-feen 0.3.0 → 0.5.0

data/README.md

@@ -1,29 +1,35 @@
-# Feen.rb
+# feen.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/feen.rb/main)
-![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/feen.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/feen.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE)
 
-> **FEEN** (Forsyth–Edwards Enhanced Notation) implementation for the Ruby language.
+> **FEEN** (Field Expression Encoding Notation) implementation for Ruby.
 
-## What is FEEN?
+## Overview
 
-FEEN (Forsyth–Edwards Enhanced Notation) is a universal, rule-agnostic notation for representing board game positions. It extends traditional FEN to support:
+This library implements the [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/), providing serialization and deserialization of board game positions between FEEN strings and [`Qi`](https://github.com/sashite/qi.rb) objects.
 
-- **Multiple game systems** (Chess, Shōgi, Xiangqi, and more)
-- **Cross-style games** where players use different piece sets
-- **Multi-dimensional boards** (2D, 3D, and beyond)
-- **Captured pieces** (pieces-in-hand for drop mechanics)
-- **Arbitrarily large boards** with efficient empty square encoding
-- **Completely irregular structures** (any valid combination of ranks and separators)
-- **Board-less positions** (positions without piece placement, useful for pure style/turn tracking)
+FEEN is a rule-agnostic, canonical position encoding for two-player, turn-based board games built on the [Sashité Game Protocol](https://sashite.dev/game-protocol/). A FEEN string encodes exactly three fields: **piece placement** (board structure and occupancy), **hands** (off-board pieces), and **style–turn** (player styles and active player).
 
-This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/) as a pure functional library with immutable data structures.
+### Implementation Constraints
+
+| Constraint | Value | Rationale |
+|------------|-------|-----------|
+| Regular shapes only | Required | All ranks must have equal length within each dimension |
+| Max string length | 4096 | Sufficient for realistic board positions |
+| Max board dimensions | 3 | Sufficient for 1D, 2D, 3D boards |
+| Max dimension size | 255 | Fits in 8-bit integer; covers 255×255×255 boards |
+
+These constraints enable bounded memory usage and safe parsing.
+
+Only regular board shapes are supported — every rank within a dimension must contain the same number of cells. For example, `9x10` and `8x8` boards are valid. Irregular structures where ranks have different sizes (e.g., ranks of 3, 2, and 4 cells) are not supported.
 
 ## Installation
 
 ```ruby
+# In your Gemfile
 gem "sashite-feen"
 ```
 
@@ -33,479 +39,298 @@ Or install manually:
 gem install sashite-feen
 ```
 
-## Quick Start
+## Dependencies
 
 ```ruby
-require "sashite/feen"
-
-# Parse a FEEN string into an immutable position object
-position = Sashite::Feen.parse("+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")
-
-# Access position components
-position.placement  # Board configuration
-position.hands      # Captured pieces
-position.styles     # Game styles and active player
-
-# Convert placement to array based on dimensionality
-position.placement.to_a # => [[pieces...], [pieces...], ...] for 2D boards
-
-# Convert back to canonical FEEN string
-feen_string = Sashite::Feen.dump(position) # or position.to_s
-```
-
-## FEEN Format
-
-A FEEN string consists of three space-separated fields:
-
-```
-<piece-placement> <pieces-in-hand> <style-turn>
-```
-
-**Example:**
-```txt
-+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
+gem "qi", "~> 13.0"  # Position model
 ```
 
-1. **Piece placement**: Board configuration using EPIN notation with `/` separators (can be empty for board-less positions)
-2. **Pieces in hand**: Captured pieces for each player (format: `first/second`)
-3. **Style-turn**: Game styles and active player (format: `active/inactive`)
+## Usage
 
-See the [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/) for complete format details.
+### Parsing (FEEN String → Qi)
 
-## API Reference
-
-### Module Methods
-
-#### `Sashite::Feen.parse(string)`
-
-Parses a FEEN string into an immutable `Position` object.
-
-- **Parameter**: `string` (String) - FEEN notation string
-- **Returns**: `Position` - Immutable position object
-- **Raises**: `Sashite::Feen::Error` subclasses on invalid input
+Convert a FEEN string into a `Qi` object.
 
 ```ruby
-position = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
-
-# Board-less position (empty piece placement)
-position = Sashite::Feen.parse(" / C/c")
-```
-
-#### `Sashite::Feen.dump(position)`
-
-Converts a position object into its canonical FEEN string.
-
-- **Parameter**: `position` (Position) - Position object
-- **Returns**: `String` - Canonical FEEN string
-- **Guarantees**: Deterministic output (same position always produces same string)
+require "sashite/feen"
 
-```ruby
-feen_string = Sashite::Feen.dump(position)
+# Parse a Shōgi starting position
+position = Sashite::Feen.parse("lnsgk^gsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGK^GSNL / S/s")
+
+# The result is a Qi
+position.shape
+# => [9, 9]
+
+position.board
+# => ["l", "n", "s", "g", "k^", "g", "s", "n", "l",
+#     nil, "r", nil, nil, nil, nil, nil, "b", nil,
+#     "p", "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,
+#     "P", "P", "P", "P", "P", "P", "P", "P", "P",
+#     nil, "B", nil, nil, nil, nil, nil, "R", nil,
+#     "L", "N", "S", "G", "K^", "G", "S", "N", "L"]
+
+position.to_nested
+# => [["l", "n", "s", "g", "k^", "g", "s", "n", "l"],
+#     [nil, "r", nil, nil, nil, nil, nil, "b", nil],
+#     ["p", "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],
+#     ["P", "P", "P", "P", "P", "P", "P", "P", "P"],
+#     [nil, "B", nil, nil, nil, nil, nil, "R", nil],
+#     ["L", "N", "S", "G", "K^", "G", "S", "N", "L"]]
+
+position.first_player_hand   # => {}
+position.second_player_hand  # => {}
+position.first_player_style  # => "S"
+position.second_player_style # => "s"
+position.turn                # => :first
+
+# Invalid input raises an error
+Sashite::Feen.parse("invalid")  # => raises Sashite::Feen::ParseError
 ```
 
-### Position Object
+### Dumping (Qi → FEEN String)
 
-The `Position` object is immutable and provides read-only access to three components:
+Convert a `Qi` back to a canonical FEEN string.
 
 ```ruby
-position.placement  # => Placement (board configuration)
-position.hands      # => Hands (pieces in hand)
-position.styles     # => Styles (style-turn information)
-position.to_s       # => String (canonical FEEN)
-```
-
-**Equality and hashing:**
-```ruby
-position1 == position2  # Component-wise equality
-position1.hash          # Consistent hash for same positions
+# From an existing Qi
+position = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
+Sashite::Feen.dump(position)
+# => "8/8/8/8/8/8/8/8 / C/c"
+
+# From a Qi built manually
+position = Qi.new([1, 8], first_player_style: "C", second_player_style: "c")
+  .board_diff(0 => "K^", 7 => "k^")
+Sashite::Feen.dump(position)
+# => "K^6k^ / C/c"
 ```
 
-### Placement Object
-
-Represents the board configuration as a flat array of ranks with explicit separators.
+### Validation
 
 ```ruby
-placement.ranks         # => Array<Array> - Flat array of all ranks
-placement.separators    # => Array<String> - Separators between ranks (e.g., ["/", "//"])
-placement.dimension     # => Integer - Board dimensionality (1 + max consecutive slashes)
-placement.rank_count    # => Integer - Total number of ranks
-placement.one_dimensional? # => Boolean - True if dimension is 1
-placement.all_pieces    # => Array - All pieces (nils excluded)
-placement.total_squares # => Integer - Total square count
-placement.to_s          # => String - Piece placement field
-placement.to_a          # => Array - Array representation (dimension-aware)
+# Boolean check (never raises)
+Sashite::Feen.valid?("lnsgk^gsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGK^GSNL / S/s")  # => true
+Sashite::Feen.valid?("8/8/8/8/8/8/8/8 / C/c")  # => true (empty board)
+Sashite::Feen.valid?("k^+p4+PK^ / C/c")        # => true (1D board)
+Sashite::Feen.valid?("a/b//c/d / G/g")         # => true (3D board)
+Sashite::Feen.valid?("rkr//PPPP / G/g")        # => false (dimensional coherence)
+Sashite::Feen.valid?("invalid")                # => false
+Sashite::Feen.valid?(nil)                      # => false
 ```
 
-#### `to_a` - Dimension-Aware Array Conversion
-
-The `to_a` method returns an array representation that adapts to the board's dimensionality:
+### Round-trip Examples
 
-- **1D boards**: Returns a single rank array (or empty array if no ranks)
-- **2D+ boards**: Returns array of ranks
+FEEN parsing and dumping are perfect inverses — any valid FEEN string round-trips through `Qi` without loss.
 
 ```ruby
-# 1D board - Returns flat array
-feen = "K2P3k / C/c"
+# Chess starting position
+feen = "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"
 position = Sashite::Feen.parse(feen)
-position.placement.to_a
-# => [K, nil, nil, P, nil, nil, nil, k]
+Sashite::Feen.dump(position) == feen  # => true
 
-# 2D board - Returns array of arrays
-feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c"
+# Xiangqi starting position
+feen = "rheag^aehr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RHEAG^AEHR / X/x"
 position = Sashite::Feen.parse(feen)
-position.placement.to_a
-# => [[r,n,b,q,k,b,n,r], [p,p,p,p,p,p,p,p], [nil×8], ...]
-
-# 3D board - Returns array of ranks (to be structured by application)
-feen = "5/5//5/5 / R/r"
-position = Sashite::Feen.parse(feen)
-position.placement.to_a
-# => [[nil×5], [nil×5], [nil×5], [nil×5]]
-
-# Empty board
-placement = Sashite::Feen::Placement.new([], [], 1)
-placement.to_a
-# => []
-```
-
-**Other methods:**
-
-```ruby
-# Access specific positions
-first_rank = placement.ranks[0]
-piece_at_a1 = first_rank[0] # Piece object or nil
-
-# Check dimensionality
-placement.dimension # => 2 (2D board)
-
-# Inspect separator structure
-placement.separators # => ["/", "/", "/", "/", "/", "/", "/"]
-```
-
-### Hands Object
-
-Represents captured pieces held by each player.
-
-```ruby
-hands.first_player   # => Array - Pieces held by first player
-hands.second_player  # => Array - Pieces held by second player
-hands.empty?         # => Boolean - True if both hands are empty
-hands.to_s           # => String - Pieces-in-hand field
-```
-
-**Example:**
-```ruby
-# Count pieces in hand
-first_player_pawns = hands.first_player.count { |p| p.to_s == "P" }
-
-# Check if any captures
-hands.empty? # => false
-```
-
-### Styles Object
-
-Represents game styles and indicates the active player.
-
-```ruby
-styles.active    # => SIN identifier - Active player's style
-styles.inactive  # => SIN identifier - Inactive player's style
-styles.to_s      # => String - Style-turn field
-```
-
-**Example:**
-```ruby
-# Determine active player
-styles.active.to_s    # => "C" (first player Chess)
-styles.inactive.to_s  # => "c" (second player Chess)
-
-# Check if cross-style
-styles.active.to_s.upcase != styles.inactive.to_s.upcase
+Sashite::Feen.dump(position) == feen  # => true
 ```
 
-## Examples
+### Hands
 
-### Chess Positions
+Pieces in hand are represented as count maps (`Hash{String => Integer}`) in `Qi`. FEEN automatically handles aggregation (for serialization) and expansion (for parsing).
 
 ```ruby
-# Starting position
-chess_start = Sashite::Feen.parse(
-  "+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"
-)
-
-# After 1.e4
-after_e4 = Sashite::Feen.parse(
-  "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/4P3/8/+P+P+P+P1+P+P+P/+RNBQ+KBN+R / c/C"
-)
-
-# Ruy Lopez opening
-ruy_lopez = Sashite::Feen.parse(
-  "r1bqkbnr/+p+p+p+p1+p+p+p/2n5/1B2p3/4P3/5N2/+P+P+P+P1+P+P+P/RNBQK2R / c/C"
-)
-```
-
-### Shōgi with Captured Pieces
-
-```ruby
-# Starting position
-shogi_start = Sashite::Feen.parse(
-  "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / S/s"
-)
-
-# Position with pieces in hand
-shogi_midgame = Sashite::Feen.parse(
-  "lnsgkgsnl/1r5b1/pppp1pppp/9/4p4/9/PPPP1PPPP/1B5R1/LNSGKGSNL P/p s/S"
-)
-
-# Access captured pieces
-position = shogi_midgame
-position.hands.first_player   # => [P] (one pawn)
-position.hands.second_player  # => [p] (one pawn)
-
-# Count specific pieces in hand
-position.hands.first_player.count { |p| p.to_s == "P" } # => 1
-```
-
-### Cross-Style Games
-
-```ruby
-# Chess vs Makruk
-chess_vs_makruk = Sashite::Feen.parse(
-  "rnsmksnr/8/pppppppp/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/m"
-)
-
-# Chess vs Shōgi
-chess_vs_shogi = Sashite::Feen.parse(
-  "lnsgkgsnl/1r5b1/pppppppp/9/9/9/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/s"
-)
-
-# Check styles
-position = chess_vs_makruk
-position.styles.active.to_s    # => "C" (Chess, first player)
-position.styles.inactive.to_s  # => "m" (Makruk, second player)
-```
-
-### Multi-Dimensional Boards
-
-```ruby
-# 3D Chess (Raumschach)
-raumschach = Sashite::Feen.parse(
-  "rnknr/+p+p+p+p+p/5/5/5//buqbu/+p+p+p+p+p/5/5/5//5/5/5/5/5//5/5/5/+P+P+P+P+P/BUQBU//5/5/5/+P+P+P+P+P/RNKNR / R/r"
-)
-
-# Check dimensionality
-raumschach.placement.dimension  # => 3 (3D board)
-raumschach.placement.ranks.size # => 25 (total ranks)
-
-# Inspect separator structure
-level_seps = raumschach.placement.separators.count { |s| s == "//" }
-rank_seps = raumschach.placement.separators.count { |s| s == "/" }
-# level_seps => 4 (separates 5 levels)
-# rank_seps => 20 (separates ranks within levels)
-```
-
-### Irregular Boards
-
-```ruby
-# Diamond-shaped board
-diamond = Sashite::Feen.parse("3/4/5/4/3 / G/g")
-
-# Check structure
-diamond.placement.ranks.map(&:size) # => [3, 4, 5, 4, 3]
+# Shōgi mid-game with captured pieces
+feen = "lnsgk^gsnl/1r5b1/pppp1pppp/9/9/9/PPPP1PPPP/1B5R1/LNSGK^GSNL P/p S/s"
+position = Sashite::Feen.parse(feen)
 
-# Very large board
-large_board = Sashite::Feen.parse("100/100/100 / G/g")
-large_board.placement.total_squares # => 300
+position.first_player_hand   # => { "P" => 1 }
+position.second_player_hand  # => { "p" => 1 }
 
-# Single square
-single = Sashite::Feen.parse("K / C/c")
-single.placement.rank_count # => 1
+# Multiple identical pieces are aggregated in FEEN
+position = Qi.new([3, 3], first_player_style: "S", second_player_style: "s")
+  .board_diff(4 => "K^")
+  .first_player_hand_diff("P": 2, "B": 1)
+  .second_player_hand_diff("p": 1)
+Sashite::Feen.dump(position)
+# => "3/1K^1/3 2PB/p S/s"
 ```
 
-### Completely Irregular Structures
+### Multi-dimensional Boards
 
-FEEN supports any valid combination of ranks and separators:
+`Qi` supports 1D, 2D, and 3D boards natively.
 
 ```ruby
-# Extreme irregularity with variable separators
-feen = "99999/3///K/k//r / G/g"
+# 1D board
+feen = "k^+p4+PK^ / C/c"
 position = Sashite::Feen.parse(feen)
+position.shape  # => [8]
+position.board
+# => ["k^", "+p", nil, nil, nil, nil, "+P", "K^"]
 
-# Access the structure
-position.placement.ranks.size      # => 5 ranks
-position.placement.separators      # => ["/", "///", "/", "//"]
-position.placement.dimension       # => 4 (max separator is "///")
-
-# Each rank can have different sizes
-position.placement.ranks[0].size   # => 99999
-position.placement.ranks[1].size   # => 3
-position.placement.ranks[2].size   # => 1
-position.placement.ranks[3].size   # => 1
-position.placement.ranks[4].size   # => 1
-
-# Round-trip preservation
-Sashite::Feen.dump(position) == feen # => true
+# 3D board (2 layers × 2 ranks × 2 files)
+feen = "ab/cd//AB/CD / G/g"
+position = Sashite::Feen.parse(feen)
+position.shape  # => [2, 2, 2]
+position.to_nested
+# => [[["a", "b"], ["c", "d"]],
+#     [["A", "B"], ["C", "D"]]]
 ```
 
-### Empty Ranks
+### Style–Turn Mapping
 
-FEEN supports empty ranks (ranks with no pieces):
+The FEEN style–turn field maps directly to `Qi`'s style and turn accessors.
 
 ```ruby
-# Trailing separator creates empty rank
-feen = "K/// / C/c"
-position = Sashite::Feen.parse(feen)
-
-position.placement.ranks.size  # => 2
-position.placement.ranks[0]    # => [K]
-position.placement.ranks[1]    # => [] (empty rank)
-position.placement.separators  # => ["///"]
-
-# Round-trip preserves structure
-Sashite::Feen.dump(position) == feen # => true
+# First player to move (uppercase style is active)
+position = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
+position.first_player_style   # => "C"
+position.second_player_style  # => "c"
+position.turn                 # => :first
+
+# Second player to move (lowercase style is active)
+position = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / c/C")
+position.first_player_style   # => "C"
+position.second_player_style  # => "c"
+position.turn                 # => :second
 ```
 
-### Board-less Positions
+## API Reference
 
-FEEN supports positions without piece placement, useful for tracking only style and turn information:
+### Module Methods
 
 ```ruby
-# Position with empty board (no piece placement)
-board_less = Sashite::Feen.parse(" / C/c")
-
-board_less.placement.ranks.size     # => 1
-board_less.placement.dimension      # => 1
-board_less.placement.to_a           # => []
-
-# Convert back to FEEN
-Sashite::Feen.dump(board_less) # => " / C/c"
+# Parses a FEEN string into a Qi.
+# Pieces on the board are EPIN token strings; empty squares are nil.
+# Raises ParseError (or subclass) if the string is not valid.
+#
+# @param feen_string [String] FEEN string
+# @return [Qi]
+# @raise [ParseError] if invalid
+def Sashite::Feen.parse(feen_string)
+
+# Reports whether string is a valid FEEN position.
+# Never raises; returns false for any invalid input.
+# Uses an exception-free code path internally for performance.
+#
+# @param feen_string [String] FEEN string
+# @return [Boolean]
+def Sashite::Feen.valid?(feen_string)
+
+# Serializes a Qi to a canonical FEEN string.
+# Board pieces must be valid EPIN token strings.
+# Style values must be valid SIN token strings.
+#
+# @param position [Qi] Position to serialize
+# @return [String] Canonical FEEN string
+# @raise [ArgumentError] if position contains invalid tokens
+def Sashite::Feen.dump(position)
 ```
 
-### Working with Positions
+### Constants
 
 ```ruby
-# Compare positions
-position1 = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
-position2 = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
-position1 == position2 # => true
-
-# Round-trip parsing
-original = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
-position = Sashite::Feen.parse(original)
-Sashite::Feen.dump(position) == original # => true
-
-# Extract specific information
-position.placement.ranks[0] # First rank (array of pieces/nils)
-position.hands.first_player.size # Number of captured pieces
+Sashite::Feen::Limits::MAX_STRING_LENGTH  # => 4096
+Sashite::Feen::Limits::MAX_DIMENSIONS     # => 3
+Sashite::Feen::Limits::MAX_DIMENSION_SIZE # => 255
 ```
 
-### State Modifiers and Derivation
-
-```ruby
-# Enhanced pieces (promoted, with special rights)
-enhanced = Sashite::Feen.parse("+K+Q+R+B/8/8/8/8/8/8/8 / C/c")
+### Error Hierarchy
 
-# Diminished pieces (weakened, vulnerable)
-diminished = Sashite::Feen.parse("-K-Q-R-B/8/8/8/8/8/8/8 / C/c")
+All errors inherit from `Sashite::Feen::Error`, which inherits from `ArgumentError`:
 
-# Foreign pieces (using opponent's style)
-foreign = Sashite::Feen.parse("K'Q'R'B'/k'q'r'b'/8/8/8/8/8/8 / C/s")
+```
+ArgumentError
+└── Sashite::Feen::Error
+    └── Sashite::Feen::ParseError
+        ├── Sashite::Feen::PiecePlacementError
+        ├── Sashite::Feen::HandsError
+        ├── Sashite::Feen::StyleTurnError
+        └── Sashite::Feen::CardinalityError
 ```
 
-## Error Handling
-
-FEEN defines specific error classes for different validation failures:
+You can rescue at any level:
 
 ```ruby
+# Catch all FEEN errors
 begin
-  position = Sashite::Feen.parse("invalid feen")
+  Sashite::Feen.parse(input)
 rescue Sashite::Feen::Error => e
-  # Base error class catches all FEEN errors
-  warn "FEEN error: #{e.message}"
+  puts "FEEN error: #{e.message}"
 end
-```
-
-### Error Hierarchy
-
-```txt
-Sashite::Feen::Error             # Base error class
-├── Error::Syntax                # Malformed FEEN structure
-├── Error::Piece                 # Invalid EPIN notation
-├── Error::Style                 # Invalid SIN notation
-├── Error::Count                 # Invalid piece counts
-└── Error::Validation            # Other semantic violations
-```
-
-### Common Errors
 
-```ruby
-# Syntax error - wrong field count
-Sashite::Feen.parse("8/8/8/8/8/8/8/8 /")
-# => Error::Syntax: "FEEN must have exactly 3 space-separated fields, got 2"
-
-# Style error - invalid SIN
-Sashite::Feen.parse("8/8/8/8/8/8/8/8 / 1/2")
-# => Error::Style: "failed to parse SIN '1': invalid SIN notation: '1' (must be a single letter A-Z or a-z)"
-
-# Count error - invalid quantity
-Sashite::Feen.parse("8/8/8/8/8/8/8/8 0P/ C/c")
-# => Error::Count: "piece count must be at least 1, got 0"
-```
-
-## Properties
-
-- **Purely functional**: Immutable data structures, no side effects
-- **Canonical output**: Deterministic string generation (same position → same string)
-- **Specification compliant**: Strict adherence to [FEEN v1.0.0](https://sashite.dev/specs/feen/1.0.0/)
-- **Minimal API**: Two methods (`parse` and `dump`) for complete functionality
-- **Universal**: Supports any abstract strategy board game
-- **Completely flexible**: Accepts any valid combination of ranks and separators
-- **Perfect round-trip**: `parse(dump(position)) == position` guaranteed
-- **Dimension-aware**: Intelligent array conversion based on board structure
-- **Composable**: Built on [EPIN](https://github.com/sashite/epin.rb) and [SIN](https://github.com/sashite/sin.rb) specifications
-
-## Dependencies
-
-- [sashite-epin](https://github.com/sashite/epin.rb) — Extended Piece Identifier Notation
-- [sashite-sin](https://github.com/sashite/sin.rb) — Style Identifier Notation
-
-## Documentation
-
-- [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/) — Complete technical specification
-- [FEEN Examples](https://sashite.dev/specs/feen/1.0.0/examples/) — Comprehensive examples
-- [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main) — Full API reference
-- [GitHub Wiki](https://github.com/sashite/feen.rb/wiki) — Advanced usage and patterns
-
-## Development
-
-```sh
-# Clone the repository
-git clone https://github.com/sashite/feen.rb.git
-cd feen.rb
-
-# Install dependencies
-bundle install
-
-# Run tests
-ruby test.rb
+# Catch specific field errors
+begin
+  Sashite::Feen.parse(input)
+rescue Sashite::Feen::PiecePlacementError => e
+  puts "Board error: #{e.message}"
+rescue Sashite::Feen::HandsError => e
+  puts "Hands error: #{e.message}"
+end
 
-# Generate documentation
-yard doc
+# Or catch as standard ArgumentError
+begin
+  Sashite::Feen.parse(input)
+rescue ArgumentError => e
+  puts "Invalid argument: #{e.message}"
+end
 ```
 
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/new-feature`)
-3. Add tests for your changes
-4. Ensure all tests pass (`ruby test.rb`)
-5. Commit your changes (`git commit -am 'Add new feature'`)
-6. Push to the branch (`git push origin feature/new-feature`)
-7. Create a Pull Request
+### Error Messages
+
+| Error Class | Message | Cause |
+|-------------|---------|-------|
+| `ParseError` | `"input exceeds 4096 characters"` | String too long |
+| `ParseError` | `"invalid field count"` | Not exactly 3 space-separated fields |
+| `PiecePlacementError` | `"piece placement is empty"` | Field 1 is empty |
+| `PiecePlacementError` | `"piece placement starts with separator"` | Field 1 starts with `/` |
+| `PiecePlacementError` | `"piece placement ends with separator"` | Field 1 ends with `/` |
+| `PiecePlacementError` | `"invalid empty count"` | Empty count is zero or has leading zeros |
+| `PiecePlacementError` | `"invalid piece token"` | Token is not a valid EPIN identifier |
+| `PiecePlacementError` | `"dimensional coherence violation"` | Separator depth mismatch |
+| `PiecePlacementError` | `"exceeds 3 dimensions"` | Board has more than 3 dimensions |
+| `PiecePlacementError` | `"dimension size exceeds 255"` | A rank exceeds 255 squares |
+| `HandsError` | `"invalid hands delimiter"` | Field 2 missing `/` or has multiple |
+| `HandsError` | `"invalid hand count"` | Multiplicity is 0, 1, or has leading zeros |
+| `HandsError` | `"hand items not aggregated"` | Identical EPIN tokens not combined |
+| `HandsError` | `"hand items not in canonical order"` | Items violate ordering rules |
+| `StyleTurnError` | `"invalid style-turn delimiter"` | Field 3 missing `/` or has multiple |
+| `StyleTurnError` | `"invalid style token"` | Token is not a valid SIN identifier |
+| `StyleTurnError` | `"style tokens must have opposite case"` | Both tokens same case |
+| `CardinalityError` | `"too many pieces for board size"` | Total pieces exceeds total squares |
+
+## Design Principles
+
+- **Spec conformance**: Strict adherence to FEEN v1.0.0
+- **Qi integration**: Parses to and dumps from `Qi`, the shared position model across Sashité libraries
+- **Zero external parsing dependencies**: EPIN and SIN validation is inlined for performance; only `Qi` is required at runtime
+- **Canonical output**: `dump` always produces canonical form
+- **Structured errors**: Hierarchical error classes for precise handling
+- **Ruby idioms**: `valid?` predicate, `parse`/`dump` symmetry, `ArgumentError` for invalid input
+- **Defensive limits**: Bounded memory usage via configurable constraints
+- **Performance-oriented internals**: Exception-free validation path; exceptions only at the public API boundary
+
+### Performance Architecture
+
+Parsing is internally split into two layers to avoid using exceptions for control flow:
+
+- **Validation layer** — Each sub-parser (`PiecePlacement`, `Hands`, `StyleTurn`) exposes a `safe_parse` method that returns `nil` on invalid input instead of raising an exception. This path performs all structural validation and data extraction without allocating exception objects or capturing backtraces.
+- **Public API layer** — `parse` calls the validation layer internally. On failure, it raises the appropriate error class exactly once, at the boundary. `valid?` calls the same validation layer and returns a boolean directly, never raising and never constructing a `Qi` object on invalid input.
+
+This dual-path design eliminates the cost of exception-based control flow on the hot path. Since `valid?` is commonly called on untrusted or invalid input, avoiding `raise`/`rescue` per rejection keeps validation at pure method-call speed. On the `parse` side, the single `raise` at the boundary is an acceptable cost — it happens once per invalid call, not once per sub-parser.
+
+## Related Specifications
+
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/) — Official specification
+- [FEEN Examples](https://sashite.dev/specs/feen/1.0.0/examples/) — Usage examples
+- [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
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
-
-## About
-
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).