Two Go services share a gob cache file; which struct changes on one side break the other's decode?

## The setting One service writes a gob cache file; another reads it. They deploy on different schedules, and the file outlives both binaries. Whoever inherits either service needs to know which edits to the shared struct are free, which will page someone, and which will quietly corrupt results. ## What gob matches on gob matches struct fields **by name**, not by position or by declaration order. The transmitted type descriptor names each exported field, and the decoder lines those names up against the fields of the type it was asked to decode into. Fields on the wire that the destination does not declare are discarded. Fields the destination declares that the record does not carry are left exactly as they were. Neither is an error. That one rule generates most of the behaviour below. ## Safe changes **Adding an exported field.** Old readers ignore it. New readers reading old data leave it at the zero value. Both directions work, which makes additive evolution the natural way to change a gob struct. **Removing a field.** Old data still carrying it is discarded on read. New data simply omits it, and an old reader leaves its copy alone. **Reordering fields.** Irrelevant — matching is by name. **Renaming the Go struct type itself** (not its fields). For plain struct values the type name is not what the match turns on. The exception is a type registered for an interface-typed field, where the registered name *is* the identifier; that case is under "loud" below. **Switching a field between `T` and `*T`.** gob does not transmit pointers; it flattens them and sends what they point to, so the wire representation is unchanged by the indirection. ## Loud changes — they fail with an error **Incompatible numeric changes.** gob will move an integer into a differently sized integer variable, and a float into a differently sized float variable, but the categories have to match and the value has to fit. Signed to unsigned, integer to floating point, or an arriving value too large for the receiving width all fail the decode. **Changing a field's kind.** A field that was a string and is now a struct, or a slice that became a map, is a mismatch the decoder reports rather than papers over. **Moving or renaming a type registered for an interface-typed field.** The registered name is what the decoder looks up to allocate the concrete value, and by default that name is derived from the type's import path and name. Change either and old records name a type nothing maps to. Pinning the name explicitly at registration time is what prevents this. Loud failures are the good kind: they surface on the first read, and they surface as an error you can alert on. ## Silent changes — the ones that hurt **Renaming a field.** From gob's point of view this is one field deleted and a different field added. Old records carry `Hits`; the new struct declares `HitCount`. The old value is discarded, the new field is never written, and the decode returns `nil`. Downstream you see a counter that is suddenly always zero, with nothing in the logs. **Removing a field the reader still relies on.** Same shape: the destination field keeps whatever it had — its zero value on a fresh variable — and nothing is reported. The general lesson: `err == nil` from a gob decode is not evidence that the record was understood. It is evidence that nothing structurally impossible was attempted. ## The defence: a canary decode in CI Because the dangerous bucket is silent, the check has to assert values, not errors. The cheap, effective version: 1. Check a small gob file into the repository — a handful of records produced by the version currently deployed, with every field set to a distinctive non-zero value. 2. Add a test that decodes it into today's structs and asserts each field equals the value it was written with. 3. Regenerate the file deliberately, as an explicit commit, whenever the format changes on purpose. A rename or a dropped field fails that test immediately, on the pull request that introduced it, instead of in whatever service reads the cache next week. An incompatible type change fails it too, just more noisily. It costs a few dozen lines and it is the only thing that catches the silent bucket. The complementary check — whether the *old* binary can still read *new* data — needs the old binary, so in practice it is handled by policy rather than by a test: keep changes additive, pin registered names, and if the format genuinely has to change incompatibly, version the cache path so old and new files never meet. ## What to tell the next maintainer The exported field names of that struct, plus any pinned registration names, are the format. They are an interface between two deploy schedules, and they should be edited with the same care as a public API — which, for a file both services read, is exactly what they are.