Public: anyone can read this; the crew can change it.

Migrated from github.com/amirmushichge/pixel-plays

Lock Keeper rules: a tested `lock-keeper/lock.js` that works boats through a flight of canal locks from plain data #154

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

I added the Lock Keeper rules in lock-keeper/lock.js with tests in lock-keeper/lock.test.mjs. The new test file passes (11 tests, about 7 s, almost all of it the par search). scripts/gate.ts and scripts/fast.ts don't exist in this clone, so I didn't run them.

Notes

shipped production is serving it deploy ab54f53

opened this

I added the Lock Keeper rules in lock-keeper/lock.js with tests in lock-keeper/lock.test.mjs. The new test file passes (11 tests, about 7 s, almost all of it the par search). scripts/gate.ts and scripts/fast.ts don't exist in this clone, so I didn't run them. I did not run scripts/design-lint.ts because nothing in src/web/ changed.

What it does

  • Layout: the canal is three locks and four pounds, as seven places at positions 0 to 6. Each lock has a low or high level, a top and bottom gate, and a top and bottom paddle.
  • Operations: apply(state, { lock, act }) takes paddle-top, paddle-bottom, gate-top, gate-bottom or move. It returns { state, ok, why, events }.
  • Refusals: a refused operation returns the same state object and says why: uneven-water, gate-open, gate-closed, no-room, no-boat, round-over, no-such-lock or no-such-act. It never throws.
  • Water: a gate opens only when the lock is level with the pound on that side. The top paddle fills the lock and the bottom paddle empties it.
  • Flood: opening both paddles of one lock loses the round with reason: 'flood'.
  • Boats: a boat moves one place per move, only through an open gate. A lock holds one boat and a middle pound holds two.
  • Win: the round is won when every boat is through. The state reports ops against par.
  • Seeds: newRound(seed) gives one boat waiting at each end and, for some seeds, a third, so 2 or 3 boats. The same seed always gives the same queue. Shipped seeds are 1, 2 and 3.
  • Par: pars are 36, 60 and 60 operations. I found them by a breadth-first search, shortest(seed), over every legal operation sequence that avoids a flood. The test checks that the search gives the same figures, so par is reachable and no shorter solution exists.

Choices to know about

  • A paddle can't be drawn while the gate on the far side is open. Otherwise the pound would run through the lock.
  • Opening a paddle fills or empties the lock at once, and closing a paddle changes nothing. Closing a gate is always allowed.
  • A refusal reports the reason for the first boat that was blocked. A lock-full refusal is therefore hidden when a boat inside the lock is blocked first, and the test only checks that the move is refused.
  • A seed outside 1 to 3 works out its par by search the first time, which takes up to about 5 s. It is cached after that.

I did not touch shell.js, index.html or rounds.mjs, and I added no page and no catalogue entry, as the issue asked.

To try it, run bun test lock-keeper/lock.test.mjs.

🤖 Generated with Claude Code

Closes #140

Changes requested — before the latest push

The rules read correctly and the tests cover each refusal, the flood and the win. One thing has to change before this lands.

Fix first: newRound(seed) calls par(seed). For any seed outside the shipped 1, 2 and 3, that runs a synchronous breadth-first search of up to 80 levels on the caller's thread. The test file takes about 7 s mostly because of this, and newRound(7) in the determinism test pays for it. Starting a round on an unshipped seed will freeze a page or a request far past the 50 ms bar. Make newRound O(1). Either leave par out of the state (use the table value or null) and expose par(seed) as an explicit call, or restrict newRound to SEEDS. Add a test that newRound(7) returns quickly and that its par is a number or null, never a hang. shortest can also return null after 80 levels, so line must not print par null.

Also fix:

  • newRoundBare duplicates the lock literal in newRound. Extract one freshLocks() and use it in both.
  • The PARS comment has stray alignment spaces.
  • through is exported and used only inside the module. Keep it only if the page will call it.
commented

I addressed all of @juniper's points and pushed to the same branch. The new test file passes (12 tests). I didn't run tsc or the other checks again after this change. The test file still takes about 5.5 s because of the par-reachability test, which runs the search on purpose.

  • newRound is O(1): par(seed) now returns the table value for seeds 1 to 3 and null for any other seed, with no search. shortest(seed) is the explicit, slow way to find a par. I dropped the memo cache because nothing needs it now.
  • line with no par: it leaves out the "(par …)" part when par is null, so it never prints par null.
  • New test: newRound(7) returns in under 50 ms, its par is null, and its line has no mention of par. Seed 1 still reports par 36.
  • freshLocks(): one shared function now builds the locks, and newRoundBare is gone.
  • Cleanups: I fixed the stray spaces in the PARS comment and removed through from the exports, since only the module uses it.

🤖 Generated with Claude Code

Approved

Reviewed every line of lock-keeper/lock.js and its tests. It is a pure rules module with no I/O, no network, no storage, no eval and no secrets, so there is no injection, authorization or escaping surface. apply() validates lock and act at the boundary, returns the same state object on refusal and never throws. newRound is O(1) now that par is a table lookup. I checked the gate and paddle rules and the flood rule by hand, and the tests cover the refusals, the flood, the win and the determinism of the queue. I did not run the tests: the checkout I had did not contain lock-keeper/. Like the sibling rules pulls (ferryman, hoopla, tower-duel), it ships the rules only, as the issue asks. Nit, not blocking: the PARS comment is still spaced differently from its neighbours.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs