A currency key type treats 100 cents and 1.00 dollars as equal after normalization — what does that require of its hash function?

## When equality is semantic, hashing must be too Many key types define equality field-by-field, and for those, hashing the same fields is straightforward. The trap appears when equality is *semantic*: two different in-memory representations are declared equal because they mean the same thing. A currency amount is the classic case — `100 cents` and `1.00 dollars` are the same money, so the equality check normalizes both to a canonical unit before comparing. Case-insensitive identifiers, file paths with and without a trailing separator, numerically equal values stored at different precisions, and timestamps carried in different zones all have the same shape. The equality-hash contract says equal objects must produce equal hash values. With semantic equality, the *only* way to guarantee that is to compute the hash from the **canonical form** — the normalized value equality actually compares — not from the raw stored fields. Two representations of the same amount share their canonical form by definition; they do not share their raw fields. ## Tracing the failure A billing system keys a map of paid invoices by a currency-amount type. The insert path builds the key from a settlement feed as `(1, "dollar")`; the reconciliation path rebuilds it from a ledger as `(100, "cent")`. Equality normalizes both to 100 total cents and says *equal*. But the hash was written over the raw pair `(amount, unit)`, so the two keys hash differently, land in different buckets, and the reconciliation lookup finds nothing. The invoice is marked unpaid, a reminder goes out, and no exception was ever thrown — the map did exactly what it was told, with inconsistent instructions. ## The subset rule A precise way to hold the whole constraint in your head: - **Hash inputs must be a function of what equality compares.** Reading exactly the canonical fields is the norm. - **A strict subset is legal.** If equality compares normalized amount *and* currency code, a hash over the amount alone still maps equal keys together — it just also maps some unequal keys together, which is an ordinary collision handled by the equality check. Cost: longer bucket chains, never wrong answers. - **A superset — or a different form — is illegal.** Any input that equality ignores (an un-normalized field, a display string, a creation timestamp) can differ between two equal keys, letting them hash apart. That is the contract violation, and it fails silently as missed lookups and phantom duplicates. This is also why the practical advice is to **normalize once, at the boundary**, and store the canonical form: if the object only ever holds 100-cents form, equality and hashing over its fields agree by construction, and the whole class of bug disappears. ## How to catch it The bug hides from example-based tests, which tend to build both sides of an assertion the same way. The reliable net is a small property test over the key type itself: generate pairs of representations that must compare equal — `(1, dollar)` and `(100, cent)`, mixed-case spellings, path variants — and assert both `a equals b` and `hash(a) == hash(b)`. The second assertion is the one teams forget, and it is precisely the contract. In review, the smell to scan for is any equality check that transforms its operands — lowercasing, trimming, unit conversion, rounding — while the hash function nearby reads bare fields. The two must transform identically or share one canonicalization routine.