pgn2 1.5.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da98f302d6785b75581d53fbe6dab4b7ccad9f5514f7ad278be12a540633d572
-  data.tar.gz: 9b22f32a2b44bd06cfd8d29c82f9b4af8c1c4687ed9650df33c4d5fdc76dd49e
+  metadata.gz: d6363546a03960706a76a2048b8e88aff387e1f475eb76add1e1cfd615c6b6ed
+  data.tar.gz: 3944288b73d63291f31c0218902206eb39e2d8173fca7a91bb80aea59e0981a5
 SHA512:
-  metadata.gz: 0c99f7034728254221189f9af053bc6c57938d24c96d83d8dacce7ad78cf2bc8b23de3b28a497c9b750b12f63dd17a9ca6ed65b293c5f8f0188d4f79b188e5d2
-  data.tar.gz: 437fbf1d534aa15578bef06c4ca5020116f6b2385d81c886104f69bb8db0124d7e220b3d566a22f8df4e93180929519891ba71279db21e0e2f541f1b6f0f8892
+  metadata.gz: 1bb3c90fcc6afcf5a2a7ca8a285518035de7645a7627c8d64ed89200e16e364f4f687dfe2107a3b3d6f2b2d994ce8cac5620f2f2d9418bdcd874cc84d07dddc5
+  data.tar.gz: b8b0e3a0254a29397d2ac263e16ea51ed524d886e2a9c69107d9cfa3c3ae4b6ba5cbbbfd8d4a14d73d74c5525f03102cd4aacbcee93ce5a9263288b05fd4e089

data/.github/workflows/ci.yml

@@ -19,19 +19,50 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - run: bundle exec rake compile
       - run: bundle exec rspec --format documentation
 
   rubocop:
-    name: RuboCop (non-blocking)
+    name: RuboCop
+    runs-on: ubuntu-latest
+    env:
+      RUBOCOP_CACHE_ROOT: tmp/rubocop
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Prepare RuboCop cache
+        uses: actions/cache@v4
+        env:
+          DEPENDENCIES_HASH: ${{ hashFiles('.ruby-version', '**/.rubocop.yml', 'Gemfile.lock') }}
+        with:
+          path: ${{ env.RUBOCOP_CACHE_ROOT }}
+          key: rubocop-${{ runner.os }}-${{ env.DEPENDENCIES_HASH }}-${{ github.ref_name == github.event.repository.default_branch && github.run_id || 'default' }}
+          restore-keys: |
+            rubocop-${{ runner.os }}-${{ env.DEPENDENCIES_HASH }}-
+
+      - name: Lint code for consistent style
+        run: bundle exec rubocop -f github
+
+  bundle-audit:
+    name: Bundler-audit (gem vulnerabilities)
     runs-on: ubuntu-latest
-    continue-on-error: true
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '3.3'
           bundler-cache: true
-      - run: bundle exec rubocop
+      - name: Update the advisory database
+        run: bundle exec bundle-audit update
+      - name: Check dependencies for known vulnerabilities
+        run: bundle exec bundle-audit check
 
   # Verifies that lib/pgn/pgn_parser.rb (committed) matches what `racc`
   # regenerates from lib/pgn/pgn_parser.y, so the checked-in parser never

data/.github/workflows/native.yml

@@ -0,0 +1,32 @@
+name: native
+
+# Builds and tests the required Rust bitboard perft backend (a thin
+# adapter over the `chessie` crate): runs the perft oracle via
+# `cargo test`, compiles the native extension via `rake compile`, and
+# runs the full RSpec suite (which loads the ext and includes the
+# PGN::Bitboard::Engine specs).
+
+on:
+  push:
+    branches: [main, 'perf/**', 'feat/**']
+  pull_request:
+
+jobs:
+  test:
+    name: cargo test + rake compile + rspec
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - name: cargo test (Rust engine + perft oracle)
+        run: cargo test --manifest-path ext/pgn2_native/Cargo.toml
+      - name: rake compile (build native ext)
+        run: bundle exec rake compile
+      - name: rspec (with native ext loaded)
+        run: bundle exec rspec

data/.github/workflows/publish.yml

@@ -10,7 +10,9 @@ name: Publish to RubyGems
 #
 # To release a new version locally:
 #   bump lib/pgn/version.rb -> commit -> tag v<x.y.z> -> git push --tags
