Adding a new value to an existing enum field breaks API version translation

A useful frame first: translation works exactly when there's an information-preserving mapping in the direction you need. It's asymmetric — requests go old→new (up), responses new→old (down) — so breaks fall into two buckets, plus some the body-translation layer can't touch.

Response direction (new→old): server has data the old schema can't hold

All share the enum shape — the new value set is larger than the old closed set, so there's no target value.

• New enum variant (your case) or new polymorphic subtype in a tagged union.
• Widened scalar domain — u32→u64, a range that grows, a closed status enum gaining values. Worse than enums: often no sensible catchall, so clamping is silently wrong data.
• Cardinality change — single object becomes a list; down-translating is lossy when len > 1.
• New structured error codes — same break in the error path, easy to overlook.

Request direction (old→new): old client can't supply what the new server needs

The break is when up-translation must synthesize information it doesn't have.

• New required field with no safe default. Jumbo-frames worked because "off" is fine; a field that genuinely needs a value can't be backported — old clients only get default behavior, which may be wrong.
• Removed/narrowed variant or tightened validation. Old client sends a now-invalid value; if there's no survivor to map to, rejection is correct but still a break.
• Field split — one old field maps to several new ones it underdetermines.

Below the translation layer (can't help at all)

• Removed/renamed endpoints — no type mapping saves you; needs a compat shim, not translation. Auth/header/transport changes likewise out of scope.

Mitigations

1. Reserve extension points up front — catchall variants, additional_properties maps, optional/defaulted fields.
2. Policy + CI lint: every new request field must have a server-side default for older versions — the request-side analog of the catchall, mechanically checkable from a schema diff.
3. Client-robustness contract (the real fix): clients and progenitor codegen treat unknown variants / extra fields as non-fatal and degrade. Catchalls are one mechanism for this "must-ignore" semantics.
4. Schema-diff lint in CI flagging every non-translatable change above — added variant without catchall, new required field without default, widened type, removed field/endpoint, cardinality change. RFD 619's "future work" gestures at linting; this is what to lint for.
5. Accept-and-gate — for genuinely incompatible changes, refuse just the affected operation with a "please upgrade" prompt (531 already provides the prompt path) rather than breaking broadly.

Three caveats on the catchall

• Forward-looking only. The server can only emit a catchall if that version's blessed schema already has it, so you must add catchalls everywhere now. It prevents the next #10560; it doesn't fix the v20 console retroactively — clients built before the catchall still break.
• Degradation, not function. cpu_platform: Unknown won't crash but can't render the real platform. "Doesn't error" is the win.
• Request-position catchalls are a hazard, and round-trip fidelity bites. A catchall in a request enum lets clients send garbage the server must reject anyway — you may want split request/response enum types. And for read-modify-write (console GET then PUT), the catchall must preserve the original payload so the server can recover the real variant on the way up; a bare marker breaks editing of any object holding an unknown value. (Moot for server-assigned read-only fields like cpu_platform — worth confirming which enums are actually editable first.)