I recently found myself with some time and the chance to finally pick up OCaml. Its use in correctness-first systems is what had first caught my eye back in my University daysIf I remember right, the earliest glimpse I had of OCaml in industry came from this talk, hosted by the school’s hacker community where an alumni from a prop-trading shop came down to share what they were building.; I never had the chance to explore it deeply. Happily, this aligned with a long-term personal goal of building meaningful pedagogical artefactsAn example: meaningful guided projects with an effortful learning curve.for FOSS ecosystems.
Teaching people how to teach themselves is difficult because learning is a deeply personal habit and not every skill is learned the same, but a reliable start to exploring that is to make my own learning style visible.
So I set an impossible goal: spend two weeks learning OCaml’s core patterns-of-thought by designing a proxy projectA deliberately constructed side project whose primary purpose is to catalyse learning in a new domain. Instead of pursuing the project’s outcome as an end in itself, the creator uses it as a proxy for skill-building and intuition-forming under realistic conditions.as the learning substrate – a deterministic, dependency-free event-simulator for the classic Paxos protocol. ~4 weeks laterScope-creep is inevitable for personal projects., the project is at a stage where I can focus on talking about it.
This series documents the design thinking, the friction, and the moments where the compiler shifted from adversary to collaborator.
Figure 1: 🙙 Photo of the Milky Way seen from the Gobi desert by Daniel Kordan, retrieved 🙛
Written primarily for a technical audienceA little programming experience goes a long way. I won’t focus heavily on syntax – OCaml’s consistency makes it readable. For code-examples, I describe intent wherever possible so that unfamiliar syntax never gets in the way. Part II gets more involved in places where the type system is the point, but non-technical readers can gloss over those sections without losing the thread., occasionally wandering into personal narrative are the 3 parts:
Part I: A Proxy Project – the didactic motivations, the design philosophy, and the abstract grammar that anchors the architecture. You walk away understanding why the system is shaped the way it is.
Part II: Design Pressures – the implementation: how OCaml’s type system, module system, and mutation discipline shaped three key architectural decisions. You walk away understanding how the code works and what the compiler taught me. This is the most technically involved part.
Part III: Retrospectives (forthcoming) – evolution paths, honest debt, and what OCaml leaves behind in the way you think. You walk away understanding what’s next and what could have been done differently.
Each part is self-contained. If you’d rather start where your interest is strongest:
Curious about the full arc? \(\Rightarrow\) Read in order: Part I → II → III.
Here for the technical substance? \(\Rightarrow\) Start with Part II – it opens with enough context to stand alone. Part I’s
Abstract Design Grammar section is worth a look if the design constraints intrigue you.
In the OCaml community, evaluating the work? \(\Rightarrow\) Part II first, focusing on the design pressures. Part III’s debt ledger will be the most honest section about where the architecture falls short.
The simulator (v0) is complete: JSON-driven scenarios, terminal-interactive harness, deterministic replay, colourised logging.
The codebase is almost entirely hand-rolled; it relies on Jane Street’s OCaml stack throughout (Base, Core, ppx_jane) because I picked up the basics of the language by reading the book “Real World OCaml” (
my reading notes are here).
This is Part II of
a series on learning OCaml by writing a Paxos simulator. We build on Part I’s
abstract grammar and witness how subsystems take shape from it — guided, as it turns out, by the OCaml compilerI’m sure the magical source within the compiler is the underlying Hindley-Milner Type system which expects the programmer to exercise clearer type-discipline in exchange for superior inference capabilities that feel like an extension to the programmer’s own mind. I’ve put up a few words about what that experience has been like here <TODO: add reference to part 3 where we reflect on the experience of working with the compiler>itself.
This is Part I of
a series on learning OCaml through building a Paxos simulator. Here, we stay away from the code entirely and focus on listening closely to the forces that will shape the architecture.
