pub enum Category {
Show 40 variants
DeclAdded,
DeclRemoved,
InterfaceRenamed,
InterfaceRetired,
InterfaceFrozen,
InterfaceNumberChanged,
MemberReordered,
EnumReordered,
InteractionAppended,
InteractionInserted,
InteractionReordered,
InteractionRemoved,
InteractionRetired,
KindChanged,
PayloadChanged,
ReturnChanged,
ParamsChanged,
TimingChanged,
RpcBoundChanged,
LimitChanged,
ContractChanged,
InteractionClassChanged,
WidthChanged,
ConstraintChanged,
InitChanged,
ReservedNameRedeclared,
ServiceChanged,
ServiceInterfaceAdded,
ServiceInterfaceRemoved,
DocOnly,
VisibilityChanged,
PodbufInlineAppend,
PodbufRemoteInlineGrowth,
PodbufWidthChange,
PodbufStrictEnumAppend,
StrictEnumAppend,
EnumOpened,
EnumClosed,
FlatbuffersWidthChange,
Proto3WidthChange,
}Expand description
The kind of a single difference. The walk emits the structural categories; the classifier maps them to directional verdicts.
Variants§
DeclAdded
A package-level declaration, interface, or service present only in the new snapshot.
DeclRemoved
A package-level declaration, interface, or service present only in the
old snapshot. An interface is matched by its interfaces.lock
number (lock design §7), so an interface here is one whose number
is gone from the new snapshot and not retired there.
InterfaceRenamed
An interface whose interfaces.lock number is the same on both
sides and whose name changed (lock design §7). The number is the
interface’s identity and its routing key, so nothing moves on the
wire; a rename is visible in source — it changes the generated
identity-table names in both wire backends — so the text report
lists it under the heading (heading). The path carries the new
name; the detail carries the old and the new name.
InterfaceRetired
An interface whose number the old snapshot held and the new
snapshot’s retired entries list (lock design §7): the sanctioned
removal of an interface, recorded by ridl lock --retire.
InterfaceFrozen
An interface matched by name across a provisional old side whose
number is the same on both sides and whose provisional flag went
from true to false: the number ridl lock froze in place. Nothing
moves on the wire, but the catalog hash covers the number and the
flag, so the hash changes and the text report lists it under the
heading “compatible on the wire, may change the catalog hash”
(heading). A number 0 on
either side, from a snapshot written before the lock existed, is
not compared. The path carries the name; the detail carries the
old and the new number, each marked when it is provisional.
InterfaceNumberChanged
A matched interface whose number differs between the two sides, whatever the two flags: a provisional number moved by a sibling added before it, or frozen as another number. The number is the routing key, so the change is breaking. A number 0 on either side, from a snapshot written before the lock existed, is not compared. The detail carries the old and the new number, each marked when it is provisional.
MemberReordered
A surviving composite member whose slot in the body changed — a
struct field, enum value, enum-set bit or union arm — reported only
when both bodies hold the same member names. For a struct field or
union arm the slot is the ordinal, which is wire identity (typl
§7.4), and the detail carries the old and new ordinal. An enum value
or enum-set bit takes its identity from the explicit number it
declares instead (typl §8, §9), so its slot is that number: the
category reports a member whose number changed, with the old and
new value or bit in the detail. When every difference between the
two bodies is a changed number, the container’s
Category::ConstraintChanged is not reported beside it. A body
of an enum or an enum set that differs only in order is
Category::EnumReordered instead.
EnumReordered
An enum or enum-set body whose difference is only order: its live
values or bits reordered with no number changed, the enum’s
reserved list reordered with no entry added, removed or changed,
or both. A value or bit takes its identity from the explicit number
it declares (typl §8, §9), so nothing moves on the wire. The catalog
hash covers only the declarations an interface reaches; when an
interface reaches the enum or enum set, the order of its values or
bits, and of an enum’s reserved list, is part of the hash, so the
hash changes then. The text report lists it under the heading that
Category::InterfaceFrozen shares (heading). The path is the
container’s; there is no detail.
InteractionAppended
A new interaction added at the end of an interface (no earlier interaction shifted).
InteractionInserted
A new interaction added before the end — an earlier interaction now sits after it (ridl §11: insert shifts ordinals, a wire break).
InteractionReordered
A surviving interaction whose relative order within the interface changed (ridl §11: reorder shifts ordinals, a wire break).
InteractionRemoved
An interaction removed without leaving a reserved tombstone.
InteractionRetired
An interaction removed and replaced by a reserved tombstone in the
same slot (ridl §11).
KindChanged
A surviving interaction whose kind changed (signal ↔ event, etc.).
PayloadChanged
A signal/event/fixed payload type changed.
ReturnChanged
A query return type changed.
ParamsChanged
A command/query parameter list changed.
TimingChanged
A signal/event resolved timing changed.
RpcBoundChanged
A command/query declared RPC bound changed (ADR-0015 decision 8).
Separate from Category::TimingChanged because the direction of
min inverts: on an RPC it constrains the caller, not the
provider, so the signal/event rule must not be inherited silently.
LimitChanged
The payload limit declared for an interaction changed, was added or was removed (ADR-0030 decision 13). Any change is breaking: the limit is part of the catalog hash, so peers with different limits do not attach.
ContractChanged
A command/query require/ensure clause set changed.
InteractionClassChanged
A name-paired interaction’s family or operation shape changed (ADR-0012 decision 6).
WidthChanged
A derived wire width or scalar backing changed.
ConstraintChanged
A scalar constraint (range, step, length, pattern) changed, or a composite member changed in place.
InitChanged
A resolved or declared init value changed.
ReservedNameRedeclared
A name that was a reserved tombstone is live again — an
interaction inside an interface body.
ServiceChanged
A service switched between the named list and an inline shape.
Narrowed to the form switch by ADR-0015 decision 19: a changed
list is read as a set by the two ServiceInterface* categories
below.
ServiceInterfaceAdded
An interface in a service’s set that the old snapshot’s set did not hold (ADR-0015 decision 19 as amended on 2026-09-15: a service’s list is a set of interface references).
ServiceInterfaceRemoved
An interface the old snapshot’s set held that the new one does not.
Compatible on the wire — the routing key does not contain the
service — and visible in source, so the text report lists it under
that heading (heading).
DocOnly
Only doc comment, labels, or deprecation metadata changed.
VisibilityChanged
The visibility a declaration is published at changed. Separate from
Category::DocOnly because internal removes the declaration from
every out-of-package consumer (ADR-0002 §8), so the change has a
direction.
PodbufInlineAppend
A struct field appended, compatible under the generic rule, to a
struct another head of the old side holds inline, when the field
does not fit entirely inside the old head: the layout law places
any of its bytes past the old head’s size (ADR-0031 decision 10,
the inline-append rule;
ridl diff --explain podbuf_inline_append states it in full).
Breaking when the comparison is judged for the podbuf encoding,
compatible otherwise, listed under the heading “breaking under
podbuf” (heading). The path is the appended field’s; the
detail names each inline use of the old side, a struct field as
<package>/<struct>/<field> and an interaction’s request, reply
or fixed payload as <package>/<interface>/<interaction>.
PodbufRemoteInlineGrowth
A remote declaration held inline by an old consumer has a larger podbuf size.
PodbufWidthChange
An enum value, an enum-set flag or a union arm appended, compatible
under the generic rule, after which the podbuf integer of the enum
or the enum set or the tag of the union is a different integer, by
width or by signedness (ADR-0031 decision 10, the width rule;
ridl diff --explain podbuf_width_change states it in full).
Breaking when podbuf is among the encodings the comparison is
judged for, compatible otherwise. Reported once per declaration,
at <package>/<decl>, with the old and the new integer.
PodbufStrictEnumAppend
Superseded by Category::StrictEnumAppend, which is breaking for
every encoding. The variant stays so that a report or a consumer
that names the category still compiles; ridl diff no longer
reports it.
StrictEnumAppend
An enum value or an enum-set flag appended to an enum or an enum
set that is not open (ADR-0031 decision 12). A reader built from
the old declaration refuses a value or a flag it does not name, in
the verify of podbuf and in the codec of every other encoding
that checks the declaration, so the append is breaking for every
encoding. Reported once per declaration, at <package>/<decl>,
with the appended names in the detail. The same append to an
open declaration is compatible.
EnumOpened
An enum or an enum set that gained the open keyword: every
reader of the old declaration already accepts the values it
named, so the change is compatible. Reported at
<package>/<decl>.
EnumClosed
An enum or an enum set that lost the open keyword: a reader of
the new declaration refuses a value that a producer of the old one
may still send, so the change is breaking. Reported at
<package>/<decl>.
FlatbuffersWidthChange
An enum value or an enum-set flag appended, compatible under the
generic rule, after which the FlatBuffers integer of the enum or
the enum set is a different integer (ADR-0019 decision 10;
ridl diff --explain flatbuffers_width_change states it in full).
Breaking when flatbuffers is among the encodings the comparison
is judged for, compatible otherwise. Reported once per declaration,
at <package>/<decl>, with the old and the new integer.
With per-side contexts, a remote declaration reached by a surviving
old consumer use is reported once per consumer path and remote
declaration, at the consumer path, with
<remote declaration>: <integer> values. A side without remote
context draws no remote width line; shared-context entry points
do not report remote widths.
Proto3WidthChange
An enum-set flag appended, compatible under the generic rule,
after which the proto3 scalar of the enum set is a different
scalar (ADR-0017 decision 9;
ridl diff --explain proto3_width_change states it in full).
Breaking when proto3 is among the encodings the comparison is
judged for, compatible otherwise. Reported once per declaration,
at <package>/<decl>, with the old and the new proto3 scalar.
With per-side contexts, a remote declaration reached by a surviving
old consumer use is reported once per consumer path and remote
declaration, at the consumer path, with
<remote declaration>: <integer> values. A side without remote
context draws no remote width line; shared-context entry points
do not report remote widths.