Leaky Abstraction
An abstraction whose underlying implementation details become visible or consequential, requiring users to understand what it was meant to hide.
All non-trivial abstractions leak — Spolsky's law — and the useful question is not whether but where, and whether the leak is acknowledged.
Familiar examples: an ORM that hides SQL until a query plan matters, at which point you must understand both the ORM and the SQL it generates; a network abstraction that makes a remote call look local until it is slow or fails; a distributed cache that behaves like a dictionary until a partition or an eviction changes the semantics.
The practical consequences for design:
Do not build an abstraction that promises to hide something it cannot. Making remote calls look local is the classic case, and it produces systems whose failure modes surprise everyone who uses them.
Provide an escape hatch. An ORM that permits raw SQL, a client that exposes the underlying connection. Abstractions without escape hatches get abandoned wholesale the first time they do not fit.
Expose the leak deliberately where it is consequential — an interface that shows latency, failure and partial success is more honest than one that hides them and surprises later.
The related judgement: premature abstraction costs more than duplication. An abstraction built from one example encodes that example's accidents, and the second use case breaks it.