app/puzzle_book.h

the puzzles that ship on the board (lichess PLAN.md §2, L5).

Lichess can revoke API access at their discretion, and a living room can lose its Wi-Fi at any time. So the board carries its own puzzles: a subset of the CC0 Lichess puzzle database, built by kirin/tools/make_puzzle_book.py and installed as a data file. This is what makes the Lichess link a sync upgrade rather than the feature itself — the promise PLAN §2 makes and this class keeps.

Three things worth knowing about it:

  1. IT NEEDS NO ENGINE, WHICH IS WHY THE BOOK’S FORMAT IS NOT THE DATABASE’S. Reading a raw Lichess CSV row means applying the opponent’s ply to its FEN (PLAN §3.2), and applying a move means the engine — whose state lives in globals owned by the session’s worker thread (linked_engine.h). Serving a puzzle happens on the UI thread, so it must not touch the engine at all. The tool therefore does the ply reconciliation once, at build time, and the shipped book is already in the solver-to-move convention: parseBookRow is a pure string parse. parseDatabaseRow (puzzle.h) still exists for a raw dump and still takes an engine; the two formats are deliberately different files so neither can be mistaken for the other.

  2. IT AIMS AT THE PLAYER. Linked, Lichess picks the difficulty for us (its difficulty parameter is relative to the player’s own puzzle rating). Unlinked, nothing does — so the book serves from a band around the KIRIN puzzle rating (player_rating.h), which exists for exactly this: “aiming the opponent” with no account and no network. A board that hands a beginner a 2400 puzzle is a board they stop using.

  3. IT REMEMBERS. A book is a few thousand puzzles and a solver will play a lot of them; being handed one you solved last week is the thing that makes a local library feel small. Seen ids are persisted alongside the rating file and skipped, until the band is exhausted — at which point repeating a puzzle beats refusing to show one.

Pure: no Qt, no HTTP, no hardware. Runs in the CTest suite.

namespace kirin
class PuzzleBook
#include <puzzle_book.h>

Public Functions

explicit PuzzleBook(std::string path = "", std::string seenPath = "")
inline bool loaded() const
inline size_t size() const
inline const std::string &path() const
std::vector<Puzzle> nextBatch(int targetRating, int count)
void markSeen(const std::string &id)
inline size_t seenCount() const
void forgetSeen()
inline void setSeed(uint64_t seed)

Public Static Functions

static std::string defaultPath()
static std::string defaultSeenPath()

Public Static Attributes

static constexpr int kBandStep = 100
static constexpr int kMaxBand = 600

Private Functions

void load()
void loadSeen()

Private Members

std::string path_
std::string seenPath_
std::vector<Puzzle> puzzles_
std::unordered_set<std::string> seen_
std::mt19937_64 rng_