The Puzzle set loaded on every stack #442

New issue

Closed

opened 2026-10-16 08:19:40 +00:00 by root · 6 comments

root commented

2026-10-16 08:19:40 +00:00

(Migrated from gitlab.core-project.space)

Parent

#440

What to build

Every stack holds the same set of Puzzles, loaded by one idempotent command.

The Puzzle table and its committed migration (ADR 0031): Lichess id as key, FEN, solution line (UCI), rating, rating deviation, Themes as an array indexed for containment, an index on rating.
The sampling script, kept in the repo: reads the Lichess puzzle dump (CC0), keeps about 50,000 Puzzles so that each curated Theme has a few hundred in each 200-point band, checks every line with the engine (the FEN parses, every Move is legal in turn) and drops any that fails, and writes the sample gzipped.
The committed sample it produced.
The loader: an idempotent db:puzzles command in the API that upserts the sample by Lichess id. Puzzles are product data, not demo data: it runs outside the devtools gate (ADR 0039), next to the migrations in every stack's deploy, and in the e2e stack.
The curated Theme list (the 20 Themes named in #440) as a constant the contract and the front can share later.

Lichess lines are stored as they are: the FEN is the position before the opponent's Move, and the line's first Move is the opponent's.

Seam: S1 (the API on in-process Postgres; the loader run first, as the demo seed test does). Covers stories 49-50 of #440.

Acceptance criteria

The migration creates the Puzzle table with its indexes; the migrations test passes.
A test loads a small fixture set twice and finds each Puzzle once, with its fields unchanged.
A test shows the loader refuses or skips a line the engine rejects.
The committed sample loads in full on a fresh database.
The deploy of every stack runs the loader after the migrations; the e2e stack has Puzzles.
The sampling script's use is documented where the other scripts are.
The gate is green (CONTRIBUTING.md, "The five commands").

## Parent #440 ## What to build Every stack holds the same set of Puzzles, loaded by one idempotent command. - **The Puzzle table** and its committed migration (ADR 0031): Lichess id as key, FEN, solution line (UCI), rating, rating deviation, Themes as an array indexed for containment, an index on rating. - **The sampling script**, kept in the repo: reads the Lichess puzzle dump (CC0), keeps about 50,000 Puzzles so that each curated Theme has a few hundred in each 200-point band, checks every line with the engine (the FEN parses, every Move is legal in turn) and drops any that fails, and writes the sample gzipped. - **The committed sample** it produced. - **The loader:** an idempotent `db:puzzles` command in the API that upserts the sample by Lichess id. Puzzles are product data, not demo data: it runs outside the devtools gate (ADR 0039), next to the migrations in every stack's deploy, and in the e2e stack. - The curated Theme list (the 20 Themes named in #440) as a constant the contract and the front can share later. Lichess lines are stored as they are: the FEN is the position before the opponent's Move, and the line's first Move is the opponent's. Seam: S1 (the API on in-process Postgres; the loader run first, as the demo seed test does). Covers stories 49-50 of #440. ## Acceptance criteria - [ ] The migration creates the Puzzle table with its indexes; the migrations test passes. - [ ] A test loads a small fixture set twice and finds each Puzzle once, with its fields unchanged. - [ ] A test shows the loader refuses or skips a line the engine rejects. - [ ] The committed sample loads in full on a fresh database. - [ ] The deploy of every stack runs the loader after the migrations; the e2e stack has Puzzles. - [ ] The sampling script's use is documented where the other scripts are. - [ ] The gate is green (`CONTRIBUTING.md`, "The five commands").

root commented

2026-10-16 08:20:08 +00:00

(Migrated from gitlab.core-project.space)

mentioned in issue #443