# Fairy-Stockfish adoption record

**Decision date:** 2026-07-22  
**Status:** Adopted and integrated for the Xiangqi browser opponent; final smoke test in a cross-origin-isolated browser is required before release  
**Package:** `fairy-stockfish-nnue.wasm` 1.1.11  
**License:** GNU GPL version 3.0

## Why this engine

The previous handcrafted browser AI was too shallow for a satisfying Xiangqi game. Fairy-Stockfish supports Xiangqi and provides an NNUE-enabled WebAssembly package suitable for local, browser-side analysis.

## Exact upstream sources

- Engine/WASM source: <https://github.com/fairy-stockfish/fairy-stockfish.wasm/tree/nnue>
- Core engine source: <https://github.com/fairy-stockfish/Fairy-Stockfish>
- npm distribution: <https://www.npmjs.com/package/fairy-stockfish-nnue.wasm/v/1.1.11>
- GPLv3 text: <https://www.gnu.org/licenses/gpl-3.0.en.html>

## Vendored files

`assets/games/xiangqi/vendor/fairy-stockfish/` contains the exact package JavaScript and WebAssembly payload, its package manifest, GPL license text, and author notices.

## Verification recorded

The game validates every engine response against its local Xiangqi rules before applying it, and falls back safely when the engine is unavailable. The browser embedded in this development environment does not expose `SharedArrayBuffer`, so it cannot be used as the final threaded-WASM smoke test. Use the header-enabled local server below in a normal modern browser before release.

## Required response headers

This NNUE build uses WebAssembly threads and therefore requires `SharedArrayBuffer`. The game host must send both of these headers on the Xiangqi page and its engine assets:

```text
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

`scripts/serve-local.js` is the local server used for verification and sends these headers. Without them, the game deliberately falls back to its small built-in legal-move opponent rather than failing the game. Configure equivalent headers in production before expecting Fairy-Stockfish to be active.

## Release obligations

Before publishing a build that serves the engine files to visitors:

1. Keep the engine copyright notices and `COPYING.txt` available.
2. Add a visible credits/license link to this file and the upstream sources.
3. Offer the matching source for the exact engine build at no charge. The above upstream tag/package link is sufficient only while it exactly matches the shipped files and no engine changes are made.
4. If the engine or its build configuration is modified, publish the patches and build instructions under GPLv3 alongside the release.
5. Review the final distribution with legal counsel if the surrounding game code becomes tightly coupled with the engine.

The game’s article content, artwork, analytics configuration, and advertising account are not part of the engine distribution.