ADR-0001 decision 9: what a redefined declaration takes away from the one it replaces.

breaks/2 is given the declaration a name had and the declaration replacing it, and lists every way the new one narrows the old one - every reason a read that held under the old declaration might not hold under the new. The list is empty when the redefinition takes nothing away, and a name declared on neither side is an :error rather than an empty list: nothing was redefined, so there is nothing to answer.

The six rows

The record's table, kept literally, with the kind each row reports. Five ways a redefinition narrows:

and one way it does not:

The kind is the first element

A break's first element is the row it came from: one atom per breaking row of the table above, and the same atom every time that row is the reason. An embedder wording a warning matches on it and never re-derives from the two declarations why the row broke.

case Compatibility.breaks(old, new) do
  :error -> "nothing was redefined"
  breaks -> Enum.map(breaks, fn
    {:field_removed, name} -> "#{name} is gone"
    {:type_changed, name} -> "#{name} holds a different type"
    {:made_required, name} -> "#{name} must now be there"
    {:required_added, name} -> "#{name} was added and must be there"
    {:made_optional, name} -> "#{name} is no longer promised"
  end)
end

The vocabulary is closed at those five and is the break() type: a case that names all five is exhaustive over every break this module reports, and a sixth kind would be a new row in the record's table, not a new spelling of an old one. The compatible row reports nothing at all, so there is no kind for an optional field added to match on - an empty list is the answer.

The asymmetry is the whole point: this answers may a reader keep reading, not did anything change. A declaration that gains an optional field takes nothing away from a read written against the old one.

Why relaxing a field is a break

A record field that goes required -> optional stops promising its value, and the read check stopped reading an optional record field as covering a required shape field when decision 8 was amended on 2026-09-06. A read that held under the old declaration therefore does not hold under the new, which is the one question this module answers. The row was compatible while step 3 ignored the record side's required?; the amendment of 2026-09-06 to decision 9 moves it.

A one_of is a completion hint, never a break

A field's one_of lists the values a host expects and an editor draws as choices. It is not a constraint: a value control fed from it still admits anything the author types, and nothing in this package reads it as a promise. Adding one, removing one, reordering one, widening one and shrinking one are therefore all compatible, and the key means on a declaration field exactly what it means on an entry (decision 9 as amended 2026-09-06).

What is not a break

A field's item_type is not compared, for the same reason the read check does not descend into it: list satisfies list, and narrowing that is a decision no record has taken. A changed label, a changed note, a changed one_of and a changed kind are not among the record's five either - label and note carry no contract, one_of is a hint, and a name that changes kind is a redefinition this vocabulary has no word for. Nothing here raises: an input that is not a declaration is read as not declared on that side.

Deterministic order

Breaks are ordered by field name, then by reason in the order the record's table lists them, so two runs over the same pair produce the same list and a caller may compare two lists directly. One field can carry several breaks: a field that changed type and was relaxed at once names both.