How puzzles are generated and verified unique

The finished puzzles are stored in files, and an automated check re-solves every stored puzzle before each release, failing the build if any has more or fewer than one solution. “Verified unique” on this site means that check passed, nothing more.

Where do the puzzles come from?

All puzzles are generated by the site’s own code. None are copied from other sites, books or puzzle collections. The generator is a script that runs on the developer’s machine and writes its output into data files. Nothing is generated in your browser or on the server while you play. When you start a game, the page loads a file of ready-made puzzles for the level you picked and chooses one.

The generator is deterministic. It uses a seeded random number generator (a small algorithm called mulberry32) and never the browser’s built-in random function, so the same seed always produces the same puzzle. That makes any stored puzzle reproducible, and it makes the generator testable.

Step 1: how is a complete grid made?

A Sudoku puzzle is a finished grid with most of the digits taken away, so the generator starts with a finished grid. It does this by running the solver on an empty board with the digit order shuffled. The solver tries a digit in an empty cell, moves on, and backs up when it hits a dead end. Because the digits are tried in random order, each run ends at a different valid grid. A cap on the number of search steps stops a run that wanders for too long, and the generator simply starts over with the next seed.

A caveat on randomness: shuffling the digit order at each step does not pick grids with equal probability from all possible grids. The result is varied and valid, but this page does not claim it is a uniform sample of every grid that exists.

Step 2: how are clues removed?

The generator lists all the cells in random order and visits them one by one. For each cell it blanks the digit and asks two questions about the resulting puzzle.

1. Does the puzzle still have exactly one solution?
2. Can the technique solver still finish it using techniques no harder than the target tier?

If both answers are yes, the clue stays removed. If either is no, the digit goes back. When every cell has been visited, no further clue can be taken out without breaking one of the two conditions, so the puzzle has no spare clues for its target level. There is one more rule: if the uniqueness check runs out of its step budget before it can decide, the removal is rejected, because an unfinished search proves nothing.

How does the solution counter prove uniqueness?

The first question depends on a bounded solution counter. It is a backtracking solver with two features that matter.

• It picks the most constrained cell first. At each step it looks for the empty cell with the fewest digits still allowed and branches on that cell. If some cell has no allowed digits, the branch is a dead end and is dropped at once. A cell with exactly one allowed digit is taken immediately. This keeps the search small even on sparse puzzles.
• It stops at two. To prove a puzzle is unique you do not need to know exactly how many solutions it has. You need to know whether the number is exactly one. The counter therefore stops as soon as it finds a second solution. Finding one solution and then searching the rest of the tree without finding another proves uniqueness. Finding two proves the puzzle is not unique.

The counter also rejects puzzles whose givens already contradict each other, such as two equal digits in one row, by reporting zero solutions. Its tests include a known textbook puzzle with a known single solution, and an empty grid, where it must report that there are multiple solutions and stop at the limit. The textbook fixture lives in the test files only and is never shipped as a puzzle.

Step 3: how is a puzzle graded and stored?

When carving is finished, the puzzle is solved once more by the technique solver with every technique available. The hardest technique it needed sets its level, as explained in how Sudoku difficulty is graded. The target tier used during carving is only an aim. The puzzle is stored under the level it actually earned. The generator aims at whichever level currently has the smallest pool, skips puzzles that duplicate one already collected, and discards puzzles that land in a pool that is already full.

Each stored puzzle is a short record: the 81-character puzzle string with a dot for each blank, the number of clues, and the list of techniques used. For the 16×16 board the record also stores the solution, so the browser never has to search for it. Puzzle files live in data/puzzles, one file per variant and level, and each file is loaded only when a player picks that level. The technique frequency guide is built from those records.

What is checked before each release?

The generator is not trusted on its own. A separate script, scripts/verify-puzzles.ts, runs as part of the continuous-integration gate and re-checks every stored puzzle from scratch.

