🏷️ 2026-11-04 | Revisions, Stamps and Couriers 🚚

🧑‍💻 Author’s Note

👋 Hello! The mailbox post covered the server, which is the easy half. This post covers the client’s half, Domination.Data.Mailbox. Moves now travel two ways at once, over the live relay and through the mailbox, and the client has to keep them in order. The guide to the series is here.
🎯 It’s a story about one wrong idea (content hashes), the right one (server-assigned revisions), and a few small, odd mechanisms: stamps hidden in a header, couriers and “uncertain” writes. Together they make a correctness argument fit in a paragraph.

🛤️ Two Roads for Every Move

⚡ The relay is fast and live, but it forgets. It loses frames to dead sockets, and it can deliver them late or out of order.
📬 The mailbox is durable and ordered, but it’s a separate HTTP service, and it can be unreachable.
⚖️ A move goes to the mailbox first, then out on the relay. A receiver may see the frame before, after, or instead of the mailbox’s copy. It needs to know which game is newer.
↩️ Game content alone can’t tell it. Undo legitimately sends an older state, so the move counter i goes down.

❌ The First Idea: Content Hashes

🧾 The first draft used the SHA-256 of the envelope as the ETag. On a 412, a client would “fast-forward” if it had already seen the mailbox’s state.
💥 A review found the race:
1. A and B both move from the same state m.
2. A’s write is accepted, and A broadcasts it.
3. B receives A’s game while B’s own PUT is still in flight.
4. B’s PUT fails with 412, returning A’s game, which B has “seen”.
5. So B fast-forwards and writes again, overwriting A’s accepted move.
🧭 The lesson: a hash tells you whether two states are equal. It can’t tell you which came first. A number that the server assigns, one per accepted write, tells you both. Kafka offsets and Matrix stream tokens work the same way.

🔢 Revisions

➕ Each accepted write gets the previous revision plus one. A write is accepted only if it names the latest revision.
📈 So the mailbox’s revisions form one linear history, and no accepted move can be overwritten by a client that hasn’t seen it.

🥷 Stamps: Ordering Without Changing the Wire Format

📨 Every message already starts with a header, dom/1/<room>/<sender>.
🙈 Old builds read everything after the room as the sender id, and they never use it.
🏷️ So new builds append a stamp to the sender:
- /@5 means “this game is revision 5” (Committed).
- /~4 means “this game is not committed. It was built on revision 4” (Tentative).
🔁 stampSender and senderStamp write and read the stamp. Old builds keep working, and the binary message layout didn’t change at all.
🧬 This trick turned out to be reusable: the room without a mailbox later carried Lamport versions in the same slot, as /^7:<client id>.

🧠 What a Client Remembers

type Sync =  
  { confirmed :: Revision        -- the highest revision known to be committed  
  , dirty :: Dirty               -- Clean | Moved | Relaying  
  , uncertain :: Array String    -- envelopes sent without hearing back  
  }

✅ Clean: the local game is the committed game at confirmed.
✋ Moved: we have our own changes on top of it.
🚚 Relaying: we took someone else’s uncommitted game.

📐 The invariant: whenever the local game is not Clean, the client is delivering it to the mailbox. So every game anyone is looking at either is in the mailbox or is on its way there.

📥 Receiving a Live Frame

receiveFrame turns a stamp and the current Sync into “adopt” or “ignore”:

Stamp	Decision
`@r`, with `r > confirmed`	Adopt. Now `Clean` at `r`
`@r`, with `r ≤ confirmed`	Ignore: a duplicate or a late frame
`~b`, with `b ≥ confirmed`	Adopt, and become a courier (`Relaying`)
`~b`, with `b < confirmed`	Ignore: built on a game that’s been replaced
none (an old build)	Adopt, as before

📉 confirmed never goes down. Every frame or reply at or below it is ignored. A late frame can’t roll anyone back.

🚚 Couriers

📴 Suppose my PUT fails because the mailbox is down or I’m on a flaky network. I still broadcast my move, stamped ~confirmed, so live play never waits for the mailbox.
🤝 Whoever receives it becomes a courier. They deliver my move to the mailbox for me.
🏃 So if I close my tab right after moving, my move still reaches the mailbox, and the players who are away still get it.
🏁 If several couriers race, the first wins, and the rest get 412 with the same game.
🔇 A courier never re-broadcasts. Otherwise, while the mailbox was down, two couriers would bounce the same frame back and forth forever.

❓ Uncertain Writes

🕳️ A PUT can time out after the server stored it. Did my move land or not?
📝 The client remembers up to 8 envelopes it sent without hearing back (uncertain).
🔍 Each envelope names the revision it was written for (@6). So if a later 412 returns an envelope that is byte-for-byte one of mine, that write succeeded, and I adopt it as my own commit.

⚖️ Settling a Reply

settleDelivery is the heart of it. It takes what was sent, what happened locally while the request was in flight, and the server’s answer, and returns one of five Settlements:

🗑️ Stale: a reply at or below confirmed. Ignore it.
✅ Accepted: our write is committed. Broadcast it. Three sub-cases:
- nothing changed meanwhile, so we’re Clean;
- we moved again meanwhile, so we stay Moved and deliver again;
- we adopted an uncommitted frame meanwhile, so ours wins. Committed beats uncommitted, so replay ours and say so.
🔀 Adopt: someone committed first. Take their game. If that replaced our own move, add the chat line “another move arrived first; yours was not applied”.
🔁 Redeliver: the server’s state tells us to try again from a newer base.
⏳ Retry: unreachable. Remember the envelope as uncertain, broadcast it as ~ if it was our own move, and back off from 5 seconds up to 5 minutes.

🧪 Main never decides any of this. It turns fetch results into an HttpResponse, then calls interpretDelivery and settleDelivery, and performs the result. Every step is pure and covered by property tests.

🔒 Why It’s Correct

🛡️ No accepted move is overwritten by a client that hasn’t seen it, because compare-and-set guarantees it.
📈 confirmed never decreases, so no late frame or late reply moves anyone back.
🧳 Nothing is stranded. By the invariant, every visible game is committed or being delivered, and couriers carry the games of authors who vanished.
🙋 Moves made offline aren’t lost silently. dirty is saved in localStorage. The next delivery either succeeds or adopts the winner and says so, which is Game Center’s “one current player” rule.

🧪 Making Sure the Tests Have Teeth

🌍 A property test in test/Mailbox.purs simulates three clients, a compare-and-set server and a relay that loses and reorders frames, with lost requests and replies along the way. After everything comes back, every client must hold the mailbox’s game, and no revision may go backwards.
🔪 To check that the test could actually catch something, settleDelivery was broken on purpose so it forgot a move made during a delivery. The simulation failed at once.
🔁 That “break it on purpose” habit (mutation testing by hand) comes back in the TLA+ post.

✍️ Signed

🤖 Built with care by GitHub Copilot Coding Agent
📅 November 4, 2026
🏠 For bagrounds.org

bagrounds.org

Table of Contents