Hyrum's Law¶

With enough users of an interface, every observable behaviour will come to be depended upon by someone regardless of the formal contract, so the cost of changing an observable is set by its dependent count, not its documented status.

Core Idea¶

Hyrum's Law, formulated by Hyrum Wright and popularised in Winters, Manshreck, and Wright's Software Engineering at Google (2020), is the principle that with a sufficient number of users of an interface, it does not matter what is promised in the formal contract: every observable behaviour of the system will come to be depended upon by somebody, and any change to that observable behaviour — even one outside the documented specification — will break someone's code.

The structural claim is that a software interface produces two distinct contracts simultaneously: the published contract, which specifies the supported and promised behaviours; and the de facto contract, which is the set of observable behaviours that some user population has discovered and built dependencies on, whether or not those behaviours were ever promised. The de facto contract is always at least as large as the published contract and, under sufficient scale and time, approaches the entire observable surface of the implementation — including error message text, iteration ordering, timing characteristics, edge-case handling, and undocumented side effects. The mechanism is enumeration under scale: given a large and diverse enough user population, every observable property of a system is sampled by some user, and at least one of those users incorporates that property into production code, either deliberately (copying an undocumented error code into a matcher), by accident (tests that happen to check byte-for-byte serialisation output whose order was never guaranteed), or because no documented alternative was available. From the provider's perspective, any subsequent change to that observable — even a change to something never promised and never intended as an interface — incurs backward-compatibility cost proportional to the dependent count, regardless of what the contract says. The practical consequence is that minimising the observable surface of an implementation is a distinct and often more important discipline than minimising the contractual surface: hiding implementation details through encapsulation and indirection, adding jitter to timing, randomising iteration order proactively to prevent accidental dependencies from forming, and treating every observable from day one as a potential future de facto contract.

Structural Signature¶

Sig role-phrases:

the published contract — the formally specified, narrow set of supported and promised behaviours
the observable surface — everything a user can see the implementation do: timing, error-message text, iteration order, edge-case handling, side effects, performance
the user population — a base large and diverse enough that, by sheer enumeration, every observable is sampled by someone
the de facto contract — the union of observables that have accumulated external dependents; always ⊇ the published contract and, under scale and time, approaching the full observable surface
the enumeration mechanism — given enough users, each observable is discovered and built upon (deliberately, accidentally, or for want of a documented alternative), forming a dependency
the dependent-count cost rule — the backward-compatibility cost of changing an observable is set by its dependent count, not by its contractual status
the inert-vs-effective split — shrinking the contractual surface (documenting fewer methods, deprecation notices) does nothing to the de facto contract; only shrinking the observable surface (encapsulation, jitter, proactively randomized iteration order) prevents dependencies from forming
the telemetry instrument — "which observables have already accumulated dependents?" is empirical, answered by measuring actual reliance rather than reading the spec
the asymptotic regime — under sufficient scale and time the de facto contract approaches the observable surface and the published contract becomes nearly irrelevant to what can safely change

What It Is Not¶

Not a claim about the published contract. The cost of changing a behaviour is set by its dependent count, not by whether it was ever promised. Iteration order, error-message text, and timing — none of them documented — can be every bit as expensive to change as the formal API, so "that was never part of the contract" does not make a change safe.
Not the network effect. Both scale with user count, but the network effect scales value (the system is worth more as users grow) while Hyrum's Law scales constraint (the system becomes harder to change as users grow). Rising worth and rising rigidity are opposite consequences of the same growth, and conflating them misreads what the law predicts.
Not the Postel principle. "Be liberal in what you accept" governs the accept side of an interface — how inputs are tolerated; Hyrum's Law governs the observe side — how outputs and behaviours become depended upon. They are complementary, not the same: one concerns what the system ingests, the other what users can see and pin to.
Not Goodhart's Law. Both concern observability-driven distortion, but Goodhart is about a measure becoming a target once it is optimized against; Hyrum is about an observable becoming a contract once it is depended upon. The mechanisms differ — optimization pressure on a proxy versus dependency accretion on any visible behaviour.
Not generic legacy lock-in. Lock-in is the broad category; Hyrum's Law names one specific channel within it — observability under scale converting implementation details into de facto contracts. Other lock-in channels (data-format inertia, switching costs, network effects) are not Hyrum's Law, and treating it as a synonym for "things get hard to change" loses its precise mechanism.
Not fixed by documenting less. Shrinking the contractual surface — fewer documented methods, warnings, deprecation notices — does nothing to the de facto contract, because dependents form on observables regardless of promises. Only shrinking the observable surface (encapsulation, jitter, proactively randomized iteration order) prevents dependencies from forming; the contractual lever is inert.
Not a law of nature. It is an empirical engineering regularity stated in the asymptotic limit — "given a sufficient number of users." For a small or homogeneous user base the de facto contract need not approach the observable surface; the near-determinism holds only under enough scale and time, so it is a tendency that sharpens with users, not a physical certainty.