-# This workflow then builds and pushes the .gem automatically.
+# This workflow then builds and pushes the .gem automatically — but only after
+# the RSpec matrix, RuboCop, bundler-audit, and the racc in-sync check all
+# pass.
 
 on:
   push:
@@ -31,11 +33,51 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - run: bundle exec rake compile
       - run: bundle exec rspec
 
+  rubocop:
+    name: RuboCop (on tag)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec rubocop -f github
+
+  bundle-audit:
+    name: Bundler-audit (on tag)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec bundle-audit update
+      - run: bundle exec bundle-audit check
+
+  parser-reproducible:
+    name: Racc parser in sync with grammar (on tag)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: |
+          bundle exec racc -o /tmp/pgn_parser.check.rb lib/pgn/pgn_parser.y
+          diff -u lib/pgn/pgn_parser.rb /tmp/pgn_parser.check.rb
+
   publish:
     name: Build & push gem
-    needs: test
+    needs: [test, rubocop, bundle-audit, parser-reproducible]
     runs-on: ubuntu-latest
     environment: release
     permissions:

data/.github/workflows/release-gems.yml

@@ -0,0 +1,43 @@
+name: release-gems
+
+# Cross-compiles prebuilt native platform gems for the Rust bitboard
+# backend using rake-compiler-dock (which spins up Docker images for each
+# target). End users then `gem install pgn2` and get a binary — no Rust
+# toolchain required. Push to RubyGems is gated on a published release;
+# `workflow_dispatch` builds + uploads artifacts without pushing.
+#
+# The target platform list is configured in the Rakefile's
+# Rake::ExtensionTask (ext.cross_platform); keep that list as the single
+# source of truth.
+#
+# Targets:
+#   x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build prebuilt platform gems
+        run: bundle exec rake native:gem
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-gems
+          path: pkg/*.gem
+      - name: Push to RubyGems
+        if: github.event_name == 'release'
+        run: |
+          for g in pkg/*.gem; do gem push "$g"; done
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+          GEM_HOST_OTP_CODE: ${{ secrets.RUBYGEMS_OTP }}

data/.github/workflows/release.yml

@@ -1,10 +1,11 @@
 name: Release
 
 # Auto-releases on any push to `main` whose version (lib/pgn/version.rb) does
-# not yet have a matching `v<x.y.z>` tag. It gates on the RSpec matrix, then
-# creates the tag and pushes the gem to rubygems.org in this same workflow
-# (a tag pushed by the GITHUB_TOKEN does NOT trigger other workflows, so the
-# publish happens here directly to avoid that limitation).
+# not yet have a matching `v<x.y.z>` tag. It gates on the RSpec matrix,
+# RuboCop, bundler-audit, and the racc in-sync check, then creates the tag
+# and pushes the gem to rubygems.org in this same workflow (a tag pushed by
+# the GITHUB_TOKEN does NOT trigger other workflows, so the publish happens
+# here directly to avoid that limitation).
 #
 # Manual releases still work: `git tag vX.Y.Z && git push origin vX.Y.Z` fires
 # publish.yml (human-pushed tags do trigger workflows).
@@ -51,11 +52,57 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - run: bundle exec rake compile
       - run: bundle exec rspec
 
+  rubocop:
+    name: RuboCop
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec rubocop -f github
+
+  bundle-audit:
+    name: Bundler-audit
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec bundle-audit update
+      - run: bundle exec bundle-audit check
+
+  parser-reproducible:
+    name: Racc parser in sync with grammar
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: |
+          bundle exec racc -o /tmp/pgn_parser.check.rb lib/pgn/pgn_parser.y
+          diff -u lib/pgn/pgn_parser.rb /tmp/pgn_parser.check.rb
+
   release:
     name: Tag & publish
-    needs: [check, test]
+    needs: [check, test, rubocop, bundle-audit, parser-reproducible]
     if: needs.check.outputs.should_release == 'true'
     runs-on: ubuntu-latest
     environment: release

data/.gitignore

@@ -18,4 +18,12 @@ tmp
 
 
 tags
-*.output
+*.output
+.worktrees/
+ext/pgn2_native/target
+lib/pgn2_native
+
+# Throwaway experiment crates (chessie/chess smoke tests) — never ship in the gem.
+/exp/
+# Cargo build artifacts anywhere.
+/target/

data/.rubocop.yml

@@ -7,20 +7,30 @@ AllCops:
     - "bench/**/*"
     - "vendor/**/*"
     - "pkg/**/*"
