feat(course): audit fixes and twelve extensions (Modules 7b, 12, 13)

Audit pass:
- Frame rule counts frames since the last move, so every step lasts
  exactly movesEvery(score) frames, also right after a speed-up
- clampTime + MAX_GAP_MS: a hidden tab no longer replays the whole gap
- Pong Restart keeps held keys
- Fact corrections (mulberry32 output coverage, Haskell IO, uniform)
- New fixture cases from a mutation analysis

Extensions (all three tracks, shared fixtures, course text):
- Turn queue (Exercise 10.6), persisted high score (10.7),
  replay viewer (10.8), play() end-to-end helper (9.5)
- Optional State (4.7) and optional Module 7b, stack-safe IO
- Module 12, property-based testing with generators, shrinking,
  invariants and a model-based oracle
- Module 13, Conway's Life with a Click event
- JS type checking via jsconfig, JSDoc and types.d.ts
- Maintainer tools: scripts/mutate.mjs, scripts/typecheck-js.sh,
  Playwright end-to-end suite (e2e/, scripts/e2e.sh)

Docs: docs/contract.md is the canonical contract; specs and build log
under docs/superpowers.

Verified: JS 728, Scala 689, F# 691 unit tests; stubs and progression
M01-M13 and M07b; 176 end-to-end tests on Chromium and WebKit.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Lucas WintherandClaude Fable 5.2 committed 2026-11-11 12:05:29 +01:00
1 parent 876f5aabb1
commit edd57f0148
253 files changed
+21753 -503

No files matched your search

+65
View File
@@ -0,0 +1,65 @@
/// m07b safeio (optional): a stack-safe IO. Same idea as m07's IO, plus one more case, so that `bind` only builds
/// data and no program shape can overflow the stack, however deeply its `bind`s are nested.
/// - `Pure a` done, with a value
/// - `Effect (op, k)` perform `op`, then continue with `k result`
/// - `FlatMap (io, f)` run `io`, then continue with `f result`
/// The ops, their answers and the result of `trace` are m07's `IO.Op`, `IO.OpResult` and `IO.Traced`.
/// (Not `open Snake.IO`: its cases are also called Pure and Effect.)
module Snake.SafeIO
/// `FlatMap`'s inner program produces some type `X` that only its continuation knows. A union case cannot have a
/// type parameter of its own, so `X` is erased to `obj`; only `bind` builds a `FlatMap`, and it keeps the two in step.
type SafeIO<'a> =
| Pure of 'a
| Effect of IO.Op * (IO.OpResult -> SafeIO<'a>)
| FlatMap of SafeIO<obj> * (obj -> SafeIO<'a>)
// Given: the same program, seen as a SafeIO<obj>. Constant work: continuations are wrapped, not called.
let rec private erase (io: SafeIO<'a>) : SafeIO<obj> =
match io with
| Pure a -> Pure(box a)
| Effect(op, k) -> Effect(op, fun r -> erase (k r))
| FlatMap(m, g) -> FlatMap(m, fun x -> erase (g x))
let pure (a: 'a) : SafeIO<'a> = Pure a
let effect (op: IO.Op) : SafeIO<IO.OpResult> = Effect(op, pure)
// Only builds a node: never calls f, not even when io is Pure. The unbox cannot fail: x is the result of `io`.
let bind (f: 'a -> SafeIO<'b>) (io: SafeIO<'a>) : SafeIO<'b> = FlatMap(erase io, fun x -> f (unbox<'a> x))
let map (f: 'a -> 'b) (io: SafeIO<'a>) : SafeIO<'b> = io |> bind (fun a -> Pure(f a))
// A left fold on purpose: with SafeIO the nesting no longer matters.
let sequence (ios: SafeIO<unit> list) : SafeIO<unit> = List.fold (fun acc io -> acc |> bind (fun () -> io)) (pure ()) ios
// One rewrite towards a program whose top is a Pure or an Effect. Constant work, no recursion.
// FlatMap(Pure a, f) -> f a
// FlatMap(Effect(op, k), f) -> Effect(op, fun r -> FlatMap(k r, f))
// FlatMap(FlatMap(m, g), f) -> FlatMap(m, fun x -> FlatMap(g x, f)) (re-association)
// Pure and Effect are already in that shape and come back unchanged.
let step (io: SafeIO<'a>) : SafeIO<'a> =
match io with
| FlatMap(Pure x, f) -> f x
| FlatMap(Effect(op, k), f) -> Effect(op, fun r -> FlatMap(k r, f))
| FlatMap(FlatMap(m, g), f) -> FlatMap(m, fun x -> FlatMap(g x, f))
| other -> other
// Given: the canned answer of the pure interpreter, as in m07. SafeIO keeps Module 7's two operations; the stored
// best score of Module 10 is not part of it, so its operations are refused loudly rather than given a meaning here.
let private answer (seed: uint32) (op: IO.Op) : IO.OpResult =
match op with
| IO.RandomSeed -> IO.Seed seed
| IO.Draw _ -> IO.Done
| IO.LoadBest
| IO.SaveBest _ -> failwith "SafeIO.trace answers only Module 7's operations (Draw and RandomSeed)"
// `loop` calls itself only in tail position, so the compiler turns it into a loop: the stack stays flat.
let trace (seed: uint32) (io: SafeIO<'a>) : IO.Traced<'a> =
let rec loop (current: SafeIO<'a>) (performed: IO.Op list) : IO.Traced<'a> =
match current with
| Pure a -> { IO.Result = a; IO.Ops = List.rev performed }
| Effect(op, k) -> loop (k (answer seed op)) (op :: performed)
| FlatMap _ -> loop (step current) performed
loop io []