Scope of Application¶

Hyrum's Law lives across the subfields of software and computing where an interface accrues many users over time; its reach is within that domain — one substrate (a software interface with many users over time), the kind of observable changing but the mechanism constant. The underlying compound it instantiates (path_dependence through observability under scale-driven dependency formation) recurs far beyond software — customary law, descriptive linguistics, infrastructure co-option, biological spandrels — but that reach belongs to the compound (a future observable-surface-becomes-contract parent), not to "Hyrum's Law" as named. The habitats below are genuine in-domain uses.

API and protocol design — the canonical case: Kubernetes, Go, and web-platform evolution policy, with Torvalds' "we don't break userspace" operationalising the law for the Linux kernel down to preserving syscall bugs.
Library and SDK evolution — even unpublished helper functions and internal classes acquire dependents under scale, so refactoring them becomes a breaking change in practice.
Compiler and language design — undefined behaviour and type-inference quirks becoming load-bearing through real-world reliance, hardening into de facto language semantics.
Cloud and platform engineering — provisioning timing, error formats, and undocumented quotas ossifying into contracts that deprecation schedules underestimate.
Open-source dependency ecosystems — transitive imports amplifying the effect, every public symbol in an indirectly-imported library potentially relied upon by some consumer along some chain.

Clarity¶

Naming Hyrum's Law separates three things that API designers had routinely run together: the published contract (what the interface promises), the observable behaviour (everything a user can see the implementation do), and the de facto contract (the subset of observables that some user population has actually built dependencies on). The three are nested — observable behaviour exceeds the published contract, and under scale and time the de facto contract grows to approach the full observable surface — and most disputes about "but that was never part of the API" dissolve once a team can point at which of the three layers a given dependency lives in. The deeper confusion it removes is the belief that a behaviour's contractual status governs the cost of changing it. Hyrum's Law replaces that with a sharper rule: the backward-compatibility cost of changing an observable is set by its dependent count, not by whether it was ever promised, so iteration order, error-message text, and timing characteristics can be every bit as expensive to change as the documented surface.