• It runs the solution counter and requires a count of exactly one.
• It runs the technique solver again and requires that the grade equals the level the puzzle is filed under.
• Where a solution is stored, as in the 16×16 pool, it requires that it equals the one the solver finds.

Any failure makes the build fail. When this guide was written, the script ran over every pool on the site and reported 10,074 puzzles verified with 0 failures; that figure grows if the pools do. The check covers all stored puzzles and not a sample, which is why the site is able to say its puzzles are verified unique. The statement is about the stored files and the site’s rules. It is not a claim about any puzzle you may find elsewhere.

How can the same puzzle appear in different disguises?

A pool has a fixed number of puzzles, so to add variety the game applies a transformation before showing one. A transformation changes how a puzzle looks without changing its logic. On a plain classic board it can relabel the digits, swap bands of three rows or stacks of three columns, swap rows within a band, swap columns within a stack, and transpose the grid. All of these keep the puzzle valid, keep it uniquely solvable, keep the number of clues, and keep its grade, which the unit tests check on randomly generated puzzles for the classic, 6×6, 4×4, diagonal and anti-knight setups.

Boards with extra constraints, such as the diagonal or irregular boards, cannot use row and column moves safely, so they get digit relabeling only. Killer puzzles can have their structure moved, but their digits cannot be relabeled, because the cage sums depend on the digits.

This is honest variety, not unlimited new puzzles. The moves are the same symmetries that mathematicians use to count grids, explained in Latin squares and the math behind Sudoku. A transformed puzzle is the same puzzle underneath, and two players can in principle receive disguised versions of one stored puzzle. A solver with a good memory for patterns of givens might recognize one. The pools are the number of distinct puzzles the site holds: 1,000 per level for classic, and fewer for the variants.

How do the variants change the steps?

The three steps are the same everywhere, but some variants add a preparation step first. For the irregular board the generator first draws a random map of nine jigsaw regions and builds the grid to fit it. For killer Sudoku it fills an ordinary grid first, then divides the board into cages and computes each cage’s sum from the finished grid, so the sums are always consistent with at least one solution. The solution counter then makes sure there is only one. Diagonal, hyper and anti-knight boards add their extra constraints to the geometry the solver uses, which means both the grid and the uniqueness check follow the variant’s own rules.

The 16×16 board has its own setting. Capped carving on a board that size is slow, so the script keeps a minimum number of clues while carving: 120 for the Easy level and 110 for Medium. Those puzzles are still checked for exactly one solution and graded the usual way. They simply start with more clues than a 9×9 puzzle would.

Why generation runs offline

Searching for a unique, graded puzzle is expensive. The cost depends on the board, the variant and the target level, and it can be large. The site’s notes record that a Hard 16×16 puzzle takes close to two minutes to generate. Doing that on a phone would freeze the page, so it never happens on a player’s device or on the request path. The generator script accepts a time budget and writes whatever it has found when the time runs out, which is how rarer levels are handled.

What does “verified unique” not promise?

• It is not a quality rating. A unique puzzle can still be dull or tedious. Uniqueness is a correctness property.
• It is not a difficulty guarantee beyond the site’s method. The level reflects the techniques in this site’s solver and nothing else.
• It is not novelty. The puzzles are generated, then transformed, and may resemble puzzles elsewhere.
• It depends on the rules. Uniqueness is checked under the rule set of each variant as the site defines it.

Run it yourself

The scripts are ordinary Node programs. Generating a pool for a variant is a single command, node scripts/generate-puzzles.ts classic 50, where the last number is how many puzzles to produce per level. Re-checking everything stored is node scripts/verify-puzzles.ts. If you want to write the core of the counter yourself, the TypeScript solver tutorial builds a smaller version step by step. To see a graded puzzle in action, play one on the home page or try the daily Sudoku, and find more tutorials on the guides hub. If you are learning to solve, the naked singles lesson is the first step on the techniques the grader uses.