After a config reload, a stored key starts hashing to a new value — why does its map entry become unfindable even though no key field changed?

## The consistency clause The well-known half of the equality-hash contract says equal keys must hash equal. The quieter half says a key's hash must be **consistent**: the same key must produce the same hash value for as long as any table holds it. A hash table records nothing but "this entry lives in the bucket its key hashed to at insert time." Every later operation re-derives that location by hashing the key again. If the second derivation disagrees with the first, the table's only piece of navigation is wrong — the entry is physically present and logically unreachable. ## How a hash drifts without the key changing The famous version of this failure is mutating a key's own fields after insert — a story of its own. The subtler version, the one in this support ticket, involves **no change to the key at all**: the hash function consumed inputs beyond the key's fields. Concretely: a service interns lookup keys for catalog labels and, to make matching "smart", its hash and equality normalize text using rules loaded from a reloadable configuration file — locale folding tables, alias maps, strip-lists. At insert time the rules map the key to one canonical string, which hashes to bucket 40. An operator hot-reloads the config; the folding rules change slightly; the same key now canonicalizes differently and hashes to bucket 12. Every entry inserted before the reload is stranded: present in the table, invisible to lookups. Anything non-local can smuggle itself into a hash this way: configuration, environment variables, locale settings, a lazily computed field, wall-clock-derived state. The rule that prevents the whole class: **a hash may read only the key's own stable value — nothing that can change while the key is stored.** ## The diagnostic signature This bug has a fingerprint worth memorizing, because it separates it from a plain missing entry: - **Iteration finds it; lookup does not.** Walking the table's buckets visits every entry regardless of hash, so a full scan or a size count shows the "missing" data. A keyed lookup, which trusts the hash, misses. - Counts disagree with membership: the table reports n entries while n keyed lookups succeed for fewer. When a report says "the entry is there when we dump the map but a get returns nothing," the hash-at-lookup differs from the hash-at-insert — either the key mutated, or, as here, the hash function's other inputs moved. ## What randomized hashing does and does not break Production hash maps deliberately randomize their hashing per process — typically a keyed function such as SipHash with a seed drawn at startup — to stop adversaries from precomputing colliding keys and degrading the table to O(n). Python randomizes string hashes per process, and Ruby does likewise; several other runtimes vary iteration order run-to-run for the same reason. This is **contract-legal**: the seed is fixed for the process, so any key hashes identically for as long as any table in that process holds it. Consistency is scoped to the table's lifetime, not to eternity. The corollary is the discipline it imposes: hash values are ephemeral, process-local numbers. Never persist them to disk, send them across the network, or compare them across runs — the next process will derive different ones for the same keys. Systems that need a durable digest of a key must compute one with an explicitly stable, versioned function, separate from the table's hash. ## Recovering and preventing Once entries are stranded, the table cannot heal in place — it does not know which buckets hold misplaced entries. The recovery is a rebuild: iterate everything (iteration still works), re-insert into a fresh table under the corrected, stable hash. Prevention is a design rule plus a test: hash and equality read only the key's immutable value; and a soak test that inserts, flips every reloadable input, and asserts lookups still hit.