The distinction this sharpens has a direct operational payoff — it makes minimising the observable surface legible as a discipline distinct from, and often more important than, minimising the contractual surface. Documenting fewer methods shrinks the contract but does nothing to the de facto contract; hiding implementation details behind encapsulation, adding jitter to timing, and proactively randomising iteration order shrink the observable surface and so prevent dependencies from forming in the first place. The productive questions the law lets a designer ask are not "what did we promise?" but "which observables have already accumulated dependents (a telemetry question), and which observables should we obscure from day one before they ossify into contracts?" It also draws clean boundaries against neighbors it is easily confused with: it is not the network effect (which concerns value rising with users, where Hyrum's Law concerns constraint rising with users), not the Postel principle (which governs the accept side of an interface, where Hyrum governs the observe side), and not generic legacy lock-in (the broader category of which this names one specific channel — observability under scale).

Manages Complexity¶

Interface evolution presents the maintainer with a pile of seemingly distinct headaches: legacy lock-in, deprecation that drags on for years, kernel-syscall conservatism that preserves even bugs, undocumented behaviors that ossify into requirements, "no breaking changes" policies that creep to cover things never promised, downstream tests that pin byte-for-byte output. Treated separately, each is its own war story with its own ad hoc remedy. Hyrum's Law compresses the pile to three nested sets and one cost rule. The sets are the published contract, the observable behavior, and the de facto contract, with published ⊆ observable and the de facto contract growing under scale and time to approach the full observable surface. The rule is that the backward-compatibility cost of changing any observable is set by its dependent count, not by its contractual status — so iteration order, error-message text, and timing characteristics can be exactly as expensive to change as the documented surface. From those, the maintainer reads the qualitative outcome off two parameters rather than re-litigating each dispute: how large and diverse the user population is (which fixes how far the de facto contract has spread across the observable surface), and how exposed a given observable is (which fixes whether it has likely accrued dependents). Most "but that was never part of the API" arguments dissolve once the team locates which of the three layers the dependency lives in, and the safe-versus-breaking question for any proposed change reduces to: is this observable inside the de facto contract? The branch structure is where the compression pays off operationally, because it cleanly separates an inert lever from an effective one. Shrinking the contractual surface — documenting fewer methods, posting warnings, emitting deprecation notices — does nothing to the de facto contract, since dependents form on observables regardless of promises. Shrinking the observable surface — encapsulation and indirection, jitter on timing, proactively randomizing iteration order before anyone depends on it — prevents dependencies from forming at all. So the maintainer's questions become tractable and few: which observables have already accumulated dependents (a telemetry question), and which should be obscured from day one before they ossify (a design question). The same dependent-count-versus-contract-status cut also places the neighbors without separate argument — the network effect scales value with users where this scales constraint, the Postel principle governs the accept side where this governs the observe side, and generic legacy lock-in is the broad category of which this names the one specific channel, observability under scale.

Abstract Reasoning¶

The first characteristic move is predictive under scale: from the size and diversity of an interface's user population, infer how far the de facto contract has spread across the observable surface, and therefore which observables are now load-bearing regardless of what was promised. The reasoning runs FROM "this interface has a large, diverse user base sustained over time" TO "by enumeration, essentially every observable property — error-message text, iteration order, timing, edge-case handling, undocumented side effects — has been sampled and depended upon by someone, so the de facto contract approaches the full observable surface." The law makes the prediction nearly deterministic in the asymptotic regime: given enough users and time, the published contract becomes almost irrelevant to what can safely change, and the maintainer predicts that even a behavior never intended as an interface (proto field-iteration order, a syscall bug) has acquired dependents and ossified into a contract.

The second move is diagnostic on the cost of a proposed change, replacing contractual status with dependent count as the operative variable. Faced with a change, the analyst does not ask "did we promise this?" but "is this observable inside the de facto contract, and how many dependents has it accrued?" — so the reasoning runs FROM "this change touches iteration order / error text / timing, which was never documented" TO "its backward-compatibility cost is set by its dependent count, not its contractual status, so it may be exactly as breaking as a change to the documented surface." The move resolves most "but that was never part of the API" disputes by locating the dependency in one of the three nested layers (published ⊆ observable, with the de facto contract in between), and it makes telemetry the decisive instrument: the question "which observables have already accumulated dependents?" is empirical, answered by measuring what users actually rely on rather than by reading the spec.

The third move is interventionist with a sharp inert-versus-effective split, and it is where the law pays off operationally. Because dependents form on observables regardless of promises, the analyst predicts that shrinking the contractual surface — documenting fewer methods, posting warnings, emitting deprecation notices — does nothing to the de facto contract, while shrinking the observable surface — encapsulation and indirection, jitter on timing, proactively randomizing iteration order before anyone depends on it — prevents dependencies from forming at all. So the reasoning runs FROM "we want this behavior to remain changeable" TO "obscure it from day one, treating every observable as a future contract, rather than merely declining to document it," with the predicted effect that proactively injecting variability (Google's build-time jitter on proto iteration order) stops new dependencies forming exactly as the law's mechanism implies. The move also supports a counterfactual and a boundary-drawing inference: asking "what would this system look like with ten users instead of ten million?" exposes how much present structure is Hyrum's-law fossilisation rather than intrinsic complexity, and the dependent-count-versus-contract-status cut places the neighbors — the network effect scales value with users where this scales constraint, the Postel principle governs the accept side where this governs the observe side, and generic legacy lock-in is the broad category of which this names the single channel, observability under scale.

Knowledge Transfer¶

Within software and computing Hyrum's Law transfers as mechanism, cleanly and across the full range of software substrates. The three nested sets (published contract ⊆ observable behaviour ⊆ — under scale and time — the de facto contract), the dependent-count-not-contractual-status cost rule, the predictive-under-scale reasoning, and the inert-versus-effective intervention split (shrink the observable surface, not merely the contractual one) all carry intact across API and protocol design (Kubernetes, Go, web-platform evolution; Linus Torvalds' "we don't break userspace," which operationalises the law for the kernel down to preserving syscall bugs), library and SDK evolution (even unpublished helpers acquire dependents), compiler and language design (undefined behaviour and type-inference quirks becoming load-bearing through reliance), cloud and platform engineering (provisioning timing, error formats, undocumented quotas hardening into contracts), and open-source dependency ecosystems (transitive imports amplifying the effect along every chain). Across all of these only the kind of observable changes — iteration order, error text, timing, side effects — while the mechanism (enumeration under scale converts any observable into a de facto contract), the telemetry-as-decisive-instrument move, and the defensive-randomisation remedy stay constant, because the substrate is one: a software interface with many users over time.

Beyond software the honest report is a strong (B): the underlying compound genuinely recurs across substrates as co-instances, not as loose metaphor, because the shape — observable behaviour plus many dependents over time yields an effective constraint exceeding the nominal contract — is substrate-independent. It is customary and constitutional law (long-observed government practice hardening into binding convention; doctrines of practice and acquiescence in international law), linguistic descriptivism (persistent usage in a population becoming the language regardless of prescriptive rules), infrastructure co-option (bridges, roads, and buildings used beyond design parameters becoming hard to restrict to those parameters), and biological spandrels (incidental anatomical or behavioural features becoming load-bearing through downstream evolutionary co-option). Each shares the same skeleton — but the key honesty is that the skeleton is a compound of existing catalog primes, not a fresh commitment unique to Hyrum's Law: it is path_dependence / lock_in_and_path_dependence operating specifically through observability under scale-driven dependency formation. That compound is what travels, and any cross-domain lesson should be carried by it (a future parent prime, observable surface becomes contract, would reasonably cover software, customary law, descriptive linguistics, and infrastructure co-option together). Hyrum's Law is the canonical, sharpest, most useful software instance of that compound — and what stays home-bound is its software-specific cargo: the published/observable/de-facto-contract vocabulary, the asymptotic "every observable is a contract" framing, and the concrete interventions (encapsulation and indirection, build-time jitter, proactively randomised iteration order, dependency telemetry). Strip the jargon and the residue — "what users can observe and depend on becomes binding regardless of what was formally promised" — is already implied by path dependence under observable accumulation; the genuinely added, domain-specific lessons are that the de-facto-contract growth rate scales with user count and that the observable surface, not the contractual one, is the operand to manage. Two boundaries travel with the mechanism and keep it from being confused with its kin: it is not network_effect (which scales value with users where this scales constraint), not the Postel principle (which governs the accept side where this governs the observe side), and only adjacent to goodharts_law (both concern observability-driven distortion, but Goodhart concerns a measure becoming a target). The boundary to mark, then, is that the cross-substrate reach is genuine shared mechanism — carry it via the path-dependence-through-observability-under-scale compound (and its cousins in customary law, linguistics, infrastructure, and spandrels) — while "Hyrum's Law" is the software-API instantiation that adds the contract vocabulary and the encapsulation/jitter/telemetry toolkit on top. See Structural Core vs. Domain Accent.

Examples¶

Canonical¶

The example that gave the law its name inside Google concerns Protocol Buffers. The serialization format explicitly does not promise any particular order when iterating a map field or serializing certain structures — the documented contract leaves order unspecified. Yet across Google's enormous internal codebase, code and tests accreted that implicitly relied on the order actually produced (for example, tests asserting byte-for-byte equality of serialized output). Changing the implementation's order — a change entirely within the promised contract — broke real code. Google's response was not to add documentation saying "do not rely on order," which would have changed nothing, but to deliberately perturb the observable: introducing intentional, build-varying randomization into iteration order so that no new code could form a stable dependency on any particular order in the first place.

Mapped back: "Order is unspecified" is the published contract; the actual byte order emitted is part of the observable surface. Google's vast internal userbase is the user population whose enumeration mechanism turned order into part of the de facto contract, so breakage followed the dependent-count cost rule despite the contract. Adding build-time jitter is the textbook inert-vs-effective split: not documenting less, but shrinking the observable surface itself.

Applied / In Practice¶

Microsoft's backward-compatibility engineering for Windows is a decades-long field deployment of the same logic. The classic case, recounted by Raymond Chen: the original SimCity for Windows read a block of memory shortly after freeing it — harmless under the old allocator, which left the contents intact, but a use-after-free bug. When Windows changed its memory management, the observable behaviour SimCity depended on vanished and the game crashed. Rather than tell users the app was at fault, Windows 95 shipped a compatibility shim: it detected SimCity and restored the old allocation behaviour for it. Microsoft generalised this into an entire Application Compatibility infrastructure precisely because millions of shipped programs had come to depend on undocumented, unpromised observable behaviours of the OS.

Mapped back: The old allocator's habit of leaving freed memory readable was an observable surface feature never in the published contract; SimCity's reliance made it part of the de facto contract. Breaking a wildly popular program invoked the dependent-count cost rule — cost set by dependents, not by the fact that the app was technically buggy — driving Microsoft to preserve the behaviour, the constraint-rises-with-users signature of the asymptotic regime across the Windows install base.

Structural Tensions¶

T1: Defensive perturbation versus the predictability users legitimately want. The law's sharpest remedy is to shrink the observable surface — encapsulate, add timing jitter, proactively randomize iteration order — so that no stable dependency can form. Google's build-time jitter on proto iteration order is the textbook move. But deterministic, predictable, inspectable behaviour is itself a value: it aids debugging, reproducibility, caching, and performance, and users depend on stable output for legitimate reasons, not only accidental ones. Deliberately injecting variability to protect your freedom to change later degrades the very predictability that makes a system pleasant and cheap to build on. The tension is that observability is simultaneously the channel through which crippling constraints accrete and a genuine feature users need — so the provider cannot obscure everything without making the system worse to use. Diagnostic: Would perturbing this observable to keep it changeable cost users a predictability they legitimately need, or only foreclose an accidental dependency?

T2: Stability guarantees versus the freedom to fix and simplify. Honouring the law at the limit — "we don't break userspace," down to preserving syscall bugs — buys users iron-clad stability and trust. But the same discipline means the implementation can never be cleaned up: every wart, every accidental behaviour, every bug that someone came to rely on is frozen into the de facto contract forever, and the system accretes irreducible cruft it is forbidden to shed. Stability for existing users and evolvability for the maintainer are traded directly against each other, and the more successful the interface (the more dependents), the more completely evolvability is sacrificed. The tension is that the law converts every observable into a liability, so the reward for wide adoption is a permanent inability to improve the internals. Diagnostic: Is this behaviour being preserved because users genuinely need it, or because the law's stability norm has frozen a defect the system would be better without?

T3: Asymptotic determinism versus operational paralysis. "With enough users, every observable becomes a contract" is nearly deterministic in the limit, which is what gives the law its predictive punch. But taken literally as a design rule it counsels paralysis: if everything observable is load-bearing, then nothing can safely change, and the maintainer is frozen. The law's power as a prediction and its uselessness as an unqualified directive pull apart, and the gap is bridged only by dropping back to the empirical dependent count — telemetry, not the asymptotic claim, is what actually tells you which observables to protect. The tension is that the law is most true exactly where it is least actionable: in the asymptotic regime it describes a ceiling of total constraint that no maintainer can act on without the finer-grained reliance data the law itself does not supply. Diagnostic: Is a change being blocked because measured dependents actually rely on this observable, or merely because the law says someone eventually will?

T4: Treat-every-observable-as-a-contract versus premature over-engineering. The law counsels obscuring observables from day one — before anyone depends on them — because retrofitting encapsulation after dependencies form is far more expensive. Prudent. But applied indiscriminately it means encapsulating, indirecting, and jittering everything up front, at real cost in complexity and effort, to defend against dependencies that most observables will never actually attract. On day one you cannot know which observables will accrue dependents and which are irrelevant, so proactive obscuring is a bet placed under ignorance, and over-defending is its own waste. The tension is that the cheapest time to act (before dependencies form) is also the time you know least about which observables are worth defending — so the discipline trades wasted pre-emptive effort against later lock-in, with no way to be sure which observables warranted it. Diagnostic: Is obscuring this observable now a targeted defence of a behaviour likely to attract dependents, or blanket over-engineering against a risk this particular observable will never realize?

T5: Telemetry as decisive instrument versus its blind spots. The law makes reliance empirical: "which observables have dependents?" is answered by measuring what users actually do, not by reading the spec — a genuine advance over arguing from the contract. But telemetry only sees the surface you instrumented, the users you can observe, and the reliance happening now; it is blind to off-platform consumers, future users, air-gapped or third-party dependents, and reliance on behaviours you never thought to measure. The asymptotic claim says danger lives precisely in the unanticipated observable nobody documented — which is exactly the region telemetry is least able to see. The tension is that the law's empirical instrument is strongest for known, instrumented observables and weakest for the undocumented, unmeasured ones where the law predicts the worst surprises. Diagnostic: Does the telemetry cover the full population and surface that could be depending on this observable, or only the instrumented, currently-visible slice of it?

T6: Autonomy versus reduction (a software-API law or the path-dependence-through-observability compound). "Hyrum's Law" is the canonical, sharpest software instance, with real home-bound cargo — the published/observable/de-facto-contract vocabulary, the asymptotic framing, and the encapsulation/jitter/telemetry toolkit — and within software it transfers intact as mechanism. But its skeleton is a compound of existing parents, path_dependence / lock_in operating through observability under scale-driven dependency formation, and that compound genuinely recurs as co-instances in customary and constitutional law, descriptive linguistics, infrastructure co-option, and biological spandrels. Strip the jargon and the residue — "what users can observe and depend on becomes binding regardless of what was promised" — is already implied by path dependence under observable accumulation, and a neutral parent (observable surface becomes contract) would cover all those substrates together. The tension is between a precise, useful software law and the recognition that its portable core belongs to a broader compound that should not bear the software name. Diagnostic: Resolve toward the path-dependence-through-observability compound when carrying the lesson to law, language, or infrastructure; toward Hyrum's Law when managing a software interface's observable surface in situ.

Structural–Framed Character¶

Hyrum's Law sits at mixed. Its evaluative weight is nil: it is an empirical engineering regularity — with enough users, every observable becomes depended upon — that renders no verdict on whether that is good or bad; the constraint simply obtains. On human_practice_bound it points partway framed: the law is about interfaces, users, and dependence — it needs a designed artifact and a population that builds on it, so it does not run in observer-free nature — yet the co-instances it flags (customary law hardening from practice, descriptive linguistics, infrastructure co-option, biological spandrels) show the underlying compound operating even where no software exists, and in the spandrel case with no designer at all, which pulls back toward structural. Its institutional origin is intermediate: "Hyrum's Law" is a named, coined regularity of software practice, but the compound it names is not a tradition's fiat — it is a genuine dynamical tendency. On vocab_travels it scores low: published/observable/de-facto contract, the observable surface, telemetry, and build-time jitter are API-evolution furniture. On import_vs_recognize it is recognition within software, and — unusually — the underlying compound recurs as genuine co-instances (not mere metaphor) across law, language, infrastructure, and evolution.

The portable structural skeleton is path_dependence/lock_in operating specifically through observability under scale-driven dependency formation — what a population can observe and depend on becomes binding regardless of the nominal contract, with the constraint's growth rate scaling with user count. That compound is what genuinely travels (a candidate observable-surface-becomes-contract parent would cover software, customary law, and infrastructure together), and it is what Hyrum's Law instantiates; the published/observable/de-facto vocabulary and the encapsulation/jitter/telemetry toolkit are the domain accent that stays home. Its character: an evaluatively neutral, artifact-and-user-bound regularity whose portable core is the path-dependence-through-observability compound it specializes to software interfaces.

Structural Core vs. Domain Accent¶

This section settles why Hyrum's Law is a domain-specific abstraction and not a prime — a case sharpened by the fact that its underlying compound recurs across substrates as genuine co-instances, yet the compound is built from parents the catalog already carries, not a fresh commitment the software law owns.

What is skeletal (could lift toward a cross-domain prime). Strip the interface, the users, and the code away and a thin relational structure survives: whatever a large population can observe about a system, over enough time, comes to be depended upon — so the effective constraint on changing the system exceeds its nominal contract, and the cost of changing any observable is set by its accumulated dependents rather than by whether it was ever promised. The portable pieces are abstract: an observable surface, a population that enumerates it, dependency accretion under scale and time, and an effective constraint that outgrows the formal one. This is path_dependence / lock_in operating specifically through observability under scale-driven dependency formation, and it is genuinely substrate-independent — it recurs as co-instances in customary and constitutional law (long practice hardening into binding convention), descriptive linguistics (persistent usage becoming the language regardless of prescriptive rules), infrastructure co-option (structures used beyond design parameters becoming hard to restrict), and biological spandrels (incidental features co-opted into load-bearing roles, with no designer at all). That recurrence is mechanism, not metaphor. But it is the compound Hyrum's Law shares, not what makes "Hyrum's Law" itself distinctive.

What is domain-bound. Almost everything that makes the concept Hyrum's Law in particular is API-evolution furniture, and none of it survives extraction. The published / observable / de-facto-contract trichotomy is software-interface vocabulary. The asymptotic "every observable becomes a contract" framing presupposes a designed interface with a measurable observable surface — error-message text, iteration order, timing, undocumented side effects. The concrete interventions — encapsulation and indirection, build-time jitter, proactively randomized iteration order, dependency telemetry — presuppose an implementation whose observables a provider can perturb. The decisive test: strip that software cargo and the residue — "what a population can observe and depend on becomes binding regardless of what was formally promised" — is already implied by path dependence under observable accumulation; a customary-law convention has no build-time jitter, a biological spandrel has no telemetry. What is left when the contract vocabulary and the encapsulation toolkit are removed is the bare observability-under-scale compound, which is no longer "Hyrum's Law" but its parents. The concept is constituted by the very software-interface substrate the prime bar asks it to shed.

Why this does not clear the prime bar. A prime is a relational structure whose vocabulary travels and whose cross-domain transfer is recognition of the same mechanism, not analogy. Hyrum's Law's transfer is bimodal — but with an unusual second mode, because the underlying compound really does recur beyond software as co-instances rather than mere metaphor. Within software it travels intact as full mechanism — API and protocol design (Kubernetes, Go, Torvalds' "we don't break userspace" down to preserving syscall bugs), library and SDK evolution, compiler and language design, cloud engineering, and open-source dependency chains — because only the kind of observable changes while the enumeration-under-scale mechanism, the telemetry instrument, and the defensive-randomization remedy stay constant. Beyond software the compound transfers as genuine mechanism to law, language, infrastructure, and evolution — but "Hyrum's Law" as named does not, because its published/observable/de-facto vocabulary and its jitter/telemetry toolkit have nothing to attach to there; importing the software law onto customary law renames the dynamic and sheds the toolkit. And when the substrate-independent lesson is needed cross-domain, it is already carried, in more general form, by the parents Hyrum's Law instantiates: path_dependence / lock_in operating through observability under scale (a neutral observable-surface-becomes-contract parent would cover software, customary law, linguistics, and infrastructure together). The cross-domain reach belongs to that compound; "Hyrum's Law," as named, carries software baggage — the contract trichotomy, the asymptotic framing, the encapsulation/jitter/telemetry apparatus — that should stay home. It clears the domain-specific bar comfortably as the canonical, sharpest software instance, but its only substrate-spanning content is a path-dependence compound its parents already carry — with just two genuinely domain-specific additions (the de-facto contract's growth rate scales with user count, and the observable rather than contractual surface is the operand to manage) that specialize the compound rather than generalize past it.

Relationships to Other Abstractions¶

Current abstraction Hyrum's Law Domain-specific

Parents (2) — more general patterns this builds on

Hyrum's Law presupposes Observability Prime

Hyrum's Law presupposes observability because only behaviors exposed to users can be sampled, depended upon, and converted into a de facto contract.
Hyrum's Law is a decomposition of Path Dependence Prime

Hyrum's Law is the software-interface form of path dependence, where accumulated reliance on historically observable behavior constrains later changes regardless of the published contract.

Hierarchy paths (4) — routes to 4 parentless roots

Hyrum's Law → Observability

Show alternative paths (3)

Not to Be Confused With¶

The network effect. The dynamic by which a system's value to each user rises as the user base grows (more participants, more worth). It scales with user count, exactly as Hyrum's Law does, but in the opposite direction of consequence: Hyrum's Law scales constraint — the system becomes harder to change as users grow. Same growth variable, opposite valence. Tell: does adding users make the system more valuable (network effect) or more rigid and expensive to change (Hyrum's Law)? Flagged in What It Is Not.
Postel's law (the robustness principle). "Be conservative in what you send, liberal in what you accept" — a design maxim about the accept side of an interface, i.e. tolerating varied or malformed inputs. Hyrum's Law governs the observe side: how a system's outputs and behaviours become depended upon. They are complementary, not the same. Tell: is the concern what the system ingests and how forgivingly (Postel) or what users can see it do and then pin to (Hyrum)?
Goodhart's Law. "When a measure becomes a target, it ceases to be a good measure" — optimization pressure on a proxy degrades its informativeness. Both concern observability-driven distortion, but the mechanisms differ: Goodhart is a measure becoming a target under optimization, Hyrum is an observable becoming a contract under dependency accretion. Tell: is something being optimized against as a goal (Goodhart) or merely depended upon once visible (Hyrum)? No optimization pressure is required for Hyrum's Law to bite.
The law of leaky abstractions (Spolsky). "All non-trivial abstractions, to some degree, are leaky" — implementation details inevitably show through an interface meant to hide them. This is the supply side of the same phenomenon: leakage is what exposes an observable; Hyrum's Law is what happens next, when a large population builds dependencies on the leaked behaviour and it hardens into a de facto contract. Tell: is the point that the abstraction fails to fully hide its internals (leaky abstractions) or that users come to depend on whatever is visible, leaked or not (Hyrum)? Leaky abstractions explains why the observable surface exceeds the contract; Hyrum explains why that surface becomes binding.
Generic legacy lock-in / switching costs. The broad family of reasons a system becomes hard to change or leave — data-format inertia, retraining costs, contractual entanglement, network effects. Hyrum's Law names one specific channel within this family: observability under scale converting undocumented implementation details into de facto contracts. Tell: is the rigidity coming from any source of inertia (generic lock-in, the genus) or specifically from users having depended on observable behaviours (Hyrum, one channel)? Treating them as synonyms loses the precise enumeration-under-scale mechanism.
The path_dependence-through-observability compound (umbrella). The substrate-neutral structure Hyrum's Law instantiates — what a population can observe and depend on becomes binding regardless of the nominal contract, its constraint growing with user count — which recurs as genuine co-instances in customary law, descriptive linguistics, infrastructure co-option, and biological spandrels. Not a confusable peer but the parent (a candidate observable-surface-becomes-contract prime) that carries the cross-domain content; the published/observable/de-facto vocabulary and the encapsulation/jitter/telemetry toolkit are the software accent it lacks. Tell: when the lesson is needed for law, language, or infrastructure, the work is done by this compound, treated more fully in the sections above, not by "Hyrum's Law," whose name carries a toolkit that has nothing to attach to there.

Neighborhood in Abstraction Space¶

Hyrum's Law sits in a sparse region of the domain-specific corpus (86^th percentile for distinctiveness): few abstractions share its structure, so a faithful description tends to retrieve it precisely.

Family — Unclustered & Miscellaneous (309 abstractions)

Nearest neighbors

Computed from structural-signature embeddings · 2026-07-12