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 holds that with a sufficient number of users of an interface, it does not matter what the formal contract promises: every observable behaviour will come to be depended upon by somebody, and any change to it — even outside the documented spec — will break someone's code. An interface produces two contracts at once: the published contract of promised behaviours, and the de facto contract of observables users have built dependencies on. Under scale and time the de facto contract approaches the whole observable surface, by enumeration: given enough users, every observable is sampled and depended upon.

Scope of Application¶

Hyrum's Law lives across the subfields of software and computing where an interface accrues many users over time — one substrate, the kind of observable changing but the mechanism constant.

API and protocol design — the canonical case; Torvalds' "we don't break userspace," down to preserving syscall bugs.
Library and SDK evolution — even unpublished helpers acquire dependents.
Compiler and language design — undefined behaviour and quirks hardening into de facto semantics.
Cloud and platform engineering — provisioning timing, error formats, and quotas ossifying into contracts.
Open-source dependency ecosystems — transitive imports amplifying the effect along every chain.

Clarity¶

The law separates the published contract, the observable behaviour, and the de facto contract — three nested sets — so most "that was never part of the API" disputes dissolve once a team locates which layer a dependency lives in. It replaces the belief that contractual status governs change cost with a sharper rule: cost is set by dependent count, making minimising the observable surface a discipline distinct from minimising the contract.

Manages Complexity¶

Interface evolution presents a pile of distinct headaches — legacy lock-in, dragging deprecations, ossified undocumented behaviors. The law compresses that to three nested sets and one cost rule, so the maintainer reads outcomes off two parameters (population size and diversity, observable exposure), and the safe-versus-breaking question reduces to: is this observable inside the de facto contract?

Abstract Reasoning¶

The law supports a predictive-under-scale move (large diverse base implies the de facto contract approaches the full surface), a diagnostic replacing contractual status with dependent count (telemetry as the decisive instrument), and an interventionist move with a sharp inert-versus-effective split (shrinking the contractual surface is inert; shrinking the observable surface via encapsulation and jitter prevents dependencies forming).

Knowledge Transfer¶

Within software Hyrum's Law transfers as mechanism across every software substrate — the nested sets, cost rule, and inert-versus-effective remedy carry intact. Beyond it the underlying compound recurs as co-instances (customary law, linguistic descriptivism, infrastructure co-option, biological spandrels), but that reach belongs to the compound it instantiates — path_dependence through observability under scale-driven dependency formation — not the name. It is distinct from network_effect (value not constraint), the Postel principle (accept not observe side), and adjacent to goodharts_law.

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)

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