+    - "tmp/**/*"
+    # rake-compiler's staging dir (a copy of the tree under tmp/) is a build
+    # artifact; lint it only indirectly via the real source files.
+    # lib/pgn/pgn_parser.rb is generated by racc from pgn_parser.y; CI keeps it
+    # in sync via the `parser-reproducible` job, so do not lint the generated
+    # output (racc emits non-conforming names/heredocs we cannot control).
+    - "lib/pgn/pgn_parser.rb"
 
-# This is a small, mostly-stable gem; skip mandatory top-level docs.
+# This is a small, mostly-stable gem; skip mandatory top-level doc.
 Style/Documentation:
   Enabled: false
 
 Style/StringLiterals:
   EnforcedStyle: single_quotes
 
+# Frozen-string-literal comments were previously disabled via an invalid
+# `EnabledForRuby` parameter (which rubocop silently ignored, leaving the cop
+# enabled and reporting across every file). Keep the intended behaviour —
+# disabled — explicitly so the whole tree is consistent without churn.
 Style/FrozenStringLiteralComment:
-  EnabledForRuby: false
-  Enabled: true
+  Enabled: false
 
 Layout/LineLength:
-  Max: 100
+  Max: 120
 
 # The SAN/PGN grammar and move-calculation logic are inherently branchy;
 # don't fight the domain, just keep an eye on egregious cases.
@@ -28,11 +38,41 @@ Metrics/MethodLength:
   Max: 20
 
 Metrics/AbcSize:
-  Max: 25
+  Max: 30
+  # Test helpers (e.g. expect_moves_equal) iterate over move trees and are
+  # naturally branchy; ABC size is not a useful signal there.
+  Exclude:
+    - "spec/**/*"
 
 Metrics/ClassLength:
-  Max: 150
+  Max: 220
+  # notation.rb is the full SAN encoder; splitting it would hurt cohesion.
+  Exclude:
+    - "lib/pgn/notation.rb"
 
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
+    - "*.gemspec"
+    - "**/*.gemspec"
+
+Metrics/CyclomaticComplexity:
+  Max: 11
+
+Metrics/PerceivedComplexity:
+  Max: 11
+
+Metrics/ParameterLists:
+  Max: 6
+  MaxOptionalParameters: 4
+
+# `has_extras?` is part of the published public API; renaming to `extras?`
+# would be a breaking change for a released gem, so disable this cop.
+Naming/PredicatePrefix:
+  Enabled: false
+
+# This gem intentionally declares development dependencies in the gemspec
+# (consumed via `gemspec` in the Gemfile) — the canonical pattern for a
+# distributable gem — rather than in a Gemfile group.
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,220 @@
 # Changelog
 
