# Module 4 — Randomness without side effects
> **Time:** ~4 h · **You'll edit:** JS `js/src/random.js`, `js/src/spawn.js` · Scala `scala/src/Random.scala`, `scala/src/Spawn.scala` · F# `fsharp/src/Random.fs`, `fsharp/src/Spawn.fs`
> **Tests:** JS `cd js && node --test "test/m04-*.test.js"` · Scala `cd scala && ./test.sh M04` · F# `cd fsharp && ./test.sh M04`
> **Prerequisites:** Modules 1–3
## Why this module
After the snake eats, a new apple must appear on a random free cell. The usual code is one line:
```js
const i = Math.floor(Math.random() * cells.length)
```
That line quietly destroys everything you have built so far:
- **It is not pure.** `Math.random()` takes no arguments and returns a different number each time. A function that calls it is not referentially transparent, so `spawnApple(state)` would no longer mean one thing.
- **It cannot be tested exactly.** What should the test for "eating spawns a new apple" expect? You can only check vague properties ("the apple is somewhere free").
- **It cannot be replayed.** A player reports a bug after 300 moves. You have their key presses, but not the random numbers, so you cannot reproduce the game.
The fix is an old idea: a pseudo-random generator is not random at all. It is a **deterministic function** from a state (the seed) to a number and a new state. If we make that function explicit and *carry the seed in the game state* (that is why `seed` is in `GameState`, Module 2), randomness becomes pure. Same seed, same game.
Carrying the seed by hand is tedious and error-prone, though. Fixing *that* leads you to discover `map` and `flatMap` for random generators, and to a pattern with a famous name: the **State monad**.
## Learning objectives
After this module you can:
- **explain** why `Math.random` breaks purity and testing, and how a seed fixes it;
- **describe** at a high level how mulberry32 turns a seed into a number and a new seed, and why 32-bit arithmetic must be handled carefully in each language;
- **implement** `Random = seed → (A, seed)` with `pure`, `map` and `flatMap`, and recognise it as the State monad;
- **use** Scala's for-comprehension and F#'s computation expressions as syntax for the same chaining;
- **implement** apple spawning, including the full-board edge case, and explain why "same seed ⇒ same game".
## Concepts
### Pseudo-random numbers are a pure function in disguise
A pseudo-random number generator (PRNG) keeps a small internal state. Each time you ask for a number, it computes the number from the state and updates the state. `Math.random()` does exactly this, but the state is hidden inside the JavaScript engine and seeded from something unpredictable when the program starts.
Take the hidden state out, and what remains is a plain function:
```
next : seed -> (value, nextSeed)
```
Call it with the same seed, you get the same value and the same next seed, every time. To get a *sequence* of numbers, you feed each returned seed into the next call:
```
seed0 --next--> (v1, seed1) --next--> (v2, seed2) --next--> (v3, seed3) ...
```
That is the whole trick. The numbers look random (they pass statistical tests), but they are completely determined by the first seed. Where does the *first* seed come from? From the outside world, once, at the very edge of the program (in Module 9, the runtime asks the browser's `crypto` for one). Everything after that is pure.
> **From Scala:** `scala.util.Random` and `java.util.Random` are objects with a mutable seed inside: `rng.nextInt()` changes `rng`. Even `new Random(42)` only makes the *start* reproducible; the object is still mutated by each call, so `rng.nextInt() + rng.nextInt()` is not referentially transparent. We want the seed in our hands, as a value.
### mulberry32, in plain words
The course uses a small, fast generator called **mulberry32**. You do not need to understand why its constants work (that is research), but you should understand its structure, because it is surprisingly simple:
1. **Advance a counter.** The new seed is the old seed plus a fixed odd constant, `0x6D2B79F5`, wrapped around modulo 2^32. Because the constant is odd, repeatedly adding it visits all 2^32 possible seeds before repeating. That is the *period* of the generator: about 4.3 billion numbers.
2. **Scramble the counter.** The output value is a "mix" of the new seed: a few rounds of XOR-with-a-shifted-copy and 32-bit multiplication. These operations spread every bit of the input over every bit of the output, so consecutive seeds (which differ by a constant) give outputs that look unrelated.
In other words: the seed is only a counter, and the "randomness" is a hash of the counter. In pseudo-code, with all arithmetic on unsigned 32-bit integers:
```
s = (seed + 0x6D2B79F5) mod 2^32 -- the next seed
t = imul(s xor (s >>> 15), s or 1)
t = t xor (t + imul(t xor (t >>> 7), t or 61))
value = t xor (t >>> 14) -- as an unsigned 32-bit number
return (value, s)
```
(`imul` is 32-bit multiplication, keeping only the low 32 bits; `>>>` is an unsigned right shift.) mulberry32 is fine for games and simulations, and **not** suitable for anything security-related: given one output, the next ones can be predicted.
For example, from seed `0` the first draw gives the value `1144304738` and the new seed `1831565813` (which is `0x6D2B79F5`: zero plus the constant). The next draw, from seed `1831565813`, gives `1416247` and seed `3663131626`. These are the first two cases of `fixtures/m04-random.json`.
### The same 32 bits in three languages
The three tracks must produce **bit-identical** numbers, otherwise the shared fixtures (and apple positions) would differ between languages. That is harder than it sounds, because the languages treat integers differently:
| | JavaScript | Scala | F# |
|---|---|---|---|
| Seed type | `number` (a 64-bit float) | `Long` (holds 0 until 2^32) | `uint32` |
| 32-bit multiply | `Math.imul(a, b)` | `Int` `*` wraps around | `uint32` `*` wraps around |
| Unsigned shift | `>>>` | `>>>` on `Int` | `>>>` on `uint32` (unsigned type, so logical) |
| XOR / OR | `^` / `\|` | `^` / `\|` | `^^^` / `\|\|\|` |
| Back to unsigned | `x >>> 0` | `x.toLong & 0xFFFFFFFFL` | already unsigned |
The usual bugs: in JS, forgetting that `+` and `*` on numbers do not wrap at 2^32 (so you get huge or fractional values), or that `^` and `|` produce *signed* 32-bit results (so you get negative numbers). In Scala, doing the arithmetic in `Long` (which does not wrap at 32 bits) or forgetting to convert the final `Int` back to unsigned. The fixture `m04-random.json` checks ten consecutive draws from seeds `0`, `1` and `4294967295` (the largest seed), which catches every one of these mistakes.
### Threading seeds by hand
Suppose you have `nextUint32 : seed → [value, seed]` and you want a die roll, then the sum of two dice. Written directly (JavaScript, as an illustration):
```js
const d6 = (seed) => {
const [v, s] = nextUint32(seed)
return [1 + (v % 6), s]
}
const twoDice = (seed) => {
const [a, s1] = d6(seed)
const [b, s2] = d6(s1)
return [a + b, s2]
}
```
It works, and it is pure. But look at how much of it is plumbing: every line unpacks a pair, passes the seed on, and repacks a pair. And the plumbing is easy to get wrong:
```js
const twoDiceBuggy = (seed) => {
const [a, s1] = d6(seed)
const [b, s2] = d6(s1)
const [c, s3] = d6(s1) // oops: s1 again. c always equals b.
return [a + b + c, s2] // and we return the wrong seed
}
```
Nothing stops you from reusing a seed or returning the wrong one, and the result is still "random-looking", so the bug is hard to spot. When code has the same plumbing everywhere, the functional move is to **name the pattern and write the plumbing once**.
### A type for "something that needs a seed"
Give the shape a name:
```
Random = seed -> [A, seed]
```
A `Random` is a *description* of how to produce an `A` from a seed: a recipe, not a number. `nextUint32` is a `Random`. `d6` is a `Random`. `twoDice` is a `Random`. Nothing happens until you **run** it with a seed: `run(r, seed)`.
**JavaScript**
```js
// A Random is a plain function: seed => [value, nextSeed]
export const run = (r, seed) => ...
```
**Scala**
```scala
// A case class wrapping the function; running it is r.run(seed)
final case class Random[A](run: Long => (A, Long))
```
**F#**
```fsharp
// A single-case union wrapping the function; running it is Random.run seed r
type Random<'a> = Random of (uint32 -> 'a * uint32)
```
Scala and F# wrap the function in a small type of its own (a case class, a single-case union) so that the compiler can tell a `Random` apart from any other function with the same shape, and so that `map` and `flatMap` can be attached to it. F#'s `run` takes the seed first and the `Random` last (data last), so you can write `r |> Random.run 42u`.
Now look at the plumbing in `d6` and `twoDice` again. There are only two patterns in it.
**Pattern 1: change the value, keep the seed.** `d6` runs `nextUint32`, transforms the value (`1 + v % 6`) and passes the seed through untouched. Call this **`map`**:
```
map(r, f) : Random where r : Random, f : A -> B
seed --r--> [a, s1] gives [f(a), s1]
```
**Pattern 2: run one, then choose the next based on its value, and run that with the leftover seed.** `twoDice` runs `d6`, and then runs "another `d6`, and add `a` to its result", which depends on `a`. Call this **`flatMap`**:
```
flatMap(r, f) : Random where r : Random, f : A -> Random
seed --r--> [a, s1]
a --f--> r2
s1 --r2--> [b, s2] gives [b, s2]
```
And one trivial pattern: **a value that needs no randomness**, which leaves the seed alone. Call it **`pure`**:
```
pure(a) : Random seed gives [a, seed]
```
With these, the dice need no plumbing at all, and the seed-reuse bug cannot even be written:
**JavaScript**
```js
const d6 = map(nextUint32, (v) => 1 + (v % 6))
const twoDice = flatMap(d6, (a) => map(d6, (b) => a + b))
run(twoDice, 42) // [sum, nextSeed], the same every time for seed 42
```
**Scala**
```scala
val d6: Random[Int] = Random.nextUint32.map(v => 1 + (v % 6).toInt)
val twoDice: Random[Int] = d6.flatMap(a => d6.map(b => a + b))
twoDice.run(42L)
```
**F#**
```fsharp
let d6 : Random = Random.nextUint32 |> Random.map (fun v -> 1 + int (v % 6u))
let twoDice : Random = d6 |> Random.bind (fun a -> d6 |> Random.map (fun b -> a + b))
Random.run 42u twoDice
```
Naming differences to note (the full table is in `course/reference.md`):
- JS functions take the data first: `map(r, f)`. Scala uses methods: `r.map(f)`, and `Random.pure(a)` lives in the companion object. F# functions take the data last so they fit pipelines: `r |> Random.map f`.
- F# calls `flatMap` **`bind`**, which is the traditional ML/Haskell name.
You are going to implement `pure`, `map`, `flatMap` and `run` yourself in Exercise 4.2. The diagrams above are the specification.
### You have met this before: the State monad
Look at the type again: `seed → [A, seed]`. Replace "seed" by any state type `S`:
```
State = S -> (A, S)
```
This is the **State monad**: a computation that reads a state, produces a value, and hands on a new state, with `pure` and `flatMap` to sequence such computations without writing the plumbing. Our `Random` is `State`. It is a pure, honest version of "a function that uses and updates a variable": the "variable" is threaded through explicitly, by `flatMap`, so nothing is hidden.
> **From Scala:** you have used `map` and `flatMap` on `List` and `Option`. Any type with a sensible `pure` and `flatMap` is a **monad**, and `Random` is one. "Sensible" means three laws hold:
> - **left identity:** `flatMap(pure(a), f)` behaves like `f(a)`;
> - **right identity:** `flatMap(r, pure)` behaves like `r`;
> - **associativity:** `flatMap(flatMap(r, f), g)` behaves like `flatMap(r, a => flatMap(f(a), g))`.
>
> "Behaves like" means "gives the same result when run with any seed". The tests check the two identity laws (`flatMap with pure on the left or right changes nothing`).
Because `Random` has `map` and `flatMap`, Scala's **for-comprehension** works on it directly. A for-comprehension is only syntax: the compiler rewrites it into `flatMap` and `map` calls.
**Scala**
```scala
val twoDice: Random[Int] =
for
a <- d6
b <- d6
yield a + b
// the compiler turns this into: d6.flatMap(a => d6.map(b => a + b))
```
F# has the same idea, called a **computation expression**. You define a small "builder" object that tells the compiler which function is `bind` and which is `return`, and then you can write:
**F#**
```fsharp
type RandomBuilder() =
member _.Bind(r, f) = Random.bind f r
member _.Return(a) = Random.pure a
let random = RandomBuilder()
let twoDice : Random =
random {
let! a = d6
let! b = d6
return a + b
}
```
`let!` means "run this `Random` and bind its value", which is `bind`. F#'s `async { }`, `task { }` and `seq { }` are built the same way. (The builder is optional; the course code does not need it.)
JavaScript has no such syntax for user-defined types, so you write the nested `flatMap`/`map` calls. Once you see them as "and then, with the result...", they read naturally.
### Drawing a number below `n`
To pick one of `n` free cells, you need a number in `[0, n)`. `intBelow(n)` is `nextUint32` with its value taken modulo `n`. That is a `map`.
(Strictly, `v % n` is slightly biased when 2^32 is not a multiple of `n`: small results are a tiny bit more likely. For `n` up to 400 the bias is below one in ten million, far below anything a player could notice. Libraries that need exact uniformity reject and redraw; we keep it simple and identical across tracks.)
### Spawning an apple
Now apply it to the game. `spawnApple(state)`:
1. If there already is an apple, or the game is not `Playing`, return `state` unchanged.
2. List the **free cells**: every cell of the board that is not part of the snake, in **row-major order** (row `y = 0` from left to right, then row `y = 1`, ...).
3. Draw an index `i` below the number of free cells, from `state.seed`.
4. Return the state with `apple` set to the `i`-th free cell and `seed` set to the seed the draw left behind.
Why does the order of free cells matter? Because the index `i` must mean the same cell in every track. "Row-major" is part of the contract; the fixture `free-cells-row-major-order` checks it.
A worked example from the tests. A 3 x 2 board, a one-cell snake at (0,0) about to eat the apple at (1,0), seed 0:
```
before tick after advance after spawnApple
x: 0 1 2 x: 0 1 2 x: 0 1 2
y=0 H A . y=0 b H . y=0 b H .
y=1 . . . y=1 . . . y=1 . A .
```
After `advance`, the snake is `(1,0) (0,0)` and there is no apple. Free cells, row-major: `(2,0), (0,1), (1,1), (2,1)`, four of them. From seed 0, `nextUint32` gives `1144304738`, and `1144304738 % 4 = 2`, so the apple goes to the cell at index 2: `(1,1)`. The new seed is `1831565813`. That is the test `tick: eating the apple spawns a new one in the same step`.
### Puzzle: the board is full
What happens when the snake fills the entire board? There are no free cells. Before reading on, work out what *your* `spawnApple` would do when the list of free cells is empty, in your language. What is `v % 0`?
Think about it first, then open the explanation
- **JavaScript:** `v % 0` is `NaN`, `cells[NaN]` is `undefined`, so `apple` becomes `undefined`. No crash, only a corrupt state that will cause confusing errors later.
- **Scala:** `v % 0` on integers throws `ArithmeticException: / by zero`. The game crashes at its moment of triumph.
- **F#:** `v % 0u` throws `DivideByZeroException`.
None of these is a rule of the game. A full board means the player has won. So `spawnApple` handles it explicitly: **if there are no free cells, the status becomes `Won`** (no apple, seed unchanged). This is the fixture `spawn-on-full-board`: a 3 x 2 board completely covered by a six-cell snake.
This is a pattern worth remembering: when an operation has no valid answer for some input (here: "pick one of zero cells"), find out what that input *means in the domain*, and make it an explicit, total case.
Exercise 4.1 (nextUint32) — nudge
Translate the pseudo-code line by line, then fix the integer behaviour. Start with seed 0: the new seed must be `1831565813`, which is `0 + 0x6D2B79F5`. Get that right first, then the value.
Exercise 4.1 (nextUint32) — stronger hint
- **JS:** `(seed + 0x6D2B79F5) >>> 0` wraps the sum into an unsigned 32-bit number. `Math.imul(a, b)` multiplies like a 32-bit machine. `^`, `|`, `>>>` work on 32-bit integers; `^` and `|` give *signed* results, so finish the value with `>>> 0`. Use `const` for each intermediate (you cannot reassign `t`; call them `t1`, `t2`).
- **Scala:** `val s = seed.toInt + 0x6D2B79F5` (Int addition wraps). Then the `Int` formula with `*`, `^`, `|`, `>>>`. Return `(value.toLong & 0xFFFFFFFFL, s.toLong & 0xFFFFFFFFL)`. Remember to wrap the function: `Random(seed => ...)`.
- **F#:** `let s = seed + 0x6D2B79F5u` (uint32 addition wraps). Then `^^^`, `|||`, `>>>`, `*` on `uint32`; literals need the `u` suffix (`1u`, `61u`). No conversion needed at the end. Wrap the function: `Random(fun seed -> ...)`.
If seed 0 passes but seed 4294967295 fails, your addition is not wrapping.
Exercise 4.1 (nextUint32) — near-solution (try the others first)
```js
export const nextUint32 = (seed) => {
const s = (seed + 0x6D2B79F5) >>> 0
const t1 = Math.imul(s ^ (s >>> 15), ___)
const t2 = t1 ^ (t1 + Math.imul(___, ___))
return [(t2 ^ (t2 >>> 14)) >>> 0, ___]
}
```
```scala
lazy val nextUint32: Random[Long] = Random { seed =>
val s = seed.toInt + 0x6D2B79F5
val t1 = (s ^ (s >>> 15)) * ___
val t2 = t1 ^ (t1 + ___ * ___)
val v = t2 ^ (t2 >>> 14)
(___, ___)
}
```
```fsharp
let nextUint32 : Random =
Random(fun seed ->
let s = seed + 0x6D2B79F5u
let t1 = (s ^^^ (s >>> 15)) * ___
let t2 = t1 ^^^ (t1 + ___ * ___)
(t2 ^^^ (t2 >>> 14), ___))
```
Exercise 4.2 (pure, map, flatMap, run) — nudge
Follow the types. `map(r, f)` must return a `Random`, which is a function from a seed. So it starts with `(seed) => ...` (JS), `Random(seed => ...)` (Scala) or `fun seed -> ...` (F#). Inside, you have a seed and `r`. What can you do with them?
Exercise 4.2 (pure, map, flatMap, run) — stronger hint
Draw the diagrams from the Concepts section and turn each arrow into a line of code. For `flatMap`: run `r` with the incoming seed to get `[a, s1]`; call `f(a)` to get the next `Random`; run *that* with `s1`; return its result as is. `run(r, seed)` in JS applies the function. In Scala, `r.run(seed)` is the field. In F#, write `run` first, by taking the function out of the union with a pattern (`let run seed (Random f) = ...` is allowed: a single-case union can be matched right in the parameter list); then use `run` inside `map` and `bind`, and wrap each result with `Random(fun seed -> ...)`.
Exercise 4.2 (pure, map, flatMap, run) — near-solution (try the others first)
```js
export const pure = (a) => (seed) => [___, ___]
export const map = (r, f) => (seed) => { const [a, s1] = r(seed); return [___, ___] }
export const flatMap = (r, f) => (seed) => { const [a, s1] = r(seed); return ___(___) }
export const run = (r, seed) => ___
```
```scala
def map[B](f: A => B): Random[B] = Random { seed => val (a, s1) = run(seed); (___, ___) }
def flatMap[B](f: A => Random[B]): Random[B] = Random { seed => val (a, s1) = run(seed); ___.run(___) }
def pure[A](a: A): Random[A] = Random(seed => (___, ___))
```
```fsharp
let run (seed: uint32) (Random f: Random<'a>) : 'a * uint32 = ___
let pure (a: 'a) : Random<'a> = Random(fun seed -> (___, ___))
let map (f: 'a -> 'b) (r: Random<'a>) : Random<'b> =
Random(fun seed -> let (a, s1) = run seed r in (___, ___))
let bind (f: 'a -> Random<'b>) (r: Random<'a>) : Random<'b> =
Random(fun seed -> let (a, s1) = run seed r in run ___ ___)
```
Exercise 4.3 (intBelow) — nudge
It is "the value of `nextUint32`, transformed". Which of your new functions transforms a value?
Exercise 4.3 (intBelow) — stronger hint
`map` over `nextUint32` with a function that takes the remainder modulo `n`. In Scala the value is a `Long` and the result an `Int`: `(v % n).toInt`. In F#, `int (v % uint32 n)`.
Exercise 4.3 (intBelow) — near-solution (try the others first)
```js
export const intBelow = (n) => map(___, (v) => ___)
```
```scala
def intBelow(n: Int): Random[Int] = nextUint32.map(v => ___)
```
```fsharp
let intBelow (n: int) : Random = nextUint32 |> map (fun v -> ___)
```
Exercise 4.4 (freeCells) — nudge
First build *all* cells in row-major order, then keep those not in the snake.
Exercise 4.4 (freeCells) — stronger hint
All cells: for each `y` in `range(height)`, for each `x` in `range(width)`, the point `(x, y)`. In JS that is `flatMap` over the rows and `map` over the columns. In Scala, a for-comprehension over two ranges (with `yield`). In F#, a list comprehension `[ for y in ... do for x in ... -> ... ]`. Then `filter` with "not `contains` in the snake".
Exercise 4.4 (freeCells) — near-solution (try the others first)
```js
export const freeCells = (state) =>
range(state.height)
.flatMap((y) => range(___).map((x) => point(___, ___)))
.filter((p) => !contains(___, p, pointEquals))
```
```scala
def freeCells(state: GameState): List[Point] =
(for y <- Util.range(state.height); x <- Util.range(___) yield Point(___, ___))
.filterNot(p => ___)
```
```fsharp
let freeCells (state: GameState) : Point list =
[ for y in 0 .. state.Height - 1 do
for x in 0 .. ___ do
{ X = ___; Y = ___ } ]
|> List.filter (fun p -> not (___))
```
Exercise 4.5 (spawnApple) — nudge
Three outcomes: unchanged, `Won`, or a new apple with a new seed. Write the guards first, in that order, then the draw.
Exercise 4.5 (spawnApple) — stronger hint
Compute `cells = freeCells(state)`. If it is empty, return the state with status `Won`. Otherwise run `intBelow(cells.length)` with `state.seed` and destructure the pair into the index and the new seed. Build the result with both `apple` and `seed` changed.
Exercise 4.5 (spawnApple) — near-solution (try the others first)
```js
export const spawnApple = (state) => {
if (state.apple !== null || state.status !== 'Playing') return state
const cells = freeCells(state)
if (cells.length === 0) return { ...state, status: ___ }
const [i, seed] = run(intBelow(___), ___)
return { ...state, apple: ___, seed }
}
```
The Scala and F# versions have the same shape: `if ... then state else` / `match cells with [] -> ... | _ -> ...`, then `val (i, s) = Random.intBelow(cells.length).run(state.seed)` / `let (i, s) = Random.run state.Seed (Random.intBelow (List.length cells))`, and `List.item i cells` picks the cell.
Exercise 4.6 (tick, newGame) — nudge
Each is one line: a function applied to the result of another.
Exercise 4.6 (tick, newGame) — stronger hint
`tick(state) = spawnApple(advance(state))`. You can write that call directly, or with your `compose` / `pipe` (JS), `andThen` (Scala) or `>>` (F#). Import `advance` from `rules` and `initialState` from `model`.
Exercise 4.6 (tick, newGame) — near-solution (try the others first)
```js
export const tick = (state) => spawnApple(___(state))
export const newGame = (seed) => ___(initialState(___))
```
```scala
def tick(state: GameState): GameState = spawnApple(___)
def newGame(seed: Long): GameState = ___(Model.initialState(___))
```
```fsharp
let tick (state: GameState) : GameState = state |> Rules.advance |> ___
let newGame (seed: uint32) : GameState = seed |> ___ |> ___
```