Changing the rules¶
You've read Snap's rules and tested them. Now change them. This chapter makes
two changes to the real rules in Games/Snap/Rules.lean, and for each one
looks at what the tests say, what the proofs say, and what it's like to play.
Before you start, make sure your copy is clean, so you can always get back:
To undo everything in this chapter afterwards:
Change one: snap on suit¶
In this version, a snap is valid when the two top cards are the same suit, not the same rank. With four suits rather than thirteen ranks, snaps come far more often.
The rule lives in one place, State.isMatch. Change its first pattern so it
compares suits. The result looks like this (here it's under another name,
so that this course can check it beside the real rules):
def State.isMatchBySuit (s : State) : Bool :=
match s.hand0.up, s.hand1.up with
| c :: _, d :: _ => c.suit == d.suit
| _, _ => false
In Rules.lean, change only the line with c.rank == d.rank to compare
c.suit == d.suit. Then:
lake build Games # does it still make sense to Lean?
make test # what changed?
make proofs # what still holds?
\"docs/GUARANTEES.md is out of date\"
make proofs also checks that the list of guarantees in
docs/GUARANTEES.md is current, and that page links to the line each
definition is on. A change that adds or removes lines moves those links,
so make proofs asks you to run make guarantees. That's bookkeeping,
not a broken proof: run it, then make proofs again.
The tests fail. Several of Snap's tests are about which snaps are valid, and they were written for the old rule, with cards of the same suit and different ranks. Under the new rule those are valid snaps, so the tests disagree. That is what tests are for: they pin down what the rules were, so any change shows up. If you mean to keep a change, you update the tests to say what the rules are now.
The proofs all still hold. Run make proofs: every guarantee about Snap
is still true, and Lean still accepts every proof. That's not luck. Look at
what Snap's proofs promise: no card is ever created or lost, only the player
whose turn it is can flip, a finished game accepts nothing, a valid snap is
never penalised. None of them depends on what makes a snap valid, so none
of them breaks when that changes. A proof only breaks when a change makes
what it states false, or when the reasons it gave no longer apply.
Play it. Rebuild and start the server (see Setting up), then open http://localhost:8080/?game=snap. The bot reacts to matches as the engine reports them, so it plays your rule without being told about it: the rules live only in Lean.
Change two: a false snap burns the pile¶
Now a harsher rule: a false snap doesn't hand your face-up pile to the other
player, it takes it out of the game. Here is snap with that change; only the
last three lines differ from the original:
def snapBurning (s : State) (p : Fin 2) : State × List Event :=
let me := s.hand p
let them := s.hand (other p)
if s.isMatch then
let won := them.up ++ me.up
let r := settle <| (s.setHand (other p) { them with up := [] }).setHand p
{ down := me.down ++ won.reverse, up := [] }
(r.1, [.snapped p won.length] ++ r.2)
else
let r := settle <| s.setHand p { me with up := [] }
(r.1, [.falseSnap p me.up.length] ++ r.2)
Make the same change to snap in Rules.lean (keep its name, snap), and
run the three commands again.
The tests fail, including in a new way: the random games now finish with fewer than 52 cards, and the simulation checks for exactly 52.
A proof fails. make proofs stops in Proofs/Snap/Bookkeeping.lean, at
this lemma:
/-- A snap moves face-up piles between the two players: no card is created or lost. -/
theorem snap_conserves (s : State) (p : Fin 2) : (snap s p).1.cards.Perm s.cards := by
apply perm_of_count; intro c
match p with
| 0 => unfold snap; split <;>
simp [State.setHand, State.cards, State.hand, other, List.count_append, List.count_reverse] <;> omega
| 1 => unfold snap; split <;>
simp [State.setHand, State.cards, State.hand, other, List.count_append, List.count_reverse] <;> omega
It says a snap moves cards between the players without creating or losing any. Under the new rule that is no longer true: a false snap loses cards. No proof could go through, so Lean is right to refuse the old one. And the guarantee built on it, no card is ever created or destroyed, now says something false about your game. In a project without proofs, that would be a silent change; here the build tells you which promise you just broke.
When this happens to you, you have two honest choices:
- the change was a mistake, so undo it; or
- the change is what you want, so the guarantee was too strong for your game. Restate it as something your game does keep, such as no card is ever created, and prove that instead.
What you must never do is make the error go away without changing what is
promised. This project's make proofs refuses sorry, Lean's placeholder for
a missing proof, for exactly that reason.
Exercises¶
- Make the flip limit for new games 200 instead of 2000. Where is it set?
(Hint: it isn't in
Rules.lean; look formaxFlipsinGame.lean.) Which tests and proofs care? - Change the rules so that a false snap gives the other player only your top face-up card, and you keep the rest. Before running anything, predict: will the tests fail? Will any proof?
Answers
- The default comes from the table's configuration, in Snap's
Gameinstance inGames/Snap/Game.lean:cfg.optNat "maxFlips" 2000. Change the2000. The Lean tests and proofs don't mind: the proofs about the flip limit hold for any limit above zero, which is why the configuration refuses a limit of zero. The web tests do mind: they use views recorded from the engine with the old default, and a Go test checks those recordings against the engine.make fixturesrecords them again. -
One way to write it: the caller keeps
me.up.drop 1and the other player getsme.up.take 1. Then:- The tests about false snaps fail, since they expect the whole pile to move. The other tests pass.
caller_after_false_snapinBookkeeping.leanfails, and it should: it states that the caller ends with an empty face-up pile, which is no longer true. It has to be restated.snap_conservesfails too, and this one is different: what it states is still true, since every card is still somewhere. Its proof fails because the automation it relies on doesn't know that the top card and the rest of a pile make the whole pile.
So a failing proof means one of two things: the statement became
false, or it's still true but the argument needs a new step. Telling
the two apart is the skill. Repairing snap_conserves is a good
challenge once you've finished this section.