Fourteen years ago, Gary Bernhardt coined the term Functional Core, Imperative Shell. Like most good ideas in computing it was not entirely new, but his conception had great clarity, and it forms an excellent basis for talking about testing and determinism in existing systems. Briefly, Functional Core Imperative Shell architecture divides the code into two parts.

The Functional Core is purely functional - that is no IO, and no destructive state updates. It is concerned with the business logic of the application. The Imperative Shell has comparatively little pathing, but maintains state, coordinates external dependencies, and deals with the outside world - that is to say IO.

Its job is to query the core with values, receive values back as the result of some blackbox decision, and use that to interact with the outside world; whether that is writing to a database, sending a request, or updating a GUI. The Shell and the Core in this model have distinct characteristics: Core Shell Makes decisions Coordinates dependencies Many branching execution paths More linear execution Isolated from the world Integrates with the world This makes the core very amenable to testing. Since it's purely functional, the same inputs will always get the same results.

Since it's isolated, there is nothing to mock or stub. And since it handles complex business logic, the tests can tell us a lot about how the system behaves. Functional Purity and Determinism A shorter way of describing the properties that make pure functions amenable to testing is that they are deterministic.

That is - given a stream of inputs, a pure function always returns the same stream of outputs; their behaviour is repeatable. But pure functional programming is not the only way to get there. If we tilt our heads a little we can see that a stream of values and a sequence of assignments are different ways of expressing the same thing, and State Machines can bring us the same benefits.

Consider the following code: function add(ns) {return ns.reduce((a, b) => a + b, 0)} class Add Machine {#state = 0 transition(input) {this.#state += input} get state() {return this.#state}} The function add is easy to reason about; it's pure and thus deterministic. But the Add Machine is also deterministic - given the same sequence of calls to the transition function, Add Machine will return the same state. It being imperative does not change that. const output = add([1, 2, 3]) const a = new Add Machine() a.transition(1) a.transition(2) a.transition(3) const output = a.state Pure functional programming is a fine paradigm, but due to language or performance considerations, it is not always practical - I would not want to try it in C! But weakening the requirements from purely functional to merely deterministic, we retain the testability benefits of Functional Core Imperative Shell, while broadening its applicability.

And so the title of this post: Deterministic Core, Non Deterministic Shell. Determinism can feel like a more abstract concept than functional purity. How do you know it when you see it? I find it's easier to start with what is not deterministic and work backwards.

Here are some common examples of non-repeatable behaviour: Calling RNGs that aren't seeded Asynchronous and multi threaded operations Communication over the network Communication with other processes Reading Writing to local storage Database interactions Asking the OS for the date or time All these belong in the non deterministic shell. Whenever you find them in your business logic, you have a natural target for defragmentation - either splitting the function in two around them, or lifting them up a layer and injecting their result as a parameter. It's illustrative to think of the shell metaphor quite literally; it should surround the logic, querying the heart of the application to get what it needs.

Working with what you have This is all well and good, you might think, but what use of it is to me, toiling away in the legacy vibe code mines of industry? A fai.