Enum and symbol-set evolution

Why is adding an enum value structurally safe and semantically breaking?

An enum (enumeration) is a type with a fixed set of allowed values, such as status ∈ {PICKED_UP, IN_TRANSIT, DELIVERED}.

This is the exception that shows the limits of every earlier mechanism. Adding a value to an enum is compatible by every test a registry applies: same type, same width, every old value still valid. And it is semantically breaking for any consumer that matches exhaustively: a CASE expression with no default branch, a check constraint, an inner join to a lookup table of statuses, a dashboard with hardcoded categories. That is Ravi's change 2.

The reason it escapes every mechanism: the compatibility check operates on the type, but the interface that matters is the domain (the set of valid values). The two are different, and only the type is checked.

Two resolutions exist:

Model the symbol set as data: a reference table (a dimension) with its own lifecycle and its own consumers, instead of a type baked into the schema.
Require every consumer to carry an explicit "unknown / other" branch. This is forward compatibility pushed down one level, from the field to the value. It has the same shape as the rule "readers must ignore unknown fields", which tells you it is the right generalization.

-- Brittle: any new status silently disappears into "Other"
CASE status WHEN 'PICKED_UP' THEN 'Active' WHEN 'DELIVERED' THEN 'Done' ELSE 'Other' END

-- Honest: the unknown branch is a visible, counted category
CASE status WHEN 'PICKED_UP' THEN 'Active' WHEN 'DELIVERED' THEN 'Done'
            ELSE 'UNKNOWN:' || status END

Enums are the case where the type is stable and the domain is the interface. Widen the domain and check the consumers, because no compatibility mode will.

Case, resolvedConstructed case · Ravi at Parcelo

Three harmless changes, three silent breaks

In one month an optional carrier_code crashed last year's mobile app, a new status fell into Other on the warehouse dashboard, price silently changed from cents to dollars, and 30% of delivery_priority was null. Where it started: Compatibility →

Ravi goes back through the month with the new tools.

Mobile app crash on carrier_code. The schema change was a legal "add optional with default". The problem was the app's strict parser, which rejects unknown fields. He ships a fix to the app to ignore unknown fields, and adds this to the team's rules, because forward compatibility lives in the reader's code.
RETURNED_TO_SENDER in "Other". He moves statuses into a reference table that owns the list, and changes the dashboard to show unknown statuses as their own counted category.
Cents to dollars. He sees that no compatibility mode can catch this. The right change was add a new field price_dollars and run expand/contract, with the field name carrying the unit. He also writes down the unit of every money field.
30% nulls. He changes the pipeline to store absence separately from explicit null (a schema_version per record lets Sara tell which rows were written before the field existed). Reader-side defaults are forbidden for historical data. Defaults must be written into the data.