Skip to content

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:

git status            # nothing changed in Games/

To undo everything in this chapter afterwards:

git restore Games/Snap/Rules.lean

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

  1. Make the flip limit for new games 200 instead of 2000. Where is it set? (Hint: it isn't in Rules.lean; look for maxFlips in Game.lean.) Which tests and proofs care?
  2. 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
  1. The default comes from the table's configuration, in Snap's Game instance in Games/Snap/Game.lean: cfg.optNat "maxFlips" 2000. Change the 2000. 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 fixtures records them again.
  2. One way to write it: the caller keeps me.up.drop 1 and the other player gets me.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_snap in Bookkeeping.lean fails, 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_conserves fails 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.