How do you set a team-wide policy for keeping a GraphQL client cache correct after mutations?

## Why this needs a policy at all Each individual case has a defensible answer, which is exactly the problem: 40 engineers making 40 defensible local calls produce a codebase where nobody can say what a given mutation invalidates. The failure modes at scale are two, and they are opposite. - **"Refetch everything to be safe."** Every write triggers a broad reload. Correct, and the backend absorbs a multiple of the traffic the product actually generates; on a ticketing platform, a checkout flow with five writes can turn into dozens of extra documents at exactly the moment the system is busiest. - **"Never refetch, patch by hand."** Fast and cheap - and the invalidation logic is now scattered across hundreds of call sites, each encoding a list's ordering and filtering. It rots silently: someone adds a status filter to a list argument and eleven patch sites become subtly wrong with no test failing. A policy exists to make the cheap correct thing the path of least resistance, and to make the expensive or brittle thing a deliberate, reviewed exception. ## The three-tier default **Tier 0 - the schema floor.** Every mutation returns the objects it changed, carrying identity plus every field the write can move. This costs nothing extra at runtime and removes an entire class of bug from the client's hands. It is a contract the client platform asks of the schema, and it belongs in schema review, not in a feature ticket. On a wide type - a 37-field `Event` accumulated over four years - "every field the write can move" is a real analysis, and the honest answer is often to return the whole object rather than guess. **Tier 1 - the default for membership.** Creates, deletes and reorders refetch the operations that read the affected list. It is correct by construction: the server re-applies its own ordering and filtering, and the client needs no model of either. It costs round trips and settles after the mutation response, so the UI contract has to define what the user sees in that window - usually the optimistic prediction, or a short pending state. **Tier 2 - the measured exception.** A direct store patch is allowed when a hot path shows the refetch cost, and only for lists whose ordering and filtering the client can reproduce exactly. The patch lives in a small reviewed set of helpers, not at the call site, so there is one place to fix when a list gains an argument. That ordering is deliberate: correctness by default, performance by exception with evidence. ## What the policy needs beyond a default **A mutation-to-affected-operations map.** The hardest part of any refetch rule is knowing what to refetch. Left implicit, it is folklore. Make it an artefact: a declaration next to each mutation naming the list-owning areas it disturbs, colocated with the module that owns those lists so it moves when they do. It will still rot; the mitigation is a test per critical flow that runs the mutation and then asserts the screen's data against a cold read. **Rules on retries and predictions.** Which operations may be retried automatically, where an intent key is generated and persisted, and which writes are allowed an optimistic prediction at all. These decide whether the cache can be corrupted by the transport, and no single feature team should be answering them. **A staleness budget by surface.** Not every screen deserves the same rigour. Seat inventory, money and anything the user is about to act on are strict. A venue description or a marketing banner can be stale until the next natural navigation. Writing the budget down is what stops the strict answer from being applied uniformly and blowing up the traffic bill. **Measurement.** Track requests issued per mutation, the p95 time from write to settled UI, and the fraction of refetched payload bytes that turned out unchanged. That last one is the signal that a broad refetch is being used where a narrower repair belongs. A regression here should be as visible as a latency regression. ## Alternatives worth considering, and their limits If several clients care about the same entities, pushing the canonical object over a subscription after a write converges everyone with no refetch. That is a good fit for genuinely shared, high-churn state such as remaining inventory, and a poor one everywhere else: it adds a long-lived connection, a fan-out problem and an ordering problem to solve a staleness issue that one refetch would have handled. Shortening a store's retention, or evicting aggressively after writes, is superficially attractive and mostly moves the cost: reads that would have been served locally become requests, at a time you do not choose. ## The invariant to defend Whatever the policy, the cache is an accelerator, not a source of truth. Every screen must be correct after a cold load with an empty store, and the invalidation strategy must never be the only thing making it correct. That single rule is what keeps a wrong invalidation decision a performance bug and a brief inconsistency rather than a data-integrity incident - and it is what lets you tune the rest of the policy without fear.