Building Codeword: The Solver
After building Anarchy Chess, I wanted a daily word game to pair with it and landed on Codeword. A codeword starts with an open 13x13 crossword grid (around 120 white squares) with all of the clues removed. Instead, every white square carries a number from #1 to #26. Those numbers form a 1-to-1 substitution cipher for the alphabet: each number stands for one distinct letter from A to Z, all 26 letters appear somewhere on the grid, and typing L onto #2 fills every #2 square across the board.
Only two to four starter letters are revealed at the start, so cracking the rest is all about spotting word patterns and crossing letters. Under the hood, the Go CSP solver builds each day’s grids, checks that a human can deduce all 26 letters step by step without guessing, proves no second solution exists, and powers hints.
Modeling a codeword as a CSP
In the crossword builder, each Across or Down word is a variable over dictionary words of that length, and two words only interact when they cross on a shared square. Codewords break that locality: every #5 square has to take the same letter whether two #5 squares sit inside the same word or on opposite corners of the board, while #5 and #12 can never share a letter even if their words never touch.
Going the other way - creating only 26 variables for #1 through #26 over A to Z - makes the 1-to-1 alphabet rule trivial, but checking dictionary words across many letter variables at once would be much less efficient to propagate (and I didn’t want to build custom multi-variable word constraints for it).
Keeping both sets of variables makes every constraint small and fast:
- 26 number variables (
#1through#26, each tracking live letters A to Z), tied together by a single bipartite all-different constraint so maximum matching immediately catches impossible letter squeezes, such as three numbers narrowed down to the same two letters. - One word variable per Across or Down word, restricted up front to dictionary words that match the pattern of its numbers. For instance,
[10, 7, 3, 1, 4]requires five distinct letters (matching “crane”, skipping “apple” and “sleet”), while[3, 5, 5, 2, 4]requires identical 2nd and 3rd letters with the other three distinct - so only five-letter words with that exact pattern, like “alley”, “apple”, or “otter”, enter its domain before search even starts.
Wiring each word directly to the number variables inside its cells buys two nice simplifications over a standard crossword model. First, word-to-word crossing constraints disappear completely: whenever two words share #2 or #4 - whether they intersect on that square or sit in separate corners of the grid - both words link to the same #2 and #4 variables, keeping the entire board in sync through the numbers themselves. Second, a repeated number inside a word only needs one link: in [3, 5, 5, 2, 4], #5 only links once, since every candidate in that word’s pattern-filtered list already has matching 2nd and 3rd letters.
Each pattern-filtered word list builds the same precomputed per-position []uint64 letter bitmasks (ByPosAndLetter) from bitmask propagation, so each link between a word and a number propagates cleanly in both directions:
- Number to word: locking
#3to A clears every candidate without A in that position in a single bitmask pass. When#3still has several possible letters under arc consistency, it uses the same shortcut as crossword overlaps - either pruning words with ruled-out letters or keeping words with still-allowed letters, whichever scans fewer bitmasks (at most 13). - Word to number: when candidates are pruned from an unassigned word, each linked number checks whether any surviving candidate still uses each of its remaining letters (testing
liveBits & mask != 0, just like before), dropping any letter that lost its last supporting word.
Right before constructing the full CSP, the solver runs a quick up-front pass over 26-bit uint32 letter masks, alternating word-list filtering with single-letter and two-letter pair eliminations (if two numbers narrow down to {Q, Z}, no other number can take Q or Z). That pass shrinks the candidate lists and bitmasks handed to the solver, and on a well-seeded board it often resolves nearly the whole alphabet on its own. The full CSP with bipartite all-different and backjumping earns its keep during uniqueness proofs, when a candidate board with only two starter letters has to be searched exhaustively against 85,000 words to make sure no second solution hides anywhere.
Generating daily puzzles that feel fair to humans
Each day needs three 13x13 puzzles - Easy, Medium, and Hard - built on 180-degree symmetric grids (~120 white squares across ~28 words, each at least four letters long) where all 26 letters appear on the board:
Filling a 26-letter grid from everyday words
In a regular crossword, a clever clue can rescue an obscure word. In a clue-less codeword, running into unfamiliar crossword filler or proper nouns feels unfair because letter patterns are all you have. To keep grids recognizable, the generator builds tiered word lists by combining word-quality scores with how often a word appears across eight mainstream newspaper crosswords and whether it belongs to a normal English word family (-s, -ed, -ing, and so on), dropping proper nouns along the way. Easy pulls strictly from household words, while Medium and Hard widen the vocabulary slightly.
Left to its own devices, filling a 13x13 grid from common words packs the board with friendly vowels and consonants, leaving out Q, Z, J, or X almost every time. Rather than inventing a global constraint to count distinct letters across the whole grid, the generator picks six distinct random words before starting search, assigns one of Q, Z, J, X, K, or V to each word, and prunes every candidate from that word’s domain that doesn’t contain its assigned rare letter.
Each fill attempt then runs a 75ms branch-and-bound search favoring higher-scoring words, with exponential restarts. On the rare attempt where a completed grid dodges a mid-frequency letter like W or B, the retry loop tacks any missing letters onto the required list for the next try. Once all 26 letters land on the board with no duplicate words, a random shuffle maps A through Z onto #1 through #26.
Simulating a human to pick starter letters
Picking which starter letters to reveal turned out to be the trickiest part. Just like raw solution count in Anarchy Chess, the solver’s own propagation is a terrible yardstick for human difficulty. Arc consistency happily intersects 4,000-word candidate lists across completely blank rows to deduce letters before a single word is readable. Humans don’t intersect dictionary lists across blank words in their heads - and going too far in the other direction, like giving away E, can pre-fill 20+ squares at once and make the entire board snowball on turn one.
Instead, candidate starter sets are graded by a step-by-step human solve simulator:
- A round may only deduce letters from words that already have at least one known letter on the board, so deductions have to spread outward from visible footholds rather than jumping across blank regions.
- A partially filled word only yields new letters when the surviving candidates in that tier’s dictionary narrow down to a single word on Easy and Medium (or at most two words that agree on a letter on Hard), plus the free 26th letter once 25 are placed.
To guarantee a fair foothold, at least two starter letters are clustered inside a familiar 4-to-7-letter opening word while targeting tight caps on how many of the ~120 white squares start pre-filled:
- Easy reveals 4 starters (1 non-E vowel and 3 consonants), targeting at most 20 pre-filled squares and at least two immediate single-match opening words.
- Medium reveals 3 starters (2 in an opening word plus 1 consonant elsewhere, never E or two vowels), targeting at most 14 pre-filled squares so roughly 88% of white squares start blank.
- Hard reveals just 2 consonant starters sharing one opening word, targeting at most 8 pre-filled squares (~93% blank) with at least one single-match opening word before widening to 2-word steps.
Proving uniqueness against an 85,000-word dictionary
Even when the human simulator solves all 26 letters cleanly inside its tier list, a freshly filled grid is not guaranteed to have only one valid solution overall. Suppose #17 only appears once on the board in _UMP and #23 only appears once in _ADE: unless a starter letter pins one of them down, #17=J, #23=B (“jump” and “bade”) and #17=B, #23=J (“bump” and “jade”) are both completely valid 26-letter solutions.
Every candidate starter set therefore locks its starters into the full CSP and searches for up to two solutions (with a 120ms cap), rejecting the starter set the moment a second valid mapping turns up - and discarding the entire grid if no starter set can make it unique. Testing uniqueness against the 10,000-word Easy list wouldn’t be enough either, since a player might spot a valid English word outside that smaller tier that completes a second swap, so this check always runs against a broad ~85,000-word verification dictionary.
To keep my tiny E2 micro VM happy, the server pre-generates a rolling 7-day window of these daily sets in the background, and ships only a SHA-256 hash of the 26-letter mapping to the browser so wins verify locally without exposing the answer in DevTools.
Hints: clearing bad guesses and picking useful reveals
In Anarchy Chess, most puzzles have dozens of valid solutions, so every hint click has to re-solve from the player’s current board. Codewords get a nice payoff from the uniqueness proof done during generation: because every puzzle has a single valid 26-letter solution, any placed letter that disagrees with it is guaranteed to be a dead end.
That lets live hints follow a corrective-first, constructive-second flow with zero search overhead:
The UI already stops you from typing the same letter onto two different numbers (flashing the existing square instead, with the backend rejecting duplicate-letter payloads outright), so a board can never have duplicate-letter clashes. You can still easily put an unused letter onto the wrong number, though - say guessing R on #12 when #12 is actually T. Revealing #8 = R on top of that would collide with #12, and leaving #12 = R in place lets bad crossings pile up anyway. Whenever any placed letter disagrees with the solution, the hint takes the corrective path first and flags a wrong number to clear.
Once every placed letter on the board matches the solution, the hint switches to the constructive path and reveals one unassigned number. Picking at random can reveal a lone Z at the end of two blank words and leave you just as stuck, while blindly picking the most frequent number dumps a 20-cell E across the board and spoils half the puzzle.
Instead, each unassigned number is scored by combining a capped cell-count bonus (2 points per occurrence, capped at 6 cells = 12 points) with a completion bonus for every word containing that number that already has at least one letter filled in:
+20if it is the last missing letter in that word, finishing it on the spot.+12if 2 blanks remain, turning an almost-there word into an easy 1-blank finish.+4if 3 or more blanks remain in a word you’ve started.
Capping the cell-count bonus at 12 points ensures finishing a 1-blank word (+20) always beats dumping a 20-cell E onto untouched words, steering hints toward finishing a word you’re actively working on so its crossings open up naturally.
Wrapping up
Codeword ended up being a rewarding test of how reusable the solver’s building blocks really were. Pre-filtering words by number pattern let the model reuse the exact []uint64 letter bitmasks from the crossword builder without needing crossing constraints, bipartite all-different over the 26 numbers kept broad uniqueness checks fast, and pairing curated generation word lists with an 85,000-word verification dictionary kept clue-less grids fair without leaving second solutions open.
I skipped over the frontend, daily archive, and leaderboard setup here to keep the focus on the solver side. If you want to give today’s puzzles a try, they’re up at dawnofthe.dad/codeword, and thanks for reading!