Clock Mender rules: a tested `clock-mender/gears.js` where you set gears on pegs to link the winding key to the clock hands within par, from plain data, in a two-file pull with a test file that runs in under a second #293

A new Puzzle game for the catalogue. A stopped clock's back plate has a grid of pegs, a winding key on one peg and the hands' arbor on another. You place gears from a tray of sizes so that turning the key turns the hands the right way round. Rules only: no page and no catalogue entry yet.

Done looks like:

• [x] clock-mender/gears.js holds the rules as plain data in, plain data out, with no DOM. start(level) gives a stated list of hand-made levels, at least six, each with a peg grid, the key's peg, the arbor's peg, blocked pegs, a tray of gear sizes, a required turning direction for the hands and a par. Each gear's size reaches a stated set of neighbouring pegs, and two gears mesh when their reaches touch.
• [ ] place(state, peg, size) puts a gear from the tray on a free, unblocked peg, and lift(state, peg) returns it to the tray. Both refuse anything else with a reason: a blocked or taken peg, a size not in the tray, a gear that would overlap another, or a game already over. A refused call returns the same state.
• [x] drive(state) reports which gears turn and which way, alternating along each mesh from the key. A loop of meshed gears whose directions disagree jams the whole train and is reported as jammed. The level is solved when the arbor turns in the required direction with nothing jammed. The win line reports the gears used against par; restarting the level is always allowed, and the game has no loss.
• [x] clock-mender/gears.test.mjs asserts each rule above: each level's stated solution solves it and stays within par, every refusal and its reason, alternating directions, a jam from an odd loop, the wrong direction not solving, and the win line.
• [x] bun test passes for the new file.
• [x] clock-mender/gears.test.mjs loads no page and starts no renderer or server: it calls the rules module directly and runs in under one second on its own (bun test clock-mender/gears.test.mjs). The pull states the measured time.
• [x] If the check fails only on "test took longer than 600s" or a CPU limit, the pull says so. Do not cut the rules or their tests to get under the limit.

Files: clock-mender/gears.js, clock-mender/gears.test.mjs: a two-file pull. Risk: none outside the folder. Do not touch shell.js, index.html, town.js, rounds.mjs, forge.json, scripts/, playtest.test.mjs or serve.test.mjs here. Fits: a builder.

Reviewed pull #312 at its head: ticked clock-mender/gears.js holds the rules as plain data in, plain data out, with no DOM. start(level) gives a stated list of hand-made levels, at least six, each with a peg grid, the key's peg, the arbor's peg, blocked pegs, a tray of gear sizes, a required turning direction for the hands and a par. Each gear's size reaches a stated set of neighbouring pegs, and two gears mesh when their reaches touch.; drive(state) reports which gears turn and which way, alternating along each mesh from the key. A loop of meshed gears whose directions disagree jams the whole train and is reported as jammed. The level is solved when the arbor turns in the required direction with nothing jammed. The win line reports the gears used against par; restarting the level is always allowed, and the game has no loss.; clock-mender/gears.test.mjs asserts each rule above: each level's stated solution solves it and stays within par, every refusal and its reason, alternating directions, a jam from an odd loop, the wrong direction not solving, and the win line.; bun test passes for the new file.; clock-mender/gears.test.mjs loads no page and starts no renderer or server: it calls the rules module directly and runs in under one second on its own (bun test clock-mender/gears.test.mjs). The pull states the measured time.; If the check fails only on "test took longer than 600s" or a CPU limit, the pull says so. Do not cut the rules or their tests to get under the limit..

Left open after pull #312 landed: 1 unticked item remains (place(state, peg, size) puts a gear from the tray on a free, unblocked peg, and lift(state, peg) returns it to the tray. Both refuse anything else with a reason: a blocked or taken peg, a size not in the tray, a gear that would overlap another, or a game already over. A refused call returns the same state.). The planner files each as its own issue and closes this one; a person may close it, tick what is done, or say what is left. Until then the crew does not pick it again.

Already done on main in 829fd74 (pull #312). The open box is shipped. place(state, peg, size) in clock-mender/gears.js (lines 113–126) refuses blocked, taken (which covers the key and arbor pegs), not-in-tray (including non-integer sizes), overlap, off-plate and game-over. lift(state, peg) (lines 128–139) returns the gear to the tray and refuses fixed, empty, off-plate and game-over. Every refusal returns the same state object. The tests place refuses with a reason and returns the same state, the tray: a size runs out, and lift returns the gear and lift refuses the key, the arbor, an empty peg, a bad peg and a finished game in clock-mender/gears.test.mjs assert each one with toBe(st). All 10 tests pass on main in 28 ms. No new issue is needed for this box.

Already done on main in 829fd74: place(state, peg, size) and lift(state, peg) are in clock-mender/gears.js (lines 114-139). place refuses game-over, off-plate, blocked, taken, not-in-tray and overlap; lift refuses game-over, off-plate, fixed and empty. Each refusal returns the same state object. The tests in clock-mender/gears.test.mjs ('place refuses with a reason and returns the same state', 'the tray: a size runs out, and lift returns the gear', 'lift refuses the key, the arbor, an empty peg, a bad peg and a finished game') cover them, and bun test clock-mender/gears.test.mjs passes 10 of 10 in 59 ms. The unticked box describes work that has already shipped.