In a shared contract repository, how can generated client stubs drift from the contract version they claim to implement?

## Drift is a broken function Think of stub generation as a function: `stubs = generate(contract@version, generator@version)`. A stub artefact is trustworthy exactly when it is the output of that function for the inputs it claims. **Drift is any way that equation stops holding** while the artefact keeps its label. Framing it this way is more useful in an interview than listing incidents, because every incident is one of the inputs going unpinned. ## Where the equation breaks 1. **The contract input is not pinned.** Someone generates from a working copy with an uncommitted edit, or from a branch, and publishes under the release version. The artefact is real code, built from a contract that exists nowhere. 2. **The generator input is not pinned.** The same contract, compiled by two generator versions, can emit different accessors, different naming for an edge case, and different handling of an unknown value. Two consumers then behave differently while both claim the same contract version. 3. **The output is edited.** Generated code checked into a repository invites a small hand fix — a nullability tweak, a convenience accessor — and from then on regeneration would revert it, so nobody regenerates. 4. **The stamp lies.** The artefact carries a version label applied by the release job rather than derived from the inputs, so a rebuild for an unrelated reason republishes different bytes under the same label. 5. **The consumer is pinned to a version upstream has moved past.** Not strictly drift in the artefact, but the same operational symptom: a service implementing a contract nobody can reproduce. ## Detection and prevention - Make generated code a **build output**, never a source file. What cannot be edited cannot be hand-edited. - If it must be checked in — and there are real reasons, such as consumers without the toolchain — then **regenerate and diff in continuous integration** and fail on any difference. This is the single highest-value control. - **Pin the generator version in the contract repository** and treat its upgrade as a release of its own: regenerate everything, review the diff, republish. - **Stamp provenance into the artefact**: contract version, contract content digest, generator version. A consumer can then answer "which contract does my service actually implement?" from the artefact alone. - **Compare digests at the boundary** where it matters: a producer that advertises the contract digest it serves, and a consumer that logs the digest it was generated from, turn a silent mismatch into a startup warning. ## What a drifted stub looks like in production The symptom is rarely a crash. A stub built from a contract that had one extra field will simply never populate it. A stub built by an older generator may not know about a newly declared enumeration member and map it to the unknown case. The reports that arrive are "this value is always empty for one client" or "one consumer classifies these records differently" — per-consumer inconsistency with no error rate to chase. That is why provenance stamping pays for itself: it converts a data-quality investigation into a version comparison. ## The organisational half A contract repository has a release discipline whether or not anyone writes it down. Making it explicit is short: - a contract change lands with a version bump, and the tag is the only thing generation reads; - the publish job is the only thing allowed to publish stubs, from a clean checkout of that tag; - generator upgrades are separate releases with their own diff review; - every published artefact carries its two input versions; - consumers depend on published artefact versions, never on a build from a colleague's machine. None of that is exotic, and an interviewer asking this question is usually checking whether you have seen the failure that these rules exist to prevent — a consumer running code that no contract in the repository can reproduce.