+## 2.0.1 (2026-08-15)
+
+### Summary
+
+Native Rust bitboard perft backend: a `pgn2-bitboard` **adapter over the
+`chessie` crate** (MPL-2.0; magic-bitboard move generation with
+checkmask/pinmask legality) exposed to Ruby as `PGN::Bitboard::Engine`
+via a `magnus`/`rb_sys` `cdylib` (`pgn2_native`), shipped as precompiled
+platform gems. The engine lives in `ext/pgn2_native/` and is fully
+decoupled from the pure-Ruby 0x88 `Board`/`Notation`/`MoveCalculator`,
+which stay byte-identical; all specs green. Fast perft (~90–140 Mnps
+pure-Rust on x86-64/BMI2, ~4–6× the earlier hand-rolled engine) is the
+primary deliverable; a thin `#legal_moves` / `#legal?` UCI API is the
+byproduct. Perft is cross-validated against the published perft suite
+(startpos/Kiwipete/positions 3–6).
+
+**Major bump rationale:** the native extension is a *required compiled
+artifact* (no pure-Ruby fallback for the shipped path), which changes the
+install/packaging contract — hence 2.0.0 even though the Ruby API is
+purely additive (`PGN::Bitboard` is new; existing classes are untouched).
+
+### Added
+- **`PGN::Node`** — a navigable, mutable game-tree view via
+  `PGN::Game#root`: parent/children/variation links, a lazy cached
+  pure-Ruby `Node#position` (no native-engine dependency), and variation
+  management (`add_variation`, `add_main_variation`, `promote`, `demote`,
+  `promote_to_main`, `demote_to_last`, `delete`). `MoveText` remains the
+  source of truth; mutations edit it in place and normalize the affected
+  branching point to flat sibling storage, so `Game#moves` and the
+  serializer stay correct and PGN round-trips remain byte-identical for
+  un-mutated games. Non-breaking — `Game#moves` and `MoveText` keep their
+  shapes.
+- **`PGN::Bitboard::Engine`** (native): `Engine.new(fen)`, `#perft(depth)`,
+  `#legal_moves` (sorted UCI), `#legal?(uci)`. Validates against the
+  published perft suite (startpos depth 6 = 119,060,324; Kiwipete depth 5
+  = 193,690,690; positions 3–6).
+- **`ext/pgn2_native/`** Cargo workspace: `pgn2-bitboard` (thin adapter
+  over the `chessie` crate — `cargo test` runs the perft oracle) +
+  `pgn2_native` (`cdylib`, `magnus` bindings). Built via
+  `rb_sys`/`extconf.rb`; `bundle exec rake compile`.
+- **`NOTICE.md`** + `spec.licenses = ['MIT', 'MPL-2.0']`: the gem's own
+  code stays MIT; the bundled `chessie`/`chessie_types` are MPL-2.0
+  (file-level copyleft, attributed in `NOTICE.md`, source pinned in
+  `ext/pgn2_native/Cargo.lock`).
+- **`lib/pgn/bitboard.rb`** load gate: requires the native lib, rescuing
+  `LoadError` so the rest of the gem works without it.
+- **`bench/perft.rb`** + `rake bench:perft`: perft nps benchmark.
+- **CI**: `.github/workflows/native.yml` (`cargo test` + `rake compile` +
+  `rspec`) and `.github/workflows/release-gems.yml` (cross-compile
+  prebuilt platform gems via `rake-compiler-dock`).
+- **`PGN::Position#perft(depth)`** and **`PGN::Position#legal_moves`**
+  (sorted UCI): FEN-round-trip delegations to `PGN::Bitboard::Engine`
+  (`Engine.new(position.to_fen.to_s)`), so perft/legal-move enumeration is
+  available directly on a `Position` without building the `Engine` by hand.
+  `#legal_moves` is ~30 µs/call on a middlegame position, measured by
+  `bench/legal_moves.rb`. Both raise `NameError` if the extension is absent.
+- **`bench/legal_moves.rb`**: throughput benchmark for the `Position#legal_moves`
+  delegation (FEN build + `Engine.new` + native gen + string materialization).
+
+### Fixed
+- `attacks::init()` now initializes its attack tables through
+  `std::sync::Once` (was a bare `static mut bool` flipped under `unsafe` — a
+  data race / UB). No behavior change; `init()` remains idempotent. Removed the
+  three now-redundant per-method `attacks::init()` calls in the magnus binding
+  (`pgn2_native`), since the delegated crate functions self-initialize.
+
+### Distribution note
+
+This adds a **required compiled extension**. Release artifacts are
+**precompiled platform gems** (x86_64/aarch64, linux/darwin) built in CI;
+end users and the chessellence Docker build need no Rust toolchain. Interim
+source builds install Rust in the Docker build stage (see README). The
+pure-Ruby gem contract is otherwise unchanged; `PGN::Bitboard` is simply
+undefined when the extension is absent.
+
+---
+
+## 2.0.0 (2026-08-15)
+
+### Summary
+
+(Pre-release snapshot of the native Rust bitboard perft backend, before
+the small/medium roadmap and game-tree API work landed in 2.0.1.)
+
+---
+
+### Small + medium roadmap
+
+Small + medium TODO pass: public legal-move and outcome APIs on
+`PGN::Position`/`PGN::Game` delegating to the chessie engine, plus parsing
+and packaging hardening. Serialized PGN/FEN output stays byte-identical
+except where a task explicitly normalizes a quirk (nested comments are now
+escaped on output and unescaped on parse for stable round trips); 311
+specs green, RuboCop clean.
+
+### Added
+- **`PGN::Position#legal?(san_or_uci)`** and **`#legal_moves_san`**:
+  public legal-move API. `legal?` accepts SAN or UCI and resolves SAN by
+  matching `PGN::Notation.san` against the engine's legal moves (rejecting
+  ambiguous SAN). Raises `NameError` when the extension is absent.
+- **`PGN::Attack`** module + **`PGN::Position#in_check?`**, **`#attackers`**,
+  **`#mover_color`**, **`#opponent_color`**: attack detection extracted from
+  `Notation` private methods and exposed on `Position`.
+- **Game/position outcome detection**: `Position#checkmate?`/`#stalemate?`/
+  `#insufficient_material?`/`#fifty_move?`/`#outcome`, and `Game#threefold?`
+  (streams Zobrist hashes via `each_position`) / `Game#outcome`.
+- **`PGN::EPD`** read/write + **`PGN::FEN#to_epd`**: EPD shares FEN's first
+  four fields and keeps trailing operation fields verbatim.
+- **`PGN::Game#push(san)`** / **`#pop`**: mutable history; `push` validates
+  legality (raises `ArgumentError`) and invalidates the memoized position
+  list.
+
+### Changed
+- **`PGN::Move`**: parses `0-0`/`0-0-0` as castling (alongside `O-O`), so
+  UCI-style castling normalizes to canonical SAN through one path.
+- **Parser**: `tag_section` and `variation_list` are now ordinary
+  left-recursion with a single explicit `.reverse` (and first-occurrence-wins
+  tag merge) where each list is consumed; parse output is byte-identical
+  (same 2 shift/reduce conflicts).
+- **`MoveText#clean_text`**: idempotent — strips a single outermost brace
+  pair and unescapes `\{`/`\}`/`\\` into the canonical raw comment body, so
+  `Serializer` escaping and the lexer are symmetric and nested-comment
+  round trips are byte-stable. `Game#moves=` no longer sniffs comments for
+  leftover braces.
+- **`FEN#to_position`**: en passant square is no longer dropped (Ruby
+  conditional-assignment gotcha).
+- **Rakefile**: `Rake::ExtensionTask` now sets `cross_compile`/`cross_platform`
+  (single source of truth for `release-gems.yml`) and adds the `native:clean`
+  task that `native:gem` referenced.
+
+### Fixed
+- `FEN#to_position` en-passant round-trip regression (position lost the ep
+  square, which would have corrupted `legal?` and outcome detection).
+
+---
+
+### Attack masks
+
+Attack-mask pass: precomputed knight/king on-board target tables on
+`PGN::Board`, used by `Notation` (reaches/attacked/leaper moves) and
+`MoveCalculator` (knight/king origin lookup), plus a retained-memory
+benchmark section. No behavior change; serialized PGN/FEN stays
+byte-identical; all 226 specs green.
+
+### Changed
+- **`PGN::Board::KNIGHT_ATTACKS` / `KING_ATTACKS`**: new frozen 128-entry
+  tables mapping each 0x88 index to the frozen Array of on-board target
+  indices reachable by that piece (built once at load from the existing
+  offsets). Replaces the per-call `OFFS.any? { |o| from + o == to }` +
+  `(t & 0x88).zero?` off-board test with a direct array iteration.
+- **`PGN::Notation`**: `#reaches?` (N/K), `#knight_attacked?`,
+  `#king_attacked?`, and `#leaper_moves?` now iterate the precomputed masks
+  instead of offsets. `leaper_moves?` takes targets directly (no per-call
+  off-board test).
+- **`PGN::MoveCalculator`**: K/N origin lookup routes through a new
+  `leaper_origins` using `Board::KNIGHT_ATTACKS`/`KING_ATTACKS`; the pawn
+  path keeps the offset-based `move_origins`.
+- **Bench** (`bench/profile_moves.rb`): new section 8 (SAN generation
+  allocation + throughput) and section 9 (retained memory: lazy
+  `each_position` vs eager `positions`). Baselines refreshed.
+
+### Performance
+- **SAN generation** (`Notation.san` over the immortal game): throughput
+  **+8%** (334 → 361 ips, 2.99 → 2.77 ms/i) from a same-harness A/B
+  (pre-mask lib vs masks). Allocations unchanged (1387 objects) — the masks
+  only replace arithmetic + an off-board test, no new objects per move.
+- **Replay**: neutral. Same-harness A/B: 930 → 931 objects / +6720 bytes
+  with masks; throughput within noise. (The committed replay baseline
+  refreshed 976 → 931 objects, which is measurement-environment variance
+  between runs of identical pre-mask code, not an effect of the masks.)
+- **Retention** (new section 9): a caller that streams `each_position` and
+  keeps the `Game` retains 95 objects / 6280 bytes; a caller that calls
+  `positions` (memoizing the full array on the Game) retains 287 objects /
+  17232 bytes — ~3x less retained for the streaming pattern.
+
+## 1.5.0 (2026-08-13)
+
+Performance/internals pass: a direct 0x88 FEN builder, a lazy
+`Game#each_position` enumerator, and a lazily-computed Zobrist position
+hash with `Position#hash`/`#eql?`/`#==`. No public behavior change;
+serialized PGN/FEN output stays byte-identical; all 222 specs green.
+
+### Changed
+- **`PGN::Board#fen_board_string`**: new method that serializes the FEN
+  board-string portion by walking the 0x88 `@cells` array directly (ranks
+  8→1, files a→h, empty-run collapsing), instead of rebuilding the 8x8
+  `squares` array and transposing. `FEN#board_string` now delegates to it,
+  so every `position.to_fen` / `game.fen_list` call skips the 8x8 rebuild.
+  FEN output is byte-identical (the `board_string round-trip` spec pins
+  it). Measured (immortal game, 46 positions): 1913 objects / 100464
+  bytes for FEN generation; ~1.27k ips.
+- **`PGN::Game#each_position`**: new lazy enumerator (yields each
+  `PGN::Position` in order, or returns an `Enumerator` without a block);
+  `#positions` is now `each_position.to_a` with the same memoization.
+  Callers that only need the last position can stream without
+  materializing the full array. `positions` still returns the same
+  `Array`. Cost: one `Enumerator` per `#positions` call (parse+replay
+  for 500 games: +500 objects, throughput flat).
+- **`PGN::Zobrist`**: new module with a deterministic 64-bit Zobrist key
+  table (`table`/`side`/`castling`/`ep_file`) and a `seed(board, player,
+  castling, en_passant)` helper, generated once from a frozen seed so
+  hashes are stable across processes. Pure Ruby, no native deps.
+- **`PGN::Position`**: new `#zobrist` (the hash, computed lazily on first
+  access and cached), `#hash`, `#eql?`, and `#==`. Equality compares
+  board cells, side to move, castling rights, and en-passant square —
+  halfmove/fullmove counters are ignored, matching threefold-repetition
+  semantics. The hash is lazy: the replay hot path (which never asks for
+  it) pays nothing (replay stays at 976 objects / 62064 bytes,
+  byte-identical to 1.5.0); consumers pay one full seed on demand. An
+  incremental per-move update was prototyped and rejected: 64-bit
+  Integer XOR allocates a new `Bignum` per operation (~9 per move),
+  which regressed replay by +40% allocations / −32% throughput for a
+  feature nothing currently consumes — laziness keeps the public API
+  with zero hot-path cost.
+
 ## 1.5.0 (2026-08-13)
 
 ### Summary

data/Gemfile

@@ -2,3 +2,6 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in pgn.gemspec
 gemspec
+
+gem 'rake-compiler', '~> 1.2', group: :development
+gem 'rb_sys', '~> 0.9.39', group: :development

data/NOTICE.md

@@ -0,0 +1,21 @@
+# Third-Party Notices
+
+This gem bundles a compiled Rust extension (`pgn2_native`) that links
+the `chessie` crate.
+
+## chessie
+
+- Source: https://crates.io/crates/chessie
+- Repository: https://github.com/duck2/chessie
+- Version: 2.0.x (see `ext/pgn2_native/Cargo.lock` for the exact pinned
+  version)
+- License: Mozilla Public License 2.0 (MPL-2.0)
+
+`chessie` and its dependency `chessie_types` are MPL-2.0. They are used
+unmodified. The MPL-2.0 license is file-level copyleft: it applies to
+`chessie`'s own source files only and does not change the license of
+this gem's code (MIT). Per MPL-2.0 §3.3, the source of the MPL-licensed
+files is available at the repository URL above (and is reproducibly
+pinned in `ext/pgn2_native/Cargo.lock`).
+
+pgn2's own code remains MIT-licensed; see `LICENSE.txt`.