What goes wrong when a federated entity's @key is not actually unique?

## The promise nobody verifies When a subgraph writes `type Account @key(fields: "accountNumber")`, it is making a factual claim about data: *this value identifies exactly one account*. Composition checks a great deal — that the field exists, that it is resolvable here, that it takes no arguments, that the merged graph is satisfiable — but it cannot check that claim, because it never sees a single row. Neither can the router. Uniqueness is enforced, if at all, by the service that owns the data, and only if someone put a constraint there on purpose. So the failure mode of a weak key is not a build error. It is a graph that composes, deploys, and is wrong for a subset of requests. ## What a collision actually does Consider an 11-service bank statements graph in which six subgraphs reference `Account`. Account numbers are unique **within a sort code**, not globally: two branches can both hold `40286611`. The accounts subgraph keys on `accountNumber` alone. Now trace a request. A document asks for an account and its statements. The router fetches from the accounts subgraph, carries the identity forward, and asks the statements subgraph to resolve an account from `accountNumber: "40286611"`. That service looks up the value and finds two rows. Whatever its lookup does — take the first, take the most recent, take whichever the index returned — it returns one of them. The response is a single, well-formed `Account`: the display name from one branch's customer and the statement lines from another's. There is no error. The envelope has no `errors` entry, nothing is null, and every field is the right type. The graph confidently returns a coherent lie. ## Why caching turns it from a bug into an incident It gets worse where the identity is used as a cache key. Caching entity lookups by their identity is a widespread implementation technique — an entity-level cache in the router, a response cache in front of a subgraph — and it is not something the composition specification defines, so its behaviour is entirely a property of whatever you deployed. Every one of those layers takes the same thing on faith: distinct identities mean distinct objects. When two accounts share an identity, they share a cache entry. The first request to arrive populates it; the second gets the first one's data. Now the wrong-row problem is not merely intermittent, it is *sticky*, and it crosses a customer boundary: one viewer sees another viewer's statement row. That is a confidentiality incident with an audit trail, not a data-quality ticket. ## Why it is hard to diagnose Every signal points away from the schema. * The rate is tiny and non-obvious — the share of accounts whose number collides, so perhaps one request in a few thousand. * It correlates with cache warmth and traffic mix, not with a query shape, so replaying the same document usually returns the right data. * It disappears when caching is turned off, which reads as a caching defect and sends the investigation to the wrong team. * Nothing logs an error, because from every service's point of view every request succeeded. The question that cracks it is not "what is wrong with the cache", it is **"what is the uniqueness scope of every key in this graph?"** For each entity, ask what the declared key is unique *within* — globally, per tenant, per region, per branch — and compare that to what the graph assumed. A key that is unique per tenant in a multi-tenant graph is the same bug wearing different clothes, and it is common, because a natural key almost always has a scope the schema author forgot to mention. ## Fixing it without a coordinated deploy Widening or replacing a key looks like a breaking change across every referencing subgraph, and if done as one edit it is. Alternative keys make it survivable, because `@key` is repeatable: 1. Add the correct key alongside the wrong one on the owning subgraph: `@key(fields: "accountNumber") @key(fields: "sortCode accountNumber")`. The graph now accepts either identity, and every existing reference keeps working. 2. Move referencing subgraphs one at a time onto the new key, deploying independently. 3. When nothing references the old key any more, remove it and the incident class goes with it. Step 1 is the important one: it converts an all-at-once schema break into a migration each of the six referencing teams can schedule for itself. ## The prevention that actually holds The durable fix lives in the owning service, not in the schema: a real uniqueness constraint on the columns behind the key, so a colliding row fails to be written rather than failing to be distinguished. Two habits go with it — prefer a surrogate identifier over a natural one whenever the natural value's uniqueness scope is anything narrower than the whole graph, and treat every `@key` in review as a claim someone must be able to point at a constraint for.