← Back to blog

Origami Mathematics and the Art of API Evolution

One crease pattern can fold into any shape. So can one clean API foundation. The same mathematics that promises this also names the price, in layers that double per fold and a single cut that can beat a thousand of them.

Published July 2026 · 11 min read · API design / backwards compatibility / origami mathematics


There is a result in the mathematics of paper folding that sounds like it belongs in a fantasy novel. Take a square sheet, score it with a particular grid of creases called box pleating, and that single fixed pattern of folds can be collapsed into any shape you can build out of unit cubes: an L, a staircase, a blocky little dog, a model of a building. Not a different pattern for each shape. The same pattern, folded differently, for all of them. Nadia Benbernou, Erik Demaine, and their collaborators proved this in 2009, and the startling part is stated right in their abstract: earlier universality results in origami had needed a bespoke crease pattern for every target, and this one does not. One well-designed set of creases, and the space of things it can become is enormous. If you have ever designed a system meant to last, that sentence should give you a small pleasant chill, because it describes the dream behind every API you have ever shipped. One clean, well-factored foundation that quietly folds itself into whatever the future turns out to need.

The company that has lived this dream most publicly is Stripe, and the way they do it is almost eerily close to the origami. Stripe has kept its API backwards-compatible with every version since the company began in 2011. A developer who wrote their integration in 2012 can, in principle, still run that same code today, untouched, and it works. Underneath, Stripe's engineers do not maintain fourteen years of branching version logic smeared through the codebase. They write for exactly one version, the latest, and a single component they call a response compatibility layer transforms the modern response backward into whatever dated shape each old client is still pinned to. That is the universal molecule rendered in software: one flat, current sheet of logic, folded through a chain of transforms into the precise form each historical client still expects. And the rule that decides which changes are legal is exactly origami's rule. You may add. New resources, new optional parameters, new fields on a response, all fine, because none of them disturbs anyone already there. What you may not do is take something away or change what an existing call returns, because that is a cut, and a cut tears someone's working integration.

Why the ban on cutting is so absolute has a name: Hyrum's Law. Hyrum Wright's formulation deserves to be quoted exactly: “With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.” Not the behaviors you documented. All of them. If an endpoint happens to return results in a certain order, someone relies on that order. If a bug has sat there long enough, someone has built on the bug. Once enough people are folding their own work into the creases of your system, every crease becomes load-bearing, whether you meant it to be or not. Folded paper obeys the same discipline, as a matter of plain geometry. The local laws of flat-foldability, Maekawa's theorem that the mountain and valley folds meeting at any interior point differ by exactly two, and Kawasaki's that the angles around that point alternate to a fixed sum, together mean that no single crease is independent. Each one constrains its neighbors, so you cannot re-cut one fold in a finished model without forcing every fold around it to shift. Linux turned this into a moral commandment. Linus Torvalds' unbending rule is that if a kernel upgrade breaks a program out in userspace, the kernel is what is wrong, every single time, and “we do not break userspace.” The constraint is not a nuisance the great long-lived systems merely tolerate. It is a large part of why they got to be long-lived.

So far this is a love letter to a constraint, and the constraint has earned some of it. But the same body of mathematics that promises you can fold anything also tells you, in the fine print, precisely what the promise costs, and this is where the honest version of the analogy earns its keep. Begin with the phrase everyone skips. The famous universality theorems do not say you can fold any shape from a sheet. They say you can fold it from a sufficiently large sheet. When Demaine and colleagues proved in 1999 that a single square can be folded into any polyhedron, the method was to fold the square down into a long thin strip and wrap it around the target like a mummy, elegant as an existence proof and absurd as a practical technique, and possible only if the sheet is big enough to do all that wrapping. Universality is a claim about what is possible, not about what is affordable. And the cost is not gentle. When you fold a sheet in half, the number of layers doubles, then doubles again, two, four, eight, sixteen. Britney Gallivan, then a high-school student, worked out the exact relationship in 2002 and then proved it by folding a roughly three-quarter-mile roll of tissue, about four thousand feet, in half twelve times, demolishing the old belief that no sheet can be folded more than seven or eight times. Her result makes the trap explicit: the paper you need grows like two-to-the-n, so every additional fold demands exponentially more sheet than the one before. The generality is real. It is also, quite literally, exponentially expensive.

Map that back onto the API and the picture stops being a love letter. Every backwards-compatible change is a fold, and the layers compound the same way. Stripe's compatibility layer is not one transform; it is a chain of them, one for every version boundary since 2011, and each new dated version lays another fold on top of all the previous ones. Windows carries decades of them. The sheet is still, technically, one piece, but past enough folds the crease pattern turns unreadable and the next fold needs more room than the last. This is the first asterisk on the dream: universality guarantees you can keep folding, and says nothing whatever about whether anyone will still be able to understand what you have folded. A finished Robert Lang insect, folded from one uncut square, can carry thousands of creases. That is honestly what a never-cut API becomes over a long enough life, and Stripe's layer, for all its discipline, is real code that real engineers have to keep alive forever. Folding is not free. It is deferred, and it compounds. And the thing you most want from the rule turns out to be inseparable from the thing you least want. The additive-only discipline is what guarantees you never break a client, and it is the identical discipline that guarantees the layer count only ever grows and never shrinks. Longevity and cruft are not two outcomes you get to trade against each other; they are one mechanism wearing two faces. The API lasts because it never removes anything, and it silts up because it never removes anything. Every system that has survived long enough to be worth depending on is, for precisely that reason, carrying more folds than any single person can hold in their head.

The second asterisk is deeper, and it is the point where the analogy honestly breaks, which is the most useful thing an analogy can do. Origami folds toward a known target. Lang's universal molecule, the algorithm at the heart of his design software, does not start with a sheet and discover a shape. It starts with the shape. You hand it a description of the tree-like figure you want, a body with these six legs and these two antennae, and it computes the crease pattern that yields exactly that. You fold because you already know you want the crane. An API designer is in the opposite situation, and no theorem can rescue them from it. You lay down your earliest creases, your first endpoints, your first data model, your first optional parameters, before you have any real idea what shape the system will eventually be asked to take. The use cases that will matter most in 2032 have not been imagined yet. And because of Hyrum's Law and the interdependence of creases, every early fold quietly constrains the late ones. So the theorem's clean guarantee, that any shape is reachable, does not actually transfer. Any known shape is reachable. What an API commits you to is a run of irreversible folds against a target that nobody has drawn. That is a fundamentally harder game than origami, and pretending otherwise is how systems fold themselves into a corner one reasonable, backwards-compatible decision at a time.

Which brings us to the third asterisk, and the most satisfying one, because the rebuttal to “never cut” comes from inside origami itself. There is a theorem called the fold-and-cut theorem, and its earliest known statement is astonishingly old: a 1721 Japanese mathematics book by Kan Chū Sen posed a puzzle to fold a sheet flat and make a single straight cut to produce a particular family crest. The modern theorem, proved in full by Demaine and others, says something total. Any shape whose sides are straight, however intricate, with holes, even in several disconnected pieces, can be produced by folding the paper flat and making exactly one complete straight cut. One cut. The very canon that supplies the dream of folding anything without cutting also contains the proof that a single well-placed cut can produce any shape an unbounded pile of folds could, and frequently far more cheaply. That is the mathematical form of a thing every seasoned engineer knows in their gut. Python's maintainers made the cut on purpose. Python 3 shipped in 2008 as a deliberate breaking change, chiefly to fix the way the language handled text and Unicode, and the community then spent roughly twelve years, and a great deal of pain, migrating, with Python 2 finally laid to rest at the start of 2020. It was brutal. It was also, almost certainly, cheaper than folding correct Unicode handling into Python 2 forever, one compounding compatibility layer at a time. “Never cut” is not an engineering law. It is an aesthetic that origami adopts by rule and software adopts by habit, and the mathematics is clear that a refusal to ever cut can mean choosing a thousand exponential folds over one clean break.

So the practical thing to carry out of all this is neither “keep folding forever” nor “cut whenever it is convenient.” It is a more honest reading of the constraint you are actually under. The no-cut rule is genuinely generative. Forbidding yourself to break anyone is precisely what forces the disciplined, additive, compositional design that lets a Stripe integration from 2012 still run today, and that discipline is worth guarding closely. But the generativity and the exponential cost are the same fact seen from two sides. Every fold that keeps an old client alive also thickens the sheet, and there is a point, and here the mathematics is almost cruel about it, because deciding whether an arbitrary crease pattern can even be folded flat was proved NP-hard by Marshall Bern and Barry Hayes back in 1996, which is a formal way of saying you eventually cannot tell whether your next fold is safe, where the sheet has simply grown too thick to fold again. The mastery was never in the folding, which anyone can do until the paper refuses another crease. It is in reading the thickness: in knowing your own system well enough to feel the moment when the honest move stops being another decade of compatibility layers and becomes one clean, well-aimed, painful cut. The universal molecule tells you the shape is reachable. It is silent on the size of the sheet, silent on the order of your folds, and silent on whether you will even recognize the target when you finally reach it. Those three silences are where the actual work lives.


Sources

Hyrum's Law says every observable behavior gets depended on. The mastery is reading the thickness, and you cannot read what you did not record.

Knowing when the honest move is one clean cut instead of another compatibility layer means knowing which of your system's behaviors are actually load-bearing, which is a question about what it has really done, observed and kept. For agents, that record is provenance. Chain of Consciousness gives an agent's output a durable, tamper-evident account of what it did, from what inputs, when, so the observable behaviors others fold their work into are things you can see rather than guess. You cannot read the thickness of a sheet you never measured.

See Hosted Chain of Consciousness  ·  Read the Theory of Agent Trust

pip install chain-of-consciousness  ·  npm install chain-of-consciousness

Or the whole trust stack at once: pip install agent-trust-stack / npm install agent-trust-stack