3 Aug 2026
\nFourteen years ago, Gary Bernhardt coined the term\nFunctional Core, Imperative Shell. Like most good ideas in computing it was not entirely new, but his\nconception had great clarity, and it forms an excellent basis for talking\nabout testing and determinism in existing systems.
\nBriefly, Functional Core/Imperative Shell architecture divides the code into\ntwo parts. The Functional Core is purely functional - that is no IO, and no\ndestructive state updates. It is concerned with the business logic of the\napplication. The Imperative Shell has comparatively little pathing, but\nmaintains state, coordinates external dependencies, and deals with the outside\nworld - that is to say IO. Its job is to query the core with values, receive\nvalues back as the result of some blackbox decision, and use that to interact\nwith the outside world; whether that's writing to a database, sending a\nrequest, or updating a GUI.
\nThe Shell and the Core in this model have distinct characteristics:
\nCore\nShell
\nMakes decisions\nCoordinates dependencies
\nMany branching execution paths\nMore linear execution
\nIsolated from the world\nIntegrates with the world
\nThis makes the core very amenable to testing. Since it's purely functional,\nthe same inputs will always get the same results. Since it's isolated, there\nis nothing to mock or stub. And since it handles complex business logic, the\ntests can tell us a lot about how the system behaves.
\nA shorter way of describing the properties that make pure functions amenable\nto testing is that they are deterministic. That is - given a stream of\ninputs, a pure function always returns the same stream of outputs; their\nbehaviour is repeatable. But pure functional programming is not the only way\nto get there. If we tilt our heads a little we can see that a stream of values\nand a sequence of assignments are different ways of expressing the same thing, and State Machines can bring\nus the same benefits. Consider the following code:
\nfunction add(ns) {\nreturn ns.reduce((a, b) => a + b, 0)\n}
\nclass AddMachine {\n#state = 0
\ntransition(input) {\nthis.#state += input\n}
\nget state() {\nreturn this.#state\n}\n}
\nThe function add is easy to reason about; it's pure and thus\ndeterministic. But the AddMachine is also deterministic - given\nthe same sequence of calls to the transition function, AddMachine\nwill return the same state. It being imperative does not change that.
\nconst output = add([1, 2, 3]) // 6
\nconst a = new AddMachine()\na.transition(1)\na.transition(2)\na.transition(3)
\nconst output = a.state // 6
\nPure functional programming is a fine paradigm, but due to language or\nperformance considerations, it is not always practical - I would not want to\ntry it in C! But weakening the requirements from purely functional to\nmerely deterministic, we retain the testability benefits of "Functional\nCore, Imperative Shell", while broadening its applicability. And so the title\nof this post:\nDeterministic Core, Non-Deterministic Shell.
\nDeterminism can feel like a more abstract concept than functional purity. How\ndo you know it when you see it? I find it's easier to start with what is not\ndeterministic and work backwards. Here are some common examples of\nnon-repeatable behaviour:
\nAll these belong in the non-deterministic shell. Whenever you find them in\nyour business logic, you have a natural target for defragmentation - either\nsplitting the function in two around them, or lifting them up a layer and\ninjecting their result as a parameter. It's illustrative to think of the\n"shell" metaphor quite literally; it should surround the logic, querying the\nheart of the application to get what it needs.
\n"This is all well and good", you might think, "but what use of it is to me,\ntoiling away in the legacy & vibe-code mines of industry?". A fair accusation,\nimaginary reader; not everyone can be Foundation DB and make that distinction from day one\n(they actually went a step further, but that's a topic for another post).\nDeterminism and non-determinism are highly entwined in almost every real life\ncodebase I have seen, and I've seen my fair share.
\nBut don't let perfect be the enemy of good! One way to think of your average\n(ie, terrible) codebase is that it has many deterministic cores. There are\nthousands, strewn through the slop as stars in the sky. The glass half empty\ntake is these codebases are an irredeemable legacy mess. But glass half full\nis that there are many deterministic cores hidden somewhere inside, and maybe\nonly a handful.
\nUsers of older Windows systems may remember the "Disk Defragmenter"; it took\nfiles whose contents were scattered physically across the spinning hard disk\nand made them contiguous. In an era where read speed depended on physical\ndistance on the media, this mattered a lot.
\nThere was something so satisfying about seeing the red segments slowly give\nway to the blue.
\nSo one gradual approach for existing code is to practice the Defragmentation\nof Determinism. Identify it wherever you can - files, classes, even a few\nlines in individual functions - and start collecting them. The more\ndeterminism that can be grouped, the more easily testable functionality you\nhave, and the more you can feel confident about the behaviour and reliability\nof the program as a whole. The surface area for "hard to test"\n(non-deterministic code) starts to shrink. On a large enough codebase you will\nlikely never get to a single deterministic core, but even hundreds is better\nthan thousands.
\nEvery nasty mess of a codebase I've seen has one or more much nicer\ndeterministic state machines locked inside. I promise you they are there, even\nif it's not obvious. And once you find them, you'll be delighted with how much\neasier the software is to modify and test. Piece by piece, reliability can be\nwrought.
\n