Guarantees, not shapes

Someone outside your system asks how it works, and the generous answer is the dangerous one. Send them the object model, the field names, the storage layout, the sequence of states a record passes through, and you have been transparent in a way that feels like respect. What you have actually done is hand them a set of facts they will now build against, none of which you ever promised to keep.

The distinction that matters is between a guarantee and a shape. A guarantee is a claim about what will remain true. Identity is stable. A constraint is enforced. An export is complete. A shape is how the thing currently happens to be arranged, and it is every bit as factual and not remotely the same kind of statement. The test that separates them is a single question asked of each sentence before it leaves the building, which is whether the person reading it would have to change their own artifact if the fact stopped being true. If the answer is no, the sentence is machinery. Publishing machinery does not inform a counterparty; it recruits them into depending on a decision you made for reasons that will expire.

The mechanism is that observability, not the contract, sets the boundary of what someone will depend on. Hyrum Wright’s law states it in the form the field now quotes: with a sufficient number of users of an interface, all observable behaviors of your system will be depended on by somebody, whatever the written contract promises. The document you wrote is not the surface. The surface is everything they can see. And the accidental part is genuine, because nobody involved has to be careless for it to happen. Your counterparty read a fact, treated it as stable because you published it, and shipped. Their build now encodes it. You have acquired an obligation without a negotiation, a price, or a review, and you will discover it on the day you try to change the thing.

Two engineering cultures have paid this bill in public and drawn opposite conclusions. The Linux kernel treats it as an obligation it accepted rather than a mistake somebody else made: a change that breaks a working user program is a defect in the kernel, and the position has held for three decades against considerable inconvenience. Windows treats it as an operating cost, shipping application-specific compatibility shims so that programs relying on behavior no document ever promised keep running across releases. One project refuses to break what people depend on; the other builds a permanent department to keep the broken things working. Both responses are honorable and both are expensive, and neither culture chose the dependency it is now maintaining.

The saving grace is that the counterparty almost never wanted the machinery in the first place. They wanted to know whether their thing keeps working, and that question is answered at the altitude of promises. Tell them identity is stable and you have told them everything a stable identity implies for their design, without pinning yourself to the representation that delivers it today. Tell them exports are complete and you have said the useful thing without freezing a format. This is the discovery that makes the whole discipline affordable rather than merely principled: candor and confidentiality were never opposed, because the sentences worth publishing and the sentences worth protecting turn out to be different sentences. Say what will hold, keep what will change, and you have given somebody something they can build on for years without spending a single guarantee you did not mean to make.