Problem statement
Design the object model and core APIs for a single-player Minesweeper engine that a host (a CLI, a GUI, or a test harness) drives from a fresh board to a won-or-lost outcome. The engine owns every rule: it lays out hidden mines, tracks what each cell shows, cascades open the empty regions a player uncovers, handles flagging, and decides when the game is won or lost. Whatever sits on top merely feeds reveal/flag actions in at grid coordinates and reads board state back.
Operating context. One game at a time on a rectangular grid of width W by height H seeded with M mines (classic beginner is 9x9 with 10 mines; expert is 30x16 with 99). Each cell is either mined or safe, and independently is hidden, revealed, or flagged. Revealing a safe cell shows the count of mines among its up-to-eight neighbours; revealing a cell whose count is zero must flood-open its neighbours outward until the region is bordered by numbered cells. Revealing a mined cell loses the game. A player may flag or unflag a hidden cell to mark a suspected mine; a flagged cell cannot be revealed until unflagged. The game is won when every safe cell has been revealed, regardless of how many flags were placed. Crucially, the FIRST reveal must never detonate a mine — the layout is arranged (or repaired) so the opening click is always safe. Mine placement is injectable so a test can pin an exact layout; nothing calls a global random generator inside the engine. There is no clock, no network, and no concurrent access — one caller, one thread.
Out of scope. Rendering or drawing the grid, input parsing and mouse/keyboard handling, a timer or high-score table, difficulty-preset menus and lobbies, an auto-solver or hint engine, and persistence or save/resume. Design only the in-process rules engine and its object model, not the UI or transport around it.
What to produce. The class hierarchy (entities such as Board, Cell, Game, and value objects like Position, plus the mine-placement seam), the public API each class exposes, and the state transitions for the game (not-started, in-progress, won, lost) and for a cell (hidden, revealed, flagged). Be explicit about: how the board is generated and how first-click safety is guaranteed; how adjacency counts are computed and where they live; how the zero-cell flood-reveal is implemented and bounded so it terminates; how reveal, flag, and win/lose detection stay consistent after every action; and how a different mine-placement policy (fixed seed, symmetric, no-guess) swaps in without rewriting reveal or flood logic.