I keep noticing the same pattern in systems that last.

The interface is tiny. You can teach it in minutes. The contract behind it (the expectations about behavior and edge cases) is enormous.

And the two evolve at completely different rates.

Unix pipes are the cleanest example. The interface is stdin and stdout. Byte streams. Nothing in the pipe mechanism cares whether you're sending JSON or binary garbage. But the convention, "text lines, one record per line, fields separated by whitespace or a delimiter," is what makes grep | sort | uniq -c work.

Fifty years later, pipes haven't changed.

JSON lines came along and the interface didn't budge. The contract expanded to cover a new encoding.

HTTP is the same shape at a bigger scale. GET, POST, PUT, DELETE, headers, a body. I can teach someone the interface in ten minutes. The contract runs thousands of pages across dozens of RFCs: caching semantics, content negotiation, idempotency, conditional requests, auth schemes.

The interface hasn't meaningfully changed since 1997. HTTP/2 and HTTP/3 changed the transport, not the interface.

The ratio between interface and contract keeps growing, and the systems keep working.

the sideband pattern

I think this explains why some systems become infrastructure and others don't.

The ones that last have a thin mandatory core and a rich sideband. The core is what every participant must understand. The sideband is everything else: hints, extensions, optional behaviors participants can read or ignore.

The core stays stable for years. The sideband evolves based on what people actually need.

HTTP's core: method, URL, status code. HTTP's sideband: headers. A server from 1997 ignores headers it doesn't recognize. A server from 2026 uses dozens of them.

Both work.

This is how contracts should grow. Start thin. Watch what hints consumers send and what providers parse. Promote the universal ones to the core contract.

Host was optional in HTTP/1.0. It became required in HTTP/1.1 because every real-world client was already sending it. Organic promotion based on actual usage, not speculative design.

the missing half

Plugin systems got the interface half right.

They missed the contract half entirely.

Kubernetes CRDs are a good example. You define a custom resource type, write a controller that watches for instances, the controller reconciles desired state with actual state. Clean interface. But there are no shared contracts across operators. A PostgreSQL operator from Company A and one from Company B expose completely different CRD schemas with different field names and different semantics.

You can't swap one for the other.

The interface is interchangeable. The contracts aren't, because there are no shared contracts.

The missing piece is shared behavioral contracts across providers. Not a thin interface that every provider implements (that's table stakes). Contracts with enough structure to validate against, but loose enough to evolve through the sideband pattern.

I've been building something along these lines. More on that in a later post.

what changes when the implementation can reason

There's a question that's been nagging at me.

Every system I described has dumb implementations behind the contract. grep doesn't reason about its input. An HTTP server doesn't infer what a client meant by a malformed request. Traditional contracts need to specify everything because the thing on the other side can't fill in gaps.

Every edge case needs a rule.

The interesting question: what happens when the implementation layer can reason? Say it can read a contract description and infer the right behavior for cases the contract doesn't explicitly cover. How thin can the contract actually get?

I think this changes things fundamentally. I'll write about why next.