The Migration I Keep Not Doing

Frank Duffy’s shearing layers, and what your own reluctance is measuring

The spec is written. It is called The Doppler Shift, which was funnier before it became an indictment. Move secret management off Infisical, onto Doppler. Per project the work is small: point the client at a new provider, move the values, verify the build, delete the old integration. An afternoon.

I have not started, and I have not started for months.

The reason I give myself is the project count. Too many repos, too many deploy targets, too many places a secret gets read. That reason is true and it is also the diagnosis, which took me an embarrassingly long time to notice.

Layers of longevity

Frank Duffy, the British architect, argued that there is no such thing as a building. What there is instead is several layers of longevity, bundled together and pretending to be one object. Stewart Brand took the idea, gave it six alliterative names in How Buildings Learn, and made it famous: site, structure, skin, services, space plan, stuff. Each layer changes on its own clock. Site is geological. Structure lasts centuries. Skin gets re-clad every twenty years, services every ten to fifteen, the space plan whenever the tenant changes, and the stuff moves every Tuesday.

Buildings fail at the joins. Brand’s word for the interesting part is shearing: the friction where a fast layer is trapped inside a slow one. Cast the pipes into the concrete and you have not saved money, you have bought a demolition. The plumbing will need replacing four times before the structure does, and each time you will take a hammer to a wall that was fine.

All buildings are predictions, and all predictions are wrong. So are all systems. The design question is never whether you got it right. It is whether you left yourself the tools to change.

The mapping, and its limits

Applying this to software is not a new thought and I want to be honest about that up front. IBM Research published a shearing-layers approach to information systems in 2000. Gartner turned it into pace-layered application strategy in 2010, credited to Duffy and Brand, and sold it to every enterprise architect with a budget. Jeremy Keith mapped it onto the web stack in Resilient Web Design. If you read this far expecting a novel metaphor, the metaphor is thirty years old.

The mapping itself is quick:

Site is jurisdiction. Regulatory regime, market, the law that reaches your data. You do not move it. You build for it. The CLOUD Act is a site condition, not a design decision, which is why data residency and data sovereignty are different questions and only one of them is answered by choosing a region.

Structure is the data model. Schema is load-bearing. Migrations are underpinning work carried out with the building occupied and the tenants complaining.

Skin is the interface. UI, published API surface, anything a stranger touches. Weathers, dates, gets re-clad on roughly a twenty-year cycle in building years and a two-year cycle in ours.

Services are the working guts. Auth, payments, secrets, observability, CI, hosting. Wear out, get replaced, on a schedule everyone accepts in principle.

Space plan is module boundaries, routing, code organisation. Interior walls. Moved often, cheaply, and badly.

Stuff is config, feature flags, copy, prompts. Daily churn.

Useful as far as it goes. What interests me is the three places it stops being true, because those are the places the metaphor earns money.

One: layers get captured

In a building, physics enforces the ordering. A chair does not become a load-bearing column, however long it sits there. Nothing in software prevents it.

Fast things ossify into slow things without a decision being made anywhere. A feature flag added for a two-week rollout is still there two years later and three code paths now assume it. Config accretes into schema. A prompt becomes an interface contract the moment a second system parses its output. Nobody promoted these things. They just stayed still long enough to set.

Buildings inherit their layer discipline from gravity. We have to impose ours, and we have to keep imposing it, because the default direction of travel is downward: everything sinks toward structure if you leave it alone.

Two: your skin is somebody else’s structure

Publish an API, a URL scheme, a file format, and you have handed your cladding to a stranger to use as footings. Hyrum’s Law is the formal version: with enough users, every observable behaviour of your system is depended on by somebody, regardless of what you documented.

Buildings have no equivalent. No one’s foundation depends on your facade. In software the fast layer becomes load-bearing for someone outside the building, and you find out when you repaint.

Three: cost does not track slowness

The metaphor implies that slow layers are expensive and fast layers are cheap. Often true, and the exceptions are vicious.

Changing a schema is a known quantity: migration, backfill, cutover, done. Moving a button that four hundred people press without looking is a change to the fastest layer in the stack, and it is more expensive than the schema, because habit is load-bearing and habit lives in the stuff.

What the reluctance measures

Which returns me to Doppler.

Secret management is a services-layer concern. It belongs with the plumbing: standardised, replaceable, on a cycle. A services swap should be tedious and bounded. Point at new provider, verify, move on. The cost should scale linearly with project count and nothing else.

Mine does not, and I have been treating that as a scheduling problem rather than reading it as a signal. The reason I am avoiding the work is that Infisical is not sitting in the services layer. It has leaked. Environment variable names assume its shape. Build scripts assume its CLI. Some deploy targets have it wired one way and some another, because each was set up on a different day with a different amount of care, and every one of those small inconsistencies is a pipe cast into a wall.

The migration is not hard because there are many projects. It is hard because each project made its own private treaty with the secrets provider, and I now have to renegotiate every one of them individually. That is the shear. My dread is a measurement of it, and it was an accurate measurement long before I bothered to read the dial.

There is a cheerful reading available here, and I am going to take it. The migration is worth doing on its own terms, and it is worth more as an audit. Every project where the swap is boring proves the layer held. Every project that fights back is showing me exactly where a fast thing got cast into a slow one, and the fix for those is not a better secrets provider. It is an interface: one shape the application expects, one adapter behind it, provider swapped in a single place next time.

I will be doing the migration in the order of most dread first, on the theory that the ones I want to do least have the most to teach me.

The rule underneath

“Make sure you have the tools to change” is too general to act on, so here is the operational form:

Never cast a fast thing into a slow one. When something on a two-year clock gets embedded in something on a ten-year clock, you have bought yourself a demolition, and you will not find out the price until you try to move.

And the test is free. Take any dependency you know you will replace one day, and ask what it would cost to swap tomorrow. Not the plan, the number. If the answer arrives as a feeling rather than a figure, and the feeling is dread, you already have your answer. You have simply been declining to write it down.

I had the spec for four months before I understood what it was telling me.

Alex