Published Commitments And The Debt You Cannot Refactor

Technical debt is a useful metaphor with one property that quietly does all the work: you can pay it off unilaterally. The messy module is yours. The team that wrote it can rewrite it on a Tuesday, and provided the behaviour at the edges is preserved, nobody outside needs to know or consent.

There is a second category that looks similar, gets discussed in the same meetings, and behaves nothing like it. Once something has been published, the coupling is no longer internal. A published REST endpoint, a price list, a filed statement to a regulator, a licence granted to a distributor, a commitment in a contract, a plot point in a story people have already read — each of these is a constraint held by someone outside your organisation, and you cannot refactor it, because refactoring requires both sides and you only have one.

This category has three properties worth taking seriously, and none of them is true of ordinary technical debt.

It accumulates monotonically

Internal debt goes up and down. Published commitments only go up. Every release adds surface, and the surface never shrinks on its own. A field added to a response is a field someone will parse. A promise made in a keynote is a promise recalled in a renewal negotiation. An episode that establishes a character was somewhere on a particular night has fixed that fact for every future episode.

The rate matters more than the level. A team shipping ten times as often, which is what the rest of this library is largely about achieving, is also accreting external commitments ten times as fast. That is a cost of speed which does not appear in any flow metric, and it is the one genuine argument for slowing down that this library will make.

Removing one is a breaking change, priced in trust

You can withdraw a published commitment. The mechanism exists in every domain: deprecate the endpoint, reprice, correct the filing, retcon the plot, renegotiate the licence. What you cannot do is make it free.

The cost is not primarily the migration work. It is that every future commitment you make is now discounted by everyone who watched you withdraw this one. This is why long-lived platforms are conservative in ways that look irrational from inside — the visible cost of maintaining a deprecated API is small and the invisible cost of having broken one is not, and only one of them shows up in a backlog.

The literature calls this Hyrum's Law from the software side: with enough consumers, every observable behaviour of your system is depended on by somebody, regardless of what you documented. The general form is broader. With enough audience, every observable commitment is depended on by somebody, regardless of what you intended to promise.

The consumers are outside your control and you cannot enumerate them

This is what makes the arithmetic genuinely different. Internal coupling can be found — grep the monorepo, read the call graph, ask the four teams. External coupling cannot be enumerated at all. You do not know who parses that field, who quoted that price in a board paper, who built a theory on that detail, who is relying on the thing you said in passing.

So the question "can we change this" has no answer available to you by inspection. It is always a probability estimate, and the estimate gets worse the more successful you are.

The practical consequence: publish less than you know

If commitments accumulate monotonically, are expensive to remove and cannot be enumerated, then the operative discipline is at the moment of publication rather than afterwards. Every release is also a decision about how much future optionality to spend, and that decision is usually made by default.

Underspecify deliberately. Say the thing you need to say and not the adjacent thing you happen to know. Return the field the consumer needs, not everything the query produced. State the price for the term you are committing to, not the philosophy behind it. Establish that a character was away, not the city, hotel and date — unless the city, hotel and date are load-bearing right now. Precision that is not doing work today is optionality spent for nothing.

This is genuinely hard to do, because in the moment specificity feels like quality. Texture is what makes writing good and detailed documentation is what makes an API usable. The discipline is not vagueness; it is noticing which details you are committing to versus merely mentioning, and being deliberate about the first.

Separate the published surface from the internal one, explicitly. Software has a good vocabulary for this — public API versus internal, stable versus experimental, supported versus best-effort — and most other domains have none. The equivalents are worth inventing: which facts are canon and which are one storyteller's colour, which numbers are committed and which are illustrative, which statements are positions and which are musings.

If you never mark the line, everything you publish is treated as being on the committed side of it, because your audience has no way to tell.

Build the cheap oracle for the commitments you have made. The expensive failure is contradicting yourself in public. That is mechanically checkable far more often than people assume: a register of established facts, a diff of published figures against the last statement of them, a compatibility test against the previous release, a list of active licence terms. This is the same partial-oracle argument that appears in the verification piece, applied to consistency rather than quality, and it is the one place where automation genuinely substitutes for memory.

Rights are the extreme case

Intellectual property deserves a paragraph here rather than a page, because it is the same structure with the escape hatch removed.

A rights grant — a licence, an option, an assignment, a publishing term — is a published commitment that you cannot unilaterally withdraw even at the cost of trust, because it is enforceable. An exclusive territory granted in year one constrains every deal in year five. A work-for-hire arrangement not written down constrains whether you can license at all. Chain of title is, in precisely the technical sense, a dependency graph, and an unresolved node in it blocks the whole build.

The operational point is the one that generalises: these are commitments made at speed, early, usually by people not thinking about flow, and they bind hardest exactly when the property becomes valuable enough to matter. The same "underspecify deliberately" discipline applies — grant the term you need to grant now, not the broader one that is easier to agree. Everything beyond that is a question for a lawyer, and this library is not one.

Versioning is the only real escape hatch

The one structural answer, and it is the same answer everywhere, is to make the break explicit and bounded rather than gradual and deniable.

Software calls it a major version: v1 keeps working, v2 is a different contract, both are documented, and consumers move on a stated timeline. Publishing calls it a new edition. Serialised fiction calls it a reboot, a continuity, a separate universe. Regulated reporting calls it a restatement. In every case the move is identical — declare a boundary, state which commitments survive it, and support the old surface for a named period.

What does not work, in any of these domains, is quietly changing the thing and hoping the dependency was not real. It is always real, it is always found, and the cost arrives later and larger, denominated in the trust you will want to spend on something else.

What to do on Monday

1. Write down, in one list, everything you have published that someone outside could be depending on: API surface, prices, public commitments, established facts, granted rights. The exercise usually takes an hour and the list is always longer than expected.
2. Mark each one committed or incidental. Then ask whether your audience could tell which is which from the outside. Where they could not, they are all committed.
3. Find the most recent thing you published and identify the detail you included because it felt good rather than because it was needed. That is the shape of the habit.
4. Check the accumulation rate. How much external surface did you add this quarter compared with last? If delivery has got faster and this number has not been looked at, it has gone up and nobody has priced it.
5. Build one consistency check against your own published record — figures, facts, terms, whichever you contradict most often.
6. Decide, before you need it, what a version boundary looks like in your domain and what you would call it. The worst time to invent that is the week you need one.