902 xiangqi mate problems, eight old books, and the problems I left out

Xiangqiful has 902 mate problems, and every one is a consecutive-check mate (连将杀). Red must check on every move until the black general is mated, and Black always picks the reply that lasts longest. I composed 194. The other 708 come from eight classical manuals, transcribed position by position and line by line. Each book line was then proved by the app’s own solver. None was edited to pass, and a book problem that failed is not in the app.

The whole corpus, by source and by depth:

How much of each book made it in:

Depth is counted in plies, single moves by either side. Mate in 3 means Red, Black, Red. That is how the app labels its tiers, and it is how tsume problems are counted in shogi. A chess book would call the same problem mate in 2.

What the genre demands

Xiangqi’s native puzzle has the same constraint as tsume-shogi. That is why the solver in Xiangqiful started as a port of the one in Shogiful. It has two rules. Every attacker move must give check. The defender plays the longest defence, so the line a problem records is the one that survives longest, even when a shorter one turns up first.

Xiangqi adds a trap that shogi doesn’t have. A player with no legal move loses, so a quiet final move that leaves the general stranded wins a real game, but it is not a consecutive-check mate. The solver checks that the defender is in check before it counts his replies, and it only accepts a line that ends in checkmate. A straight port of the shogi solver would get this wrong, and it is the first thing the comments in that file warn about. Stalemate as a loss is one of several xiangqi rules that reverse a chess habit; the rules guide for chess players covers the rest.

152 problems was not enough

The app was first going to ship only problems I composed. By early September there were 152 of them: 60 mate-in-1 and 92 mate-in-3. The mate-in-5 and mate-in-7 sets were planned but empty. A Premium player on the long daily session would have seen every unseen problem in 19 days and then started getting repeats. Shogiful had already taught me what that costs. A one-star review there said that with only a few hundred problems, you end up memorising them.

Composing more only went so far. The composer is a generator, and a candidate survives only if it passes a strict bar. Red must have at least two checking moves, and exactly one of them forces mate. Every red piece except the general has to be load-bearing, so removing any one of them destroys the problem. The defender must keep pieces near his general and at least six legal replies. No two problems may share a position or its mirror image. One more run per depth brought the originals to their final 194. The generator only composes mate in 1 and mate in 3, so it could never fill the two empty sets. The deep problems already existed, in books.

Eight books, 2,208 positions

I transcribed eight pre-1900 public-domain manuals from the digital editions on xqdao.com. Each problem became a starting position and the book’s main line, in the notation the app’s rules engine reads. That came to 2,208 positions. 837 of them are draws by the book’s own verdict, 66 are wins for Black, and 87 carry no verdict at all. That left 1,218 the books score as wins for Red.

Most of those don’t fit a mate-in-7 ceiling. The median main line among the 1,218 is 13 plies, the longest is 74, and only 195 are seven plies or shorter. So the import works from the end of the line. For each book problem it tries the whole problem first, then the position the book’s line reaches 7 plies before the mate, then 5, 3, and 1. It keeps the longest version that passes, and it never keeps more than one per book problem.

That is why every book problem carries one of two kinds of credit. A whole-problem credit means the book’s own diagram and main line, unchanged; only 36 problems are used whole. An ending credit means the problem starts partway through the book’s line, and 672 problems are endings. For example, the Shiqing Yaqu’s first problem has an 11-ply main line. Xiangqiful’s first mate-in-7 starts from the position after the book’s fourth ply and plays the book’s last seven moves exactly. The other 194 problems are credited as originals, and none of them is attributed to any collection.

The book was not corrected to make a problem fit

That sentence is written into the source notes of every problem set, and the import works by it. A book position and line ship only if all of these hold:

• The book claims a win for Red. Draws and Black wins are never imported.
• Every piece stands where a game could have put it, neither side starts in check, and the line replays legally.
• The book’s key move holds against every reply. Books record one defence, and the solver plays out every reply the book leaves out. If any reply escapes, the problem is out.
• The solver accepts the book’s line at the book’s depth. Every attacker move checks, the line ends in checkmate, no shorter mate exists, and exactly one first move wins.
• No later move has a twin. At every Red move along the book’s line, and along every defence the solver added, the recorded move must be the only one that still mates in time. During a problem the app accepts only the recorded move, so a second mate would mark a player’s correct answer as wrong.
• It isn’t already in the corpus, in either mirror image.
• A slow phone can re-prove it. The solver’s work is capped at 8,000 search nodes, which keeps each problem inside the device’s two-second budget.

There is no step where a failing line gets patched. The import doesn’t swap in a better key move or move a piece to remove a dual. When a book problem fails, the importer moves on to a shorter ending of the same problem. If no ending passes, the problem doesn’t ship. 708 of the 1,218 Red wins produced a problem; the other 510 produced nothing the app would ship. Not all 510 are broken, since the same gate also turns away sound problems, such as one a phone would take too long to re-prove, or one already in the corpus as a mirror image. The counts above are the real yield either way.

The Juzhongmi line in the table shows the effect. Of its 181 transcribed positions, the book scores only 42 as Red wins, and five survived.

Checked twice, by the same code

The validator runs twice: once when a problem is written into the app, and again on your device the first time the problems are loaded, before any problem reaches the puzzle database. Both runs use the same code, so the gate that admitted a problem and the gate that loads it can’t drift apart.

The second pass is there because a change to the rules engine can break a problem that used to be sound without anyone noticing. If that happens, a player should get a smaller corpus and never a board they can’t solve. A rejected problem never reaches the database. If an entire depth set fails, the app treats that as a shipping error and stores none of it. Mate-in-1 and mate-in-3 problems are checked during launch, and the deeper two sets in the background. Each problem gets two seconds.

When the validator later gained the twin check along every line, I re-ran all 902 shipped problems through it. None was rejected, and the run took about 1.7 seconds in an optimised build. The test suite proves the whole bundled set again on every run. It’s the same idea as proving Millrace’s levels in the test suite: a problem that stops passing should fail by name before it can reach a player.

How the problems reach you

The problems live in Mate Trail, one of Xiangqiful’s nine drill modules. The hub lists one row per depth, mate in 1, 3, 5, and 7, with how many you’ve solved in each. A session opens with “Find the mate. Every move must give check.” You play Red’s moves and the app answers with Black’s. Black’s replies come from the problem’s recorded lines, so the board never stops responding partway through.

Problems you miss come back through spaced repetition. The session header marks a returning problem as a review due today, or, once the unseen ones run out, as seen before with no new problems left. There’s no credit line under the board; the source lives on every problem in the data instead.

The first problem a new player sees comes from the books. During setup, before any trial offer, the app asks you to solve the last move of Lanke Shenji #46, a chariot mate with seven pieces on the board.

Mate Trail is separate from the exercises Xiangqiful cuts from your own analysed games. Nobody has screened those positions for a second mate. So when the answer to one of them is a mate in one, the app accepts any mating move, not only the one it recorded.

The free tier includes three training puzzles a day, and mate problems count toward that. Premium removes the limit for $1.99 a month or $9.99 a year, each with a 7-day free trial, or $19.99 once. Everything runs on your device on iPhone, iPad, and Mac, with no account. The app page has the rest: 40 opponents, Pikafish analysis, 80 lessons, and more than 150 drills. A Shiqing Yaqu problem from 1570 is in the app only because a solver confirmed what the book says.