The opening book skips moves. I built an opening trainer on it anyway.

I want EloCoach to tell you where you leave opening theory, and then let you practise the move you should know. That sounds like one lookup: is this move in the book, yes or no. It took me two attempts to find out that “in the book” is a much less obvious question than it looks, and the first answer I shipped to my own branch graded real Ruy Lopez theory as a miss.

Where the book comes from

The list is the open one from Lichess (the chess-openings repository, public domain). Each entry is a named line: an ECO code, a name like “Ruy Lopez: Morphy Defense”, and the moves. I turn each line into the position it ends in and key everything on the position, not the move order. That matters because openings transpose all the time: 1.Nf3 d5 2.d4 and 1.d4 d5 2.Nf3 are the same Queen’s Gambit position, and a matcher that compares move lists would call one of them an early exit.

That gives about 3,800 named positions. It is enough to say how deep a game stayed in named theory, which is all the coach needed so far. The trainer needs more: for any position, which moves are book moves?

The obvious tree, and why it was wrong

The obvious answer is a book move is any legal move that lands on a named position. I built that, wrote tests, watched them pass, and moved on. Then an independent review of the whole branch tried the Ruy Lopez main line and I reproduced what it found.

The dataset names a position when a line ends there, and a lot of the positions on the way to a named line are not themselves named. Walking from the start position using only named steps, I could reach 1,168 of the 3,815 named positions. The rest were unreachable because the road to them passed through an unnamed square. So a player who knew the Ruy Lopez perfectly would have been told 4.Ba4 is not in the book, and the leak detector would have flagged the main line as “where you left theory”.

The fix: a tree that includes the way there

A move is a book move if it lies along a named line, whether or not the square it lands on has a name. To build that I needed the move lists, which I had thrown away when I kept only the end positions. A second generated file keeps all 3,865 lines, and a third is the tree itself: 7,983 positions and 8,192 moves, merged by position so transpositions are still one node. Opening theory is fixed, so that tree is checked into the repository as data rather than worked out by the server, and the dataset it comes from is pinned to one commit so regenerating it gives the same bytes. A test rebuilds the tree from the lines and fails on any difference, and another replays every one of the 3,865 lines and checks that each move is a book move, that playing a line to the end is never reported as leaving theory, and that a real exit is never itself a book move. The Ruy Lopez walk that exposed the bug is now one case among all of them.

What “in the book” still does not mean

• It does not mean best. The list names lines, it does not say which move scores well.
• It does not mean popular. There are no game counts in it, so I order the moves by how far theory continues, which is a different thing from how often they are played.
• Leaving the book is not a mistake. Only a game that an engine has reviewed can say an exit cost something, and on my test account that is about 6 percent of games. Everything else says “you left named theory here” and nothing more.
• It starts too early to mean anything. The list names every legal first move, so the trainer ignores everything before the third move.

What it finds on a real account

On one account with 529 games, the corrected tree finds 63 positions worth practising and 20 places where the player steps out of theory, 35 times in all. The most repeated one is a King’s Gambit line: after 1.e4 e5 2.f4 exf4 3.Nf3 Nc6 the player chose 4.d4 six times, where the book continues with 4.Nc3 or 4.Bc4. That is a specific, checkable fact about a specific move, which is the whole point.

What I am still unsure about

The trainer is the next thing to ship on top of this. The part I would not trust without this episode is the claim that something is “in the book”, and the lesson I am keeping is to test against a line I know by heart, not only against the cases I thought of while writing it.