Skip to main content

ridl_diff/
classify.rs

1//! The breaking/compatible classifier.
2//!
3//! [`classify`] turns one structural [`Change`] from the walk into a directional
4//! [`Verdict`]. Direction is judged from the consumer's side (ADR-0008 decision
5//! 14): a change is breaking when it shifts or reuses a wire identity or narrows
6//! a consumer-visible guarantee. Scalar widening is compatible only for a type
7//! reached exclusively through sent values; received and unreached types break.
8//!
9//! The classifier reads the resolved IR of both sides, never source, so every
10//! bound it compares is the bound a backend sees. That is what makes the
11//! `[defaults].timing` rule need no special case: the manifest default is
12//! already resolved into every untimed interaction (ADR-0008 decision 12), so
13//! editing it arrives here as an ordinary [`Category::TimingChanged`] on each
14//! defaulted interaction and classifies by the bound rules below (ridl §9.1).
15//!
16//! Two properties are deliberate:
17//!
18//! - **No implication proving.** Contract clauses are carried as canonical
19//!   source text (ADR-0008 decision 14), so the classifier compares text. Any
20//!   `require` text change is breaking, and any `ensure` text change is
21//!   breaking; it never tries to show that one clause implies another.
22//! - **Unlisted is breaking.** A shape the table does not name is classified
23//!   breaking. A false "breaking" costs a maintainer one review; a false
24//!   "compatible" ships a wire break.
25
26use std::collections::{BTreeMap, BTreeSet};
27
28use ridl_ir::v2;
29
30use crate::{Category, Change, Verdict, frozen};
31
32#[cfg(test)]
33mod classify_tests;
34
35/// Classifies one change against the two snapshots it was drawn from.
36///
37/// `old` and `new` are the matched packages the change belongs to; the change's
38/// path is resolved against them to recover the typed IR the direction is read
39/// from. For a package present on only one side the caller passes that package
40/// as both arguments — those changes classify on their category alone.
41///
42/// A reference to a declaration of another package is not resolved here, and a
43/// type the diff cannot resolve is reported as breaking: an appended struct
44/// field typed from another package classifies breaking.
45/// [`diff_sets_in`](crate::diff_sets_in) resolves such a reference against every
46/// package of the new snapshot and the context packages, such as `ridl.std`.
47///
48/// Scalar reachability reads interactions in `new` and the supplied `scope`
49/// only; `classify` supplies an empty scope. If `new` only sends a widened type
50/// and another, unlisted package receives it, `classify` alone returns
51/// [`Verdict::Compatible`]. Callers that need the fail-closed result pass the
52/// full scope through [`diff_sets_in`](crate::diff_sets_in).
53pub fn classify(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
54    classify_in(change, old, new, &[], &[], &mut Default::default())
55}
56
57/// [`classify`], with `scope` — every package of the new snapshot, and the
58/// context packages such as `ridl.std` — to resolve a reference to another
59/// package's declaration, and `encodings`, the list the comparison is judged
60/// for ([`diff_refs_with`](crate::diff_refs_with)). Appended fields read `scope`
61/// to decide whether their types allow 0; scalar constraints read it to find
62/// every new-side interaction that reaches the type. Encoding-specific
63/// categories read `encodings`. `directions` caches the sent and received uses
64/// of reached declarations for the length of one comparison.
65// A new variant must be given a real arm here, not swept into a
66// catch-all: rustc forces *an* arm, and the arm its `help:` text
67// proposes is `_ =>`, which classifies the new variant silently. The
68// two lints below reject a wildcard over `Category` — the first when
69// it covers several variants, the second when it covers exactly one,
70// which is the case one added variant creates.
71#[deny(
72    clippy::wildcard_enum_match_arm,
73    clippy::match_wildcard_for_single_variants
74)]
75pub(crate) fn classify_in(
76    change: &Change,
77    old: &v2::Package,
78    new: &v2::Package,
79    scope: &[&v2::Package],
80    encodings: &[&str],
81    directions: &mut crate::direction::DirectionCache,
82) -> Verdict {
83    match change.category {
84        // Shifts or reuses a wire identity, or replaces a wire-carrying type.
85        // Every one of these is breaking in either direction.
86        Category::InteractionInserted
87        | Category::InteractionReordered
88        | Category::MemberReordered
89        | Category::InteractionRemoved
90        | Category::ReservedNameRedeclared
91        | Category::KindChanged
92        | Category::PayloadChanged
93        | Category::ReturnChanged
94        | Category::ParamsChanged
95        | Category::WidthChanged
96        | Category::ServiceChanged
97        | Category::DeclRemoved => Verdict::Breaking,
98
99        // An init is part of the published contract (ridl §9.1): consumers read
100        // the pre-publish value. Neither reference states a compatible
101        // direction, so the change is breaking.
102        Category::InitChanged => Verdict::Breaking,
103
104        // Doc comments, labels, and deprecation notes reach no consumer's build.
105        // Visibility is not among them — it has its own category below.
106        //
107        // A tombstone in the retired interaction's own slot is the sanctioned
108        // retirement (ridl §11); the walk only emits `InteractionRetired` when
109        // the slot is preserved.
110        Category::DocOnly | Category::InteractionRetired => Verdict::Compatible,
111
112        // An interface's identity is its `interfaces.lock` number (lock
113        // design §7). A rename that keeps the number moves nothing on the
114        // wire — the routing key is the number — and is visible in source,
115        // which the text report's heading says of it. A number the new side's
116        // lock retires is the sanctioned removal: the entry keeps the number
117        // forever, so it is never allocated again.
118        Category::InterfaceRenamed | Category::InterfaceRetired => Verdict::Compatible,
119
120        // `ridl lock` freezing a provisional number in place keeps the
121        // routing key, so nothing moves on the wire; the catalog hash, which
122        // covers the flag, changes, which the text report's heading says of
123        // it. A number that differs between the two sides is a new routing
124        // key for the same interface.
125        Category::InterfaceFrozen => Verdict::Compatible,
126        Category::InterfaceNumberChanged => Verdict::Breaking,
127
128        // A payload limit is part of the catalog hash, so peers with different
129        // limits do not attach. Raising, lowering, adding and removing one are
130        // all breaking (ADR-0030 decision 13).
131        Category::LimitChanged => Verdict::Breaking,
132
133        // An enum value or enum-set bit takes its identity from its explicit
134        // number (typl §8, §9), so a body that differs only in order moves
135        // nothing on the wire. The catalog hash covers that order when an
136        // interface reaches the enum, which the text report's heading says of
137        // it.
138        Category::EnumReordered => Verdict::Compatible,
139
140        // A reader built from a strict enum or enum set refuses a value it
141        // does not name, under every encoding (ADR-0031 decision 12), so an
142        // append to one is breaking, and so is closing an open declaration.
143        // Opening one only makes readers accept more.
144        Category::StrictEnumAppend | Category::EnumClosed => Verdict::Breaking,
145        Category::EnumOpened => Verdict::Compatible,
146
147        // A service's list is a set of interface references (ADR-0015
148        // decision 19 as amended on 2026-09-15). The routing key does not
149        // contain the service, so an interface joining or leaving the set
150        // moves no wire identity: both directions are compatible. A removal
151        // is still visible in source — the `service.member` addresses of that
152        // interface stop resolving under the service — which is what the text
153        // report's heading says of it.
154        Category::ServiceInterfaceAdded | Category::ServiceInterfaceRemoved => Verdict::Compatible,
155
156        Category::VisibilityChanged => visibility(change, old, new),
157        Category::InteractionAppended => appended(change, old, new),
158        Category::DeclAdded => added(change, old, new, scope),
159        Category::ConstraintChanged => constraint(change, old, new, scope, directions),
160        Category::TimingChanged => timing(change, old, new),
161        Category::RpcBoundChanged => rpc_bound(change, old, new),
162        Category::ContractChanged => contract(change, old, new),
163        // A family or shape is part of the contract a consumer compiled
164        // against; a change moves it in both directions (ADR-0012 decision
165        // 12).
166        Category::InteractionClassChanged => Verdict::Breaking,
167
168        // The encoding rules read compatible appends and inline growth, so
169        // the verdict is the encoding's alone: an inline copy cannot grow
170        // under podbuf, and a wider integer moves every head that holds it.
171        // FlatBuffers and proto3 each have their own scalar-width rule below.
172        // `PodbufStrictEnumAppend` is superseded by `StrictEnumAppend` and is no
173        // longer emitted; it keeps its old verdict for a report that still names
174        // it.
175        Category::PodbufInlineAppend
176        | Category::PodbufRemoteInlineGrowth
177        | Category::PodbufWidthChange
178        | Category::PodbufStrictEnumAppend => {
179            if encodings.contains(&"podbuf") {
180                Verdict::Breaking
181            } else {
182                Verdict::Compatible
183            }
184        }
185        Category::FlatbuffersWidthChange => {
186            if encodings.contains(&"flatbuffers") {
187                Verdict::Breaking
188            } else {
189                Verdict::Compatible
190            }
191        }
192        Category::Proto3WidthChange => {
193            if encodings.contains(&"proto3") {
194                Verdict::Breaking
195            } else {
196                Verdict::Compatible
197            }
198        }
199    }
200}
201
202// ==========================================================================
203// Visibility.
204// ==========================================================================
205
206/// A change to the visibility a declaration is published at.
207///
208/// Visibility rides the surface grammar next to doc comments, but it is not
209/// metadata to a consumer. `internal` maps to the target's package-private
210/// mechanism — Rust `pub(crate)`, a non-exported TypeScript member (ADR-0002
211/// §8) — so narrowing `public` to `internal` deletes the declaration from every
212/// out-of-package consumer's build. That is the plainest form of "narrows a
213/// consumer-visible guarantee" in ADR-0008 decision 14, even though the byte
214/// layout on the wire never moves.
215///
216/// Widening `internal` to `public` only offers more, so it is compatible. Any
217/// direction involving an unset visibility is breaking, following the module's
218/// unlisted-is-breaking rule.
219fn visibility(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
220    let (Some(old_visibility), Some(new_visibility)) = (
221        find_visibility(old, &change.path, |name| find_old_shape(old, new, name)),
222        find_visibility(new, &change.path, |name| find_shape(new, name)),
223    ) else {
224        return Verdict::Breaking;
225    };
226
227    match (
228        v2::Visibility::try_from(old_visibility),
229        v2::Visibility::try_from(new_visibility),
230    ) {
231        (Ok(v2::Visibility::Internal), Ok(v2::Visibility::Public)) => Verdict::Compatible,
232        _ => Verdict::Breaking,
233    }
234}
235
236/// The visibility published at a change's path: an interaction inside an
237/// interface or service shape, or a package-level declaration, interface, or
238/// service. `shape_of` resolves the container name the path carries to this
239/// side's shape — by name on the new side, and on the old side the way the
240/// walk matched it ([`find_old_shape`]), since a renamed interface's path
241/// carries only its new name.
242fn find_visibility<'a>(
243    package: &'a v2::Package,
244    path: &str,
245    shape_of: impl Fn(&str) -> Option<v2::InterfaceShape<'a>>,
246) -> Option<i32> {
247    let mut segments = path.split('/').skip(1);
248    let name = segments.next()?;
249
250    if let Some(member) = segments.next() {
251        return shape_of(name)?
252            .interface
253            .interactions
254            .iter()
255            .find(|decl| decl.name == member)
256            .map(|decl| decl.visibility);
257    }
258    if let Some(decl) = find_decl(package, name) {
259        return Some(decl.visibility);
260    }
261    // `Package::shapes` answers for a named interface and for a service with an
262    // inline shape, and `InterfaceShape::visibility` reads the authoritative
263    // field in each case — the owning service's for an inline shape, whose own
264    // `Interface.visibility` is `VISIBILITY_UNSPECIFIED` by construction.
265    if let Some(shape) = shape_of(name) {
266        return Some(shape.visibility());
267    }
268    // A service naming an interface after `:` carries no shape of its own, so
269    // it is not in `shapes()`; its visibility is still the service's.
270    package
271        .services
272        .iter()
273        .find(|service| service.name == name)
274        .map(|service| service.visibility)
275}
276
277// ==========================================================================
278// Interaction append — the identity-reuse guard.
279// ==========================================================================
280
281/// An interaction (or a freshly minted tombstone) added after every slot that
282/// existed before. Appending is compatible, but only when the slot it takes was
283/// never occupied: an ordinal freed by an untombstoned removal and handed to a
284/// new name **reuses a wire identity**, which ADR-0008 decision 14 lists first
285/// among breaking changes.
286///
287/// The walk labels that case `InteractionAppended` because the new name does sit
288/// after every surviving slot; the reuse is only visible by looking back at what
289/// the old snapshot held at that ordinal, which is why the check lives here and
290/// not in the walk.
291fn appended(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
292    let Some((container, member)) = member_path(change) else {
293        return Verdict::Breaking;
294    };
295    let (Some(old_iface), Some(new_iface)) = (
296        find_old_interface(old, new, container),
297        find_interface(new, container),
298    ) else {
299        return Verdict::Breaking;
300    };
301    let Some(ordinal) = slot_ordinal(new_iface, member) else {
302        return Verdict::Breaking;
303    };
304
305    for (name, old_ordinal) in slots(old_iface) {
306        if old_ordinal == ordinal && name != member {
307            return Verdict::Breaking;
308        }
309    }
310    Verdict::Compatible
311}
312
313// ==========================================================================
314// Additions — package level, and the append-only composite bodies.
315// ==========================================================================
316
317/// A declaration present only in the new snapshot.
318///
319/// A package-level addition — a new decl, interface, or service — is compatible:
320/// nothing that existed moved. A composite member addition is compatible only
321/// when it is a genuine append: typl §7.4 makes struct fields and union arms one
322/// append-only rule ("new fields are added at the end of the struct or union"),
323/// and an enum value appends by taking a number above every live and every
324/// retired one.
325///
326/// An appended struct field must also be readable from an old payload, which
327/// does not carry it ([`absence_reads_as_legal`], driftsys/ridl#598).
328fn added(change: &Change, old: &v2::Package, new: &v2::Package, scope: &[&v2::Package]) -> Verdict {
329    let Some((container, member)) = member_path(change) else {
330        // One or two segments: a whole package, or a package-level decl,
331        // interface, or service.
332        return Verdict::Compatible;
333    };
334    let (Some(old_decl), Some(new_decl)) = (find_decl(old, container), find_decl(new, container))
335    else {
336        return Verdict::Breaking;
337    };
338
339    // The append test is a property of the whole body, and reading the body is
340    // what catches a *surviving* member whose slot moved — which the walk does
341    // not report alongside an addition. The member name is read only for a
342    // struct field, whose type decides whether an old payload stays readable.
343    use v2::decl::Kind;
344    let appended = match (&old_decl.kind, &new_decl.kind) {
345        (Some(Kind::StructDef(old_def)), Some(Kind::StructDef(new_def))) => {
346            appended_slot(
347                &struct_slots(old_def),
348                &struct_reserved(old_def),
349                &struct_slots(new_def),
350            ) && absence_reads_as_legal(new_def, member, new, scope)
351        }
352        (Some(Kind::UnionDef(old_def)), Some(Kind::UnionDef(new_def))) => {
353            // A result union's arms are its transport identity (ADR-0008
354            // decision 4): any arm change flips it.
355            !old_def.is_result
356                && !new_def.is_result
357                && appended_slot(
358                    &union_slots(old_def),
359                    &union_reserved(old_def),
360                    &union_slots(new_def),
361                )
362        }
363        // An append to an enum or enum set is compatible only when the new
364        // declaration is `open`: a reader built from a strict declaration
365        // refuses a value it does not name (ADR-0031 decision 12). The walk
366        // folds a strict append into `StrictEnumAppend` before this runs.
367        (Some(Kind::EnumDef(old_def)), Some(Kind::EnumDef(new_def))) => {
368            new_def.open
369                && appended_slot(
370                    &value_slots(&old_def.values),
371                    &reserved_values(&old_def.reserved),
372                    &value_slots(&new_def.values),
373                )
374        }
375        (Some(Kind::EnumSetDef(old_def)), Some(Kind::EnumSetDef(new_def))) => {
376            new_def.open
377                && appended_slot(
378                    &value_slots(&old_def.bits),
379                    &[],
380                    &value_slots(&new_def.bits),
381                )
382        }
383        // A shape the table does not name classifies breaking.
384        _ => false,
385    };
386
387    if appended {
388        Verdict::Compatible
389    } else {
390        Verdict::Breaking
391    }
392}
393
394/// Whether `new_decl` is `old_decl` with values or flags appended, and it is an
395/// enum or an enum set that is not `open`: the append the generic rule would
396/// accept, were the declaration open, and that is [`Category::StrictEnumAppend`]
397/// instead.
398pub(crate) fn is_strict_enum_append(old_decl: &v2::Decl, new_decl: &v2::Decl) -> bool {
399    use v2::decl::Kind;
400    match (&old_decl.kind, &new_decl.kind) {
401        (Some(Kind::EnumDef(old_def)), Some(Kind::EnumDef(new_def))) => {
402            !new_def.open
403                && appended_slot(
404                    &value_slots(&old_def.values),
405                    &reserved_values(&old_def.reserved),
406                    &value_slots(&new_def.values),
407                )
408        }
409        (Some(Kind::EnumSetDef(old_def)), Some(Kind::EnumSetDef(new_def))) => {
410            !new_def.open
411                && appended_slot(
412                    &value_slots(&old_def.bits),
413                    &[],
414                    &value_slots(&new_def.bits),
415                )
416        }
417        _ => false,
418    }
419}
420
421/// Whether a reader built against `new_set` refuses a payload in which the
422/// field `member` of struct `container`, in package `package`, is absent —
423/// the rule that makes an appended field breaking for its type
424/// (driftsys/ridl#598). `context` holds packages that references resolve
425/// against without being compared, such as `ridl.std`. `false` when
426/// `container` is not a struct of that package. The `ridl check` desk check
427/// reads it to say so in its RIDL-407 message for an append that also sits
428/// beside a moved sibling.
429pub fn absence_refused(
430    new_set: &[v2::Package],
431    context: &[v2::Package],
432    package: &str,
433    container: &str,
434    member: &str,
435) -> bool {
436    let scope: Vec<&v2::Package> = new_set.iter().chain(context).collect();
437    let Some(home) = new_set.iter().find(|candidate| candidate.name == package) else {
438        return false;
439    };
440    match find_decl(home, container).and_then(|decl| decl.kind.as_ref()) {
441        Some(v2::decl::Kind::StructDef(def)) => !absence_reads_as_legal(def, member, home, &scope),
442        _ => false,
443    }
444}
445
446/// Whether a reader built against the new struct body accepts a payload the old
447/// body wrote, in which the appended field `member` is absent
448/// (driftsys/ridl#598).
449///
450/// An optional field reads as absent. A non-optional field reads as the
451/// FlatBuffers default, 0, when its type is a scalar, an enum or an enum set and
452/// 0 is a legal value of that type. That is the condition under which the
453/// FlatBuffers codec of `ridl-backend-rust` reads the absent field instead of
454/// refusing it as a missing required field (driftsys/ridl#472), and the two
455/// share its definition, [`ridl_ir::zero`]. Every other absent non-optional
456/// field is refused: a string, bytes, struct, union, tuple, array or map field
457/// is an offset with no default, and a scalar or enum whose type excludes 0 has
458/// no legal value to read.
459///
460/// A type the classifier cannot resolve reads as refused, following the module's
461/// unlisted-is-breaking rule: a type the diff cannot resolve is reported as
462/// breaking. That includes a reference to another package when `scope` does
463/// not hold it. No snapshot carries `ridl.std`, so it resolves only when the
464/// caller passes it as context, as the `ridl` CLI does.
465fn absence_reads_as_legal(
466    def: &v2::StructDef,
467    member: &str,
468    home: &v2::Package,
469    scope: &[&v2::Package],
470) -> bool {
471    let Some(r#type) = def.members.iter().find_map(|slot| match &slot.member {
472        Some(v2::struct_member::Member::Field(field)) if field.name == member => {
473            field.r#type.as_ref()
474        }
475        _ => None,
476    }) else {
477        return false;
478    };
479    ridl_ir::zero::field_type_holds_zero(r#type, |reference| resolve(home, scope, reference))
480}
481
482/// The declaration a type reference names on the new side, in the IR's
483/// canonical form: a bare `Name` in `home`, and `pkg.Name` in the package of
484/// that name — `home` itself or one of `scope`.
485fn resolve<'a>(
486    home: &'a v2::Package,
487    scope: &[&'a v2::Package],
488    reference: &str,
489) -> Option<&'a v2::Decl> {
490    match reference.rsplit_once('.') {
491        Some((package, name)) => std::iter::once(home)
492            .chain(scope.iter().copied())
493            .find(|candidate| candidate.name == package)
494            .and_then(|candidate| find_decl(candidate, name)),
495        None => find_decl(home, reference),
496    }
497}
498
499/// Whether the new body is the old body with every pre-existing slot untouched
500/// and every addition sitting above the highest slot ever used — live or
501/// retired.
502///
503/// Both halves matter. A member whose slot number moved has had its wire
504/// identity shifted even though its name survived, and the walk's composite
505/// comparison does not report that alongside an addition. A member taking a
506/// number at or below the old high-water mark is an insertion, or a reuse of a
507/// retired number, which typl §7.4 forbids so a wire value never carries a new
508/// meaning.
509fn appended_slot(old: &[(String, i64)], old_retired: &[i64], new: &[(String, i64)]) -> bool {
510    // The first slot of a name, as a linear search would find it.
511    let mut new_slots: BTreeMap<&str, i64> = BTreeMap::new();
512    for (name, slot) in new {
513        new_slots.entry(name.as_str()).or_insert(*slot);
514    }
515    for (name, old_slot) in old {
516        match new_slots.get(name.as_str()) {
517            Some(new_slot) if new_slot == old_slot => {}
518            // A surviving member moved, or vanished alongside the addition.
519            _ => return false,
520        }
521    }
522
523    // The high-water mark of the old body, live and retired slots together,
524    // read once: every new member must be above it (`is_above_high_water`).
525    let mark = old
526        .iter()
527        .map(|(_, slot)| *slot)
528        .chain(old_retired.iter().copied())
529        .max();
530    let old_names: BTreeSet<&str> = old.iter().map(|(name, _)| name.as_str()).collect();
531    for (name, slot) in new {
532        if old_names.contains(name.as_str()) {
533            continue;
534        }
535        if !is_above_high_water(*slot, mark) {
536            return false;
537        }
538    }
539    true
540}
541
542/// Whether `slot` is above every slot in `held`, which is the append rule for
543/// one new member: the member keeps every existing ordinal or value, and it
544/// does not reuse a retired one (typl §7.4).
545///
546/// `held` lists every slot the old body assigns or retires, live and
547/// reserved together. When `held` is empty, any `slot` is above it. `ridl
548/// check --baseline` calls this function, so the desk check and the
549/// classifier apply one rule.
550pub fn is_above_high_water(slot: i64, held: impl IntoIterator<Item = i64>) -> bool {
551    held.into_iter().max().is_none_or(|mark| slot > mark)
552}
553
554// ==========================================================================
555// Constraints — narrowed versus widened.
556// ==========================================================================
557
558/// A scalar constraint change on a named type. Widening is compatible only
559/// when at least one new-side interaction reaches the type and every use is
560/// sent by the consumer. Any received use, or no use, is breaking. Narrowing
561/// remains breaking because it rejects values a consumer may already send.
562///
563/// A composite body changed in place reaches here with no member path and no
564/// rendered values — the walk does not say which member changed inside it — and
565/// classifies breaking.
566fn constraint(
567    change: &Change,
568    old: &v2::Package,
569    new: &v2::Package,
570    scope: &[&v2::Package],
571    directions: &mut crate::direction::DirectionCache,
572) -> Verdict {
573    let mut segments = change.path.split('/').skip(1);
574    let (Some(name), None) = (segments.next(), segments.next()) else {
575        return Verdict::Breaking;
576    };
577    let (Some(old_decl), Some(new_decl)) = (find_decl(old, name), find_decl(new, name)) else {
578        return Verdict::Breaking;
579    };
580
581    use v2::decl::Kind;
582    let (Some(Kind::TypeDef(old_def)), Some(Kind::TypeDef(new_def))) =
583        (&old_decl.kind, &new_decl.kind)
584    else {
585        return Verdict::Breaking;
586    };
587
588    if narrows(old_def.constraint.as_ref(), new_def.constraint.as_ref()) {
589        Verdict::Breaking
590    } else {
591        directions.widening_verdict(new, scope, &format!("{}.{}", new.name, name))
592    }
593}
594
595/// Whether the constraint moved in the narrowing direction on any facet.
596///
597/// Each bound is judged independently and any narrowing decides the whole
598/// change, so a mixed edit — a lowered `min` with a lowered `max` — is breaking
599/// on the half that narrows. A stepped minimum also defines the grid origin,
600/// so a shifted grid is breaking even when the interval widens.
601pub(crate) fn narrows(old: Option<&v2::Constraint>, new: Option<&v2::Constraint>) -> bool {
602    let (Some(old), Some(new)) = (old, new) else {
603        // A constraint appearing where there was none bounds a previously
604        // unbounded value; dropping one entirely only widens.
605        return old.is_none() && new.is_some();
606    };
607
608    // A raised floor or a lowered ceiling rejects values that were legal.
609    if raised(old.min.as_deref(), new.min.as_deref())
610        || lowered(old.max.as_deref(), new.max.as_deref())
611    {
612        return true;
613    }
614    // Length bounds are the same rule over character and byte counts.
615    if raised_u64(old.len_min, new.len_min) || lowered_u64(old.len_max, new.len_max) {
616        return true;
617    }
618    // A step quantizes: added or changed at all it can exclude values that were
619    // legal, and the classifier does not prove divisibility. Removed, it widens.
620    if new.step.is_some() && old.step != new.step {
621        return true;
622    }
623    // A minimum is also the origin of a stepped grid. Widening the interval
624    // only preserves old values when the origin moves by whole steps.
625    if let Some(step) = new.step.as_deref()
626        && old.min != new.min
627        && !same_grid(old.min.as_deref(), new.min.as_deref(), step)
628    {
629        return true;
630    }
631    // A pattern added or rewritten can reject strings that matched before.
632    // Removed, it widens.
633    if (new.pattern.is_some() && old.pattern != new.pattern)
634        || (new.pattern_const.is_some() && old.pattern_const != new.pattern_const)
635    {
636        return true;
637    }
638    false
639}
640
641/// Whether two origins differ by a whole positive step, in exact decimal
642/// arithmetic. An omitted minimum has origin zero (typl §4.3). Unknown
643/// spellings fail closed, as do invalid steps from foreign IR snapshots.
644fn same_grid(old: Option<&str>, new: Option<&str>, step: &str) -> bool {
645    use num_bigint::BigInt;
646
647    let read = |text: &str| -> Option<(BigInt, usize)> {
648        let (negative, digits) = split_sign(text)?;
649        let (whole, fraction) = digits.split_once('.').unwrap_or((&digits, ""));
650        if whole.is_empty() || (digits.contains('.') && fraction.is_empty()) {
651            return None;
652        }
653        let coefficient = BigInt::parse_bytes(format!("{whole}{fraction}").as_bytes(), 10)?;
654        Some((
655            if negative { -coefficient } else { coefficient },
656            fraction.len(),
657        ))
658    };
659    let (Some(old), Some(new), Some(step)) = (
660        read(old.unwrap_or("0")),
661        read(new.unwrap_or("0")),
662        read(step),
663    ) else {
664        return false;
665    };
666    let scale = old.1.max(new.1).max(step.1);
667    let rescale = |(coefficient, places): (BigInt, usize)| -> Option<BigInt> {
668        Some(coefficient * BigInt::from(10).pow(u32::try_from(scale - places).ok()?))
669    };
670    let (Some(old), Some(new), Some(step)) = (rescale(old), rescale(new), rescale(step)) else {
671        return false;
672    };
673    step > BigInt::from(0) && (old - new) % step == BigInt::from(0)
674}
675
676/// Whether a lower bound was added or moved up.
677fn raised(old: Option<&str>, new: Option<&str>) -> bool {
678    match (old, new) {
679        (None, Some(_)) => true,
680        (Some(old), Some(new)) => cmp_decimal(new, old).is_none_or(std::cmp::Ordering::is_gt),
681        _ => false,
682    }
683}
684
685/// Whether an upper bound was added or moved down.
686fn lowered(old: Option<&str>, new: Option<&str>) -> bool {
687    match (old, new) {
688        (None, Some(_)) => true,
689        (Some(old), Some(new)) => cmp_decimal(new, old).is_none_or(std::cmp::Ordering::is_lt),
690        _ => false,
691    }
692}
693
694fn raised_u64(old: Option<u64>, new: Option<u64>) -> bool {
695    match (old, new) {
696        (None, Some(_)) => true,
697        (Some(old), Some(new)) => new > old,
698        _ => false,
699    }
700}
701
702fn lowered_u64(old: Option<u64>, new: Option<u64>) -> bool {
703    match (old, new) {
704        (None, Some(_)) => true,
705        (Some(old), Some(new)) => new < old,
706        _ => false,
707    }
708}
709
710/// Orders two canonical decimal strings exactly, without going through a float
711/// (the IR carries exact decimals for precisely this reason, ADR-0007 decision
712/// 9). Returns `None` when either side is not a plain decimal, which callers
713/// read as "cannot prove this relaxes".
714///
715/// The `None` case is not dead. `ridlc` only ever writes canonical decimals, but
716/// [`load_ir_json`](crate::load_ir_json) deserializes a snapshot off disk and a
717/// bound is a plain string there, so a hand-edited or foreign `.ir.json` can
718/// carry an exponent form or any other spelling this function does not read.
719fn cmp_decimal(left: &str, right: &str) -> Option<std::cmp::Ordering> {
720    use std::cmp::Ordering;
721
722    let (left_negative, left_digits) = split_sign(left)?;
723    let (right_negative, right_digits) = split_sign(right)?;
724    if left_negative != right_negative {
725        // Zero is signless in canonical form, so a sign disagreement is a real
726        // ordering: the negative side is the smaller one.
727        return Some(if left_negative {
728            Ordering::Less
729        } else {
730            Ordering::Greater
731        });
732    }
733
734    let magnitude = cmp_magnitude(&left_digits, &right_digits)?;
735    Some(if left_negative {
736        magnitude.reverse()
737    } else {
738        magnitude
739    })
740}
741
742/// Splits an optional leading sign from a decimal, rejecting anything that is
743/// not sign-digits-optional-fraction.
744fn split_sign(text: &str) -> Option<(bool, String)> {
745    let (negative, rest) = match text.strip_prefix('-') {
746        Some(rest) => (true, rest),
747        None => (false, text.strip_prefix('+').unwrap_or(text)),
748    };
749    if rest.is_empty() || !rest.chars().all(|c| c.is_ascii_digit() || c == '.') {
750        return None;
751    }
752    if rest.matches('.').count() > 1 {
753        return None;
754    }
755    Some((negative, rest.to_string()))
756}
757
758/// Orders two unsigned decimal magnitudes by integer part then fraction, so
759/// `9` < `10` and `1.5` < `1.50001`.
760fn cmp_magnitude(left: &str, right: &str) -> Option<std::cmp::Ordering> {
761    use std::cmp::Ordering;
762
763    let (left_int, left_frac) = left.split_once('.').unwrap_or((left, ""));
764    let (right_int, right_frac) = right.split_once('.').unwrap_or((right, ""));
765
766    let left_int = left_int.trim_start_matches('0');
767    let right_int = right_int.trim_start_matches('0');
768    let by_length = left_int.len().cmp(&right_int.len());
769    if by_length != Ordering::Equal {
770        return Some(by_length);
771    }
772    let by_int = left_int.cmp(right_int);
773    if by_int != Ordering::Equal {
774        return Some(by_int);
775    }
776
777    // Compare fractions digit by digit, padding the shorter with zeros.
778    let width = left_frac.len().max(right_frac.len());
779    let pad = |frac: &str| format!("{frac:0<width$}");
780    Some(pad(left_frac).cmp(&pad(right_frac)))
781}
782
783// ==========================================================================
784// Timing.
785// ==========================================================================
786
787/// A resolved timing change on a signal or event (ADR-0008 decision 12).
788///
789/// `min` is the rate floor and `max` the staleness bound, so the consumer-facing
790/// guarantee strengthens when `min` rises or `max` falls and weakens when either
791/// moves the other way. A bound added or removed, or the strict-periodic/range
792/// mode flipped, changes what a consumer may assume at all — rmdl clocks key on
793/// strict — and is breaking in both directions.
794fn timing(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
795    let Some((container, member)) = member_path(change) else {
796        return Verdict::Breaking;
797    };
798    let (Some(old_decl), Some(new_decl)) = (
799        find_old_interaction(old, new, container, member),
800        find_interaction(new, container, member),
801    ) else {
802        return Verdict::Breaking;
803    };
804    let (Some(old_timing), Some(new_timing)) =
805        (interaction_timing(old_decl), interaction_timing(new_decl))
806    else {
807        // An interaction kind that carries no timing at all. The walk cannot
808        // produce this: it emits `TimingChanged` only inside its signal and
809        // event arms, so both sides are already a timed kind by the time a
810        // change reaches here. It is still reachable, because [`classify`] is
811        // public and takes any hand-built `Change` — so the arm stays, follows
812        // the module's unlisted-is-breaking rule, and carries a test of its own.
813        // It is deliberately not a `debug_assert!`: a caller passing a category
814        // the walk would not have emitted is asking a question, not committing
815        // a bug, and aborting a debug build over it would be wrong.
816        return Verdict::Breaking;
817    };
818
819    let (Some(old_timing), Some(new_timing)) = (old_timing, new_timing) else {
820        // Timing appearing where there was none, or dropped, is a bound added
821        // or removed.
822        return Verdict::Breaking;
823    };
824
825    if old_timing.mode != new_timing.mode {
826        return Verdict::Breaking;
827    }
828    // A floor lowered, a ceiling raised, or either bound added or removed.
829    if lowered(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
830        || dropped(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
831        || raised(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
832        || dropped(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
833    {
834        return Verdict::Breaking;
835    }
836    // What remains is a floor raised, a ceiling lowered, or only
837    // `default_applied` flipped over identical bounds — a default made explicit.
838    Verdict::Compatible
839}
840
841/// A declared RPC-bound change on a command or query (ADR-0015 decision 8).
842///
843/// The two bounds keep their generic §9 meaning — `min` the rate floor, `max`
844/// the staleness bound — but on an RPC `min` is the **call throttle** and
845/// constrains the consumer, so its direction inverts against [`timing`]'s
846/// convention: raising it withdraws a call rate the caller was entitled to
847/// use (breaking), and lowering it leaves the caller less constrained
848/// (compatible). `max` is the response bound, a provider promise, and keeps
849/// the provider-side rule: raised is a weaker promise (breaking), lowered a
850/// stronger one (compatible). A bound added or removed — the whole annotation
851/// included — is breaking in both directions, exactly as in [`timing`]:
852/// callers size timeouts against a declared bound, so its appearance and its
853/// disappearance both change what a consumer may assume at all.
854///
855/// This is a distinct category rather than a kind-aware branch inside
856/// [`timing`] so that a missed branch fails closed (ADR-0012 decision 9): the
857/// deny lints above turn a missing arm into a compile error rather than a
858/// silently inherited signal rule that calls a raised RPC `min` compatible.
859fn rpc_bound(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
860    let Some((container, member)) = member_path(change) else {
861        return Verdict::Breaking;
862    };
863    let (Some(old_decl), Some(new_decl)) = (
864        find_old_interaction(old, new, container, member),
865        find_interaction(new, container, member),
866    ) else {
867        return Verdict::Breaking;
868    };
869    let (Some(old_timing), Some(new_timing)) = (rpc_timing(old_decl), rpc_timing(new_decl)) else {
870        // An interaction kind that is not an RPC. The walk cannot produce
871        // this — it emits `RpcBoundChanged` only inside its command and query
872        // arms — but [`classify`] is public and takes any hand-built
873        // [`Change`], so the arm stays and follows the module's
874        // unlisted-is-breaking rule (see [`timing`] for why it is not a
875        // `debug_assert!`).
876        return Verdict::Breaking;
877    };
878
879    let (Some(old_timing), Some(new_timing)) = (old_timing, new_timing) else {
880        // The annotation appearing where there was none, or dropped, is a
881        // bound added or removed — breaking in both directions.
882        return Verdict::Breaking;
883    };
884
885    // The mode is always `Range` on an RPC (ADR-0015 decision 7); anything
886    // else in a snapshot is erroneous IR, and a flip is breaking regardless.
887    if old_timing.mode != new_timing.mode {
888        return Verdict::Breaking;
889    }
890    // A throttle raised, a response bound raised, or either bound added or
891    // removed. `raised` covers the added case (`None` → `Some`), `dropped` the
892    // removed one. This is [`timing`]'s predicate with the `min` direction
893    // inverted — `raised` where the signal rule reads `lowered`.
894    if raised(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
895        || dropped(old_timing.min_us.as_deref(), new_timing.min_us.as_deref())
896        || raised(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
897        || dropped(old_timing.max_us.as_deref(), new_timing.max_us.as_deref())
898    {
899        return Verdict::Breaking;
900    }
901    // What remains is a throttle lowered, a response bound lowered, or only
902    // `default_applied` flipped over identical bounds — a default made
903    // explicit (ADR-0015 decision 7), the rule [`timing`] gives a signal. The
904    // caller is less constrained, or the provider promises more, or neither
905    // changed.
906    Verdict::Compatible
907}
908
909/// Whether a bound present before is absent now.
910fn dropped(old: Option<&str>, new: Option<&str>) -> bool {
911    old.is_some() && new.is_none()
912}
913
914/// The resolved timing of a signal or event; `None` for interaction kinds that
915/// carry none, and `Some(None)` for a timed kind with the field unset.
916fn interaction_timing(decl: &v2::Decl) -> Option<Option<&v2::Timing>> {
917    use v2::decl::Kind;
918    match &decl.kind {
919        Some(Kind::SignalDef(def)) => Some(def.timing.as_ref()),
920        Some(Kind::EventDef(def)) => Some(def.timing.as_ref()),
921        _ => None,
922    }
923}
924
925/// The declared timing of a command or query; `None` for other kinds, and
926/// `Some(None)` for an RPC with no bound at all. An RPC bound may come from a
927/// default (ADR-0015 decisions 4 and 7, as amended).
928fn rpc_timing(decl: &v2::Decl) -> Option<Option<&v2::Timing>> {
929    use v2::decl::Kind;
930    match &decl.kind {
931        Some(Kind::CommandDef(def)) => Some(def.timing.as_ref()),
932        Some(Kind::QueryDef(def)) => Some(def.timing.as_ref()),
933        _ => None,
934    }
935}
936
937// ==========================================================================
938// Contracts.
939// ==========================================================================
940
941/// A `require`/`ensure` clause-set change on a command or query.
942///
943/// A `require` is a precondition the caller must meet: adding one, or rewriting
944/// one, rejects callers that were legal. An `ensure` is a postcondition the
945/// caller may rely on: removing one, or rewriting one, withdraws a guarantee.
946/// Clause text is compared verbatim — the classifier never tries to prove that
947/// one clause implies another (ADR-0008 decision 14), so a rewrite reads as an
948/// addition on the `require` side and as a removal on the `ensure` side, and
949/// both are breaking.
950fn contract(change: &Change, old: &v2::Package, new: &v2::Package) -> Verdict {
951    let Some((container, member)) = member_path(change) else {
952        return Verdict::Breaking;
953    };
954    let (Some(old_decl), Some(new_decl)) = (
955        find_old_interaction(old, new, container, member),
956        find_interaction(new, container, member),
957    ) else {
958        return Verdict::Breaking;
959    };
960    let (Some(old_clauses), Some(new_clauses)) = (contracts(old_decl), contracts(new_decl)) else {
961        return Verdict::Breaking;
962    };
963
964    let kind = |want: v2::ContractKind| {
965        move |clause: &&v2::Contract| v2::ContractKind::try_from(clause.kind) == Ok(want)
966    };
967    let sources = |clauses: &[v2::Contract], want: v2::ContractKind| -> Vec<String> {
968        let mut out: Vec<String> = clauses
969            .iter()
970            .filter(kind(want))
971            .map(|clause| clause.source.clone())
972            .collect();
973        out.sort();
974        out
975    };
976
977    let old_require = sources(old_clauses, v2::ContractKind::Require);
978    let new_require = sources(new_clauses, v2::ContractKind::Require);
979    let old_ensure = sources(old_clauses, v2::ContractKind::Ensure);
980    let new_ensure = sources(new_clauses, v2::ContractKind::Ensure);
981
982    if !covers(&old_require, &new_require) || !covers(&new_ensure, &old_ensure) {
983        return Verdict::Breaking;
984    }
985    Verdict::Compatible
986}
987
988/// Whether every clause in `subset` appears in `superset`, counting duplicates.
989fn covers(superset: &[String], subset: &[String]) -> bool {
990    let mut remaining: Vec<&String> = superset.iter().collect();
991    for clause in subset {
992        match remaining.iter().position(|held| *held == clause) {
993            Some(index) => {
994                remaining.swap_remove(index);
995            }
996            None => return false,
997        }
998    }
999    true
1000}
1001
1002/// The contract clauses of a command or query; `None` for kinds that carry none.
1003fn contracts(decl: &v2::Decl) -> Option<&[v2::Contract]> {
1004    use v2::decl::Kind;
1005    match &decl.kind {
1006        Some(Kind::CommandDef(def)) => Some(&def.contracts),
1007        Some(Kind::QueryDef(def)) => Some(&def.contracts),
1008        _ => None,
1009    }
1010}
1011
1012// ==========================================================================
1013// Path resolution and IR lookups.
1014// ==========================================================================
1015
1016/// Splits a `package/container/member` path into its container and member.
1017/// Returns `None` for the shorter package-level paths.
1018fn member_path(change: &Change) -> Option<(&str, &str)> {
1019    let mut segments = change.path.split('/').skip(1);
1020    let container = segments.next()?;
1021    let member = segments.next()?;
1022    if segments.next().is_some() {
1023        return None;
1024    }
1025    Some((container, member))
1026}
1027
1028pub(crate) fn find_decl<'a>(package: &'a v2::Package, name: &str) -> Option<&'a v2::Decl> {
1029    package.decls.iter().find(|decl| decl.name == name)
1030}
1031
1032/// The shape a name refers to — a top-level interface, or the inline shape of
1033/// a service, which the walk descends into under the service's own dotted
1034/// name. `Package::shapes` keys both on exactly that identity, so one lookup
1035/// covers them.
1036fn find_shape<'a>(package: &'a v2::Package, name: &str) -> Option<v2::InterfaceShape<'a>> {
1037    package.shapes().find(|shape| shape.name == name)
1038}
1039
1040/// The old side of the shape a diff path names, found the way the walk
1041/// matched it (lock design §7; plan decision PD-14): by the frozen
1042/// `interfaces.lock` number of the new side's shape when it has one, and by
1043/// name otherwise — the new side has no identity, or does not hold the name
1044/// at all. A renamed interface's member changes therefore classify as any
1045/// other interface's, although their paths carry only the new name.
1046fn find_old_shape<'a>(
1047    old: &'a v2::Package,
1048    new: &v2::Package,
1049    name: &str,
1050) -> Option<v2::InterfaceShape<'a>> {
1051    let by_number = find_shape(new, name)
1052        .filter(|shape| frozen(shape.interface))
1053        .and_then(|shape| {
1054            old.shapes().find(|candidate| {
1055                frozen(candidate.interface) && candidate.interface.number == shape.interface.number
1056            })
1057        });
1058    by_number.or_else(|| find_shape(old, name))
1059}
1060
1061fn find_interface<'a>(package: &'a v2::Package, name: &str) -> Option<&'a v2::Interface> {
1062    find_shape(package, name).map(|shape| shape.interface)
1063}
1064
1065fn find_old_interface<'a>(
1066    old: &'a v2::Package,
1067    new: &v2::Package,
1068    name: &str,
1069) -> Option<&'a v2::Interface> {
1070    find_old_shape(old, new, name).map(|shape| shape.interface)
1071}
1072
1073fn find_interaction<'a>(
1074    package: &'a v2::Package,
1075    container: &str,
1076    member: &str,
1077) -> Option<&'a v2::Decl> {
1078    find_interface(package, container)?
1079        .interactions
1080        .iter()
1081        .find(|decl| decl.name == member)
1082}
1083
1084/// The old side's interaction under a `<package>/<container>/<member>` path,
1085/// with the container resolved by [`find_old_shape`].
1086fn find_old_interaction<'a>(
1087    old: &'a v2::Package,
1088    new: &v2::Package,
1089    container: &str,
1090    member: &str,
1091) -> Option<&'a v2::Decl> {
1092    find_old_interface(old, new, container)?
1093        .interactions
1094        .iter()
1095        .find(|decl| decl.name == member)
1096}
1097
1098/// Every slot of an interface body as (name, ordinal), tombstones included — a
1099/// tombstone occupies its ordinal exactly so the slot is never reused
1100/// (ridl §11).
1101///
1102/// A tombstone whose name is unset still holds its slot. The interface-body
1103/// `reserved` form accepts a bare ordinal or a string literal as well as a
1104/// name, and both lower to `Reserved { name: None }`; dropping those from the
1105/// slot list would leave their ordinals looking free, and a new interaction
1106/// taking one would classify as a clean append. The empty name never equals a
1107/// real interaction name, so the slot is held against every reuse without
1108/// matching anything.
1109fn slots(interface: &v2::Interface) -> Vec<(&str, u32)> {
1110    interface
1111        .interactions
1112        .iter()
1113        .filter_map(|decl| match &decl.kind {
1114            Some(v2::decl::Kind::ReservedSlot(reserved)) => {
1115                Some((reserved.name.as_deref().unwrap_or(""), decl.ordinal))
1116            }
1117            Some(_) => Some((decl.name.as_str(), decl.ordinal)),
1118            None => None,
1119        })
1120        .collect()
1121}
1122
1123fn slot_ordinal(interface: &v2::Interface, member: &str) -> Option<u32> {
1124    slots(interface)
1125        .into_iter()
1126        .find(|(name, _)| *name == member)
1127        .map(|(_, ordinal)| ordinal)
1128}
1129
1130/// Every live struct field with its ordinal — the 1-based place in the body,
1131/// counting tombstones, that typl §7.4 makes the wire identity. Shared with the
1132/// walk, which reports a reorder by these ordinals.
1133pub(crate) fn struct_slots(def: &v2::StructDef) -> Vec<(String, i64)> {
1134    def.members
1135        .iter()
1136        .filter_map(|member| match &member.member {
1137            Some(v2::struct_member::Member::Field(field)) => {
1138                Some((field.name.clone(), i64::from(field.ordinal)))
1139            }
1140            _ => None,
1141        })
1142        .collect()
1143}
1144
1145fn struct_reserved(def: &v2::StructDef) -> Vec<i64> {
1146    def.members
1147        .iter()
1148        .filter_map(|member| match &member.member {
1149            Some(v2::struct_member::Member::Reserved(reserved)) => {
1150                Some(i64::from(reserved.ordinal))
1151            }
1152            _ => None,
1153        })
1154        .collect()
1155}
1156
1157/// Every union arm with its ordinal, on the same rule as [`struct_slots`].
1158pub(crate) fn union_slots(def: &v2::UnionDef) -> Vec<(String, i64)> {
1159    def.arms
1160        .iter()
1161        .map(|arm| (arm.name.clone(), i64::from(arm.ordinal)))
1162        .collect()
1163}
1164
1165fn union_reserved(def: &v2::UnionDef) -> Vec<i64> {
1166    def.reserved
1167        .iter()
1168        .map(|reserved| i64::from(reserved.ordinal))
1169        .collect()
1170}
1171
1172/// Enum values and enum-set bits key on their integer value, not a declaration
1173/// ordinal: the number is the wire identity (typl §7.4, §8).
1174pub(crate) fn value_slots(values: &[v2::EnumValue]) -> Vec<(String, i64)> {
1175    values
1176        .iter()
1177        .map(|value| (value.name.clone(), value.value))
1178        .collect()
1179}
1180
1181fn reserved_values(reserved: &[v2::Reserved]) -> Vec<i64> {
1182    reserved.iter().filter_map(|entry| entry.value).collect()
1183}
1184
1185// ==========================================================================
1186// `--explain` — the rule row for one category.
1187// ==========================================================================
1188
1189/// Parses the snake_case word a report prints back into its category, so
1190/// `ridl diff --explain <category>` takes exactly what the report shows.
1191pub fn category_from_word(word: &str) -> Option<Category> {
1192    crate::CATEGORIES
1193        .into_iter()
1194        .find(|category| crate::category_word(*category) == word)
1195}
1196
1197/// The rule row for a category: the classification table of ADR-0008 decision
1198/// 14 as text. This is the CI-facing documentation of record until the E4 error
1199/// index publishes it.
1200// A new variant must be given a real arm here, not swept into a
1201// catch-all: rustc forces *an* arm, and the arm its `help:` text
1202// proposes is `_ =>`, which classifies the new variant silently. The
1203// two lints below reject a wildcard over `Category` — the first when
1204// it covers several variants, the second when it covers exactly one,
1205// which is the case one added variant creates.
1206#[deny(
1207    clippy::wildcard_enum_match_arm,
1208    clippy::match_wildcard_for_single_variants
1209)]
1210pub fn explain(category: Category) -> &'static str {
1211    match category {
1212        Category::DeclAdded => concat!(
1213            "A declaration, interface, or service present only in the new snapshot.\n",
1214            "  compatible  a new package-level decl, interface, or service; an enum\n",
1215            "              value appended above every live and retired number; a\n",
1216            "              union arm appended at the end of the body (typl 7.4,\n",
1217            "              append-only); a struct field appended at the end of the body\n",
1218            "              when it is optional, or when it is a scalar, enum, or enum set\n",
1219            "              whose type allows the value 0\n",
1220            "  breaking    a member inserted below the highest slot ever used, a member\n",
1221            "              taking a retired number, any addition that moves a surviving\n",
1222            "              member's slot, or any arm of a result union (ADR-0008 d4); a\n",
1223            "              non-optional struct field appended whose type does not allow\n",
1224            "              0 — a string, bytes, struct, union, tuple, array, or map, a\n",
1225            "              scalar whose range or step excludes 0, an enum with no zero\n",
1226            "              member, or a type the diff cannot resolve (ridl diff\n",
1227            "              resolves ridl.std types). A reader of the new version\n",
1228            "              refuses every payload of the old one, which does not carry\n",
1229            "              the field (typl 7.4). Declare the new field optional instead\n",
1230            "              (`field : T?`): an absent optional field reads as absent\n",
1231            "  note        an interface is matched by its interfaces.lock number (lock\n",
1232            "              design 7): a frozen number the old side never held is a new\n",
1233            "              interface, and so is every provisional one — a declaration\n",
1234            "              with no lock entry carries no identity, and a rename keeps its\n",
1235            "              number, so it is never a renamed interface (interface_renamed)"
1236        ),
1237        Category::DeclRemoved => concat!(
1238            "A declaration, interface, or service present only in the old snapshot.\n",
1239            "  breaking    a removed service, interface, decl, enum value, struct\n",
1240            "              field, or union arm withdraws something a consumer compiled\n",
1241            "              against\n",
1242            "  note        an interface is matched by its interfaces.lock number (lock\n",
1243            "              design 7), so an interface here is one whose number is gone\n",
1244            "              from the new side and not retired there — a lock line deleted\n",
1245            "              by hand, or a number changed by hand, which is this row plus\n",
1246            "              decl_added. A number the new side's lock retires is\n",
1247            "              interface_retired instead, and `ridl baseline` refuses to\n",
1248            "              publish the removal of a number it does not find retired\n",
1249            "              (RIDL-412). A removed unit, whose\n",
1250            "              packages are gone from the new set, is also decl_removed.\n",
1251            "              For its allocated interface numbers, `ridl baseline` refuses\n",
1252            "              publication with RIDL-412. To remove the unit on purpose,\n",
1253            "              run ridl baseline CURRENT_SOURCE --reset-history --out BASELINE\n",
1254            "              (see the CLI reference, Baseline publication and recovery)\n",
1255            "  caveat      a composite member retired the sanctioned way — replaced by\n",
1256            "              a `reserved` tombstone in its own slot (typl 7.4) — is also\n",
1257            "              reported breaking today. The body comparison is keyed on\n",
1258            "              member names and does not read the `reserved` list, so it\n",
1259            "              cannot yet tell that retirement from a bare deletion. This\n",
1260            "              errs on the safe side; carried as debt, see the note on\n",
1261            "              `diff_composite`. The interaction-level tombstone IS\n",
1262            "              recognised — see interaction_retired"
1263        ),
1264        Category::InterfaceRenamed => concat!(
1265            "An interface whose interfaces.lock number is the same on both sides and\n",
1266            "whose name changed.\n",
1267            "  compatible  always — the number is the interface's identity and its\n",
1268            "              routing key (lock design 7, rsdl decision D-7), so nothing\n",
1269            "              moves on the wire. Visible in source: a rename changes the\n",
1270            "              generated identity-table names in both wire backends, which\n",
1271            "              is why the text report lists it under the heading\n",
1272            "              \"compatible on the wire, visible in source\". The path\n",
1273            "              carries the new name and the detail old -> new; changes\n",
1274            "              inside the interface are reported under the new name and\n",
1275            "              classified as any other interface's\n",
1276            "  note        a provisional number is no identity: a declaration with no\n",
1277            "              lock entry is never matched, so a rename the lock does not\n",
1278            "              record is decl_removed plus decl_added, breaking, until\n",
1279            "              `ridl lock <pkg> --rename Old=New` records it"
1280        ),
1281        Category::InterfaceRetired => concat!(
1282            "An interface whose number the old snapshot held is gone from the new\n",
1283            "snapshot, whose interfaces.lock retires it.\n",
1284            "  compatible  always — the sanctioned removal of an interface: the entry\n",
1285            "              keeps its number forever with the word `retired`, so the\n",
1286            "              number is never allocated again (lock design 4 and 7, rsdl\n",
1287            "              decision D-7). A number gone with no retired entry is\n",
1288            "              decl_removed, breaking, and `ridl baseline` refuses to publish\n",
1289            "              it (RIDL-412)"
1290        ),
1291        Category::InterfaceFrozen => concat!(
1292            "An interface matched by name whose number is the same on both sides and\n",
1293            "whose provisional flag went from true to false: `ridl lock` froze the\n",
1294            "number in place.\n",
1295            "  compatible  always — the number is the routing key and it did not\n",
1296            "              change, so nothing moves on the wire. The catalog hash\n",
1297            "              changes, because it covers each interface's number and its\n",
1298            "              provisional flag, and a generated face refuses a port whose\n",
1299            "              catalog hash is another one (ADR-0023 decision 8): a peer\n",
1300            "              built before the lock and a peer built after it refuse each\n",
1301            "              other. This is why the text report lists it under the\n",
1302            "              heading \"compatible on the wire, may change the catalog\n",
1303            "              hash\".\n",
1304            "              The detail carries the number before and after, marked\n",
1305            "              (provisional) on the old side\n",
1306            "  note        a baseline never holds a provisional number (`ridl baseline`\n",
1307            "              refuses one, RIDL-411), so this change is seen between two\n",
1308            "              builds, or in a reversed comparison whose old side is a\n",
1309            "              build. A number 0 on either side, from a snapshot written\n",
1310            "              before the lock existed, is not compared"
1311        ),
1312        Category::InterfaceNumberChanged => concat!(
1313            "An interface matched across the two sides whose number differs.\n",
1314            "  breaking    always — the number is the interface's routing key, so a\n",
1315            "              peer built against the old number cannot reach the\n",
1316            "              interface at the new one. Seen between two provisional\n",
1317            "              builds when a sibling interface added before this one in\n",
1318            "              byte order moves its provisional number, and when `ridl\n",
1319            "              lock` freezes a provisional number as another number. The\n",
1320            "              detail carries the old and the new number, each marked\n",
1321            "              (provisional) when it is\n",
1322            "  note        two frozen numbers are matched by number, so they never\n",
1323            "              differ here: a frozen number changed by hand is\n",
1324            "              decl_removed plus decl_added. A number 0 on either side,\n",
1325            "              from a snapshot written before the lock existed, is not\n",
1326            "              compared.\n",
1327            "              Run `ridl lock` to freeze the numbers, so that a later\n",
1328            "              sibling cannot move them"
1329        ),
1330        Category::MemberReordered => concat!(
1331            "A surviving composite member whose slot in the body changed.\n",
1332            "  breaking    always — a struct field or union arm takes its wire\n",
1333            "              identity from its ordinal, its 1-based place in the body\n",
1334            "              counting tombstones (typl 7.4), so a member whose ordinal\n",
1335            "              changed has a new wire identity; the detail carries the old\n",
1336            "              and new ordinal. An enum value or enum-set bit takes its\n",
1337            "              identity from the explicit number it declares (typl 8, 9),\n",
1338            "              so one whose number changed has a new wire identity; the\n",
1339            "              detail carries the old and new value or bit. An enum or\n",
1340            "              enum-set body reordered with no number changed is\n",
1341            "              enum_reordered, compatible, instead\n",
1342            "  note        reported only when both bodies hold the same member names:\n",
1343            "              a reorder in the same edit as an addition or a removal is\n",
1344            "              reported through decl_added or decl_removed alone. A reorder\n",
1345            "              in the same edit as an in-place change to the body is\n",
1346            "              reported with constraint_changed on the container as well.\n",
1347            "              An enum or enum-set body whose only differences are changed\n",
1348            "              numbers, in any order, reports member_reordered alone"
1349        ),
1350        Category::EnumReordered => concat!(
1351            "An enum or enum-set body whose difference is only order: its values or\n",
1352            "bits reordered with no number changed, the enum's reserved list\n",
1353            "reordered with no entry added, removed or changed, or both.\n",
1354            "  compatible  always — a value or bit takes its identity from the\n",
1355            "              explicit number it declares (typl 8, 9), so nothing moves\n",
1356            "              on the wire. The catalog hash covers only the declarations\n",
1357            "              an interface reaches. When an interface reaches the enum or\n",
1358            "              enum set, the order of its values or bits, and of an enum's\n",
1359            "              reserved list, is part of the hash, so the hash changes\n",
1360            "              then, and a generated face refuses a port whose catalog hash\n",
1361            "              is another one (ADR-0023 decision 8). This is why the text\n",
1362            "              report lists it under the heading \"compatible on the wire,\n",
1363            "              may change the catalog hash\". The path is the container's;\n",
1364            "              there is no detail\n",
1365            "  note        a value or bit whose number changed is member_reordered,\n",
1366            "              breaking, not enum_reordered"
1367        ),
1368        Category::InteractionAppended => concat!(
1369            "An interaction added after every slot that existed before.\n",
1370            "  compatible  the slot it takes was never occupied\n",
1371            "  breaking    the slot was freed by an untombstoned removal and is now\n",
1372            "              reused by a new name — a reused wire identity (ADR-0008 d14)"
1373        ),
1374        Category::InteractionInserted => concat!(
1375            "An interaction added before the end of the interface body.\n",
1376            "  breaking    always — every later ordinal shifts, and the ordinal is the\n",
1377            "              transport identity (ridl 11)"
1378        ),
1379        Category::InteractionReordered => concat!(
1380            "A surviving interaction whose relative order in the body changed.\n",
1381            "  breaking    always — a reorder shifts wire identities (ridl 11)"
1382        ),
1383        Category::InteractionRemoved => concat!(
1384            "An interaction removed without a `reserved` tombstone holding its slot.\n",
1385            "  breaking    always — the freed ordinal is reusable, so the wire identity\n",
1386            "              is no longer permanent (ridl 11)"
1387        ),
1388        Category::InteractionRetired => concat!(
1389            "An interaction retired to a `reserved` tombstone in its own ordinal slot.\n",
1390            "  compatible  always — the sanctioned retirement: the slot stays occupied\n",
1391            "              and every later ordinal holds (ridl 11)"
1392        ),
1393        Category::KindChanged => concat!(
1394            "An interaction whose kind changed (signal, event, command, query, fixed).\n",
1395            "  breaking    any direction — the kind selects the transport shape"
1396        ),
1397        Category::PayloadChanged => concat!(
1398            "A signal, event, or fixed payload type changed.\n",
1399            "  breaking    any direction, a stream added or removed included"
1400        ),
1401        Category::ReturnChanged => concat!(
1402            "A query return shape changed.\n",
1403            "  breaking    any direction — an ok-arm change, an error arm added, removed,\n",
1404            "              or retyped, a stream added or removed, or any other change to\n",
1405            "              the synthesized inline `T | E` transport identity (ADR-0008 d4:\n",
1406            "              interface + interaction ordinal + ordered arm types)"
1407        ),
1408        Category::ParamsChanged => concat!(
1409            "A command or query parameter list changed.\n",
1410            "  breaking    any direction — a parameter added, removed, renamed, retyped,\n",
1411            "              or a stream added or removed on one"
1412        ),
1413        Category::TimingChanged => concat!(
1414            "A signal or event resolved timing changed (ADR-0008 d12).\n",
1415            "  compatible  min raised (a higher rate floor) or max lowered (a tighter\n",
1416            "              staleness bound) with the mode unchanged; default_applied\n",
1417            "              flipped over identical resolved bounds — a default made\n",
1418            "              explicit\n",
1419            "  breaking    min lowered, max raised, a bound added where none was, a bound\n",
1420            "              removed, or the strict-periodic/range mode flipped\n",
1421            "  note        editing `[defaults].timing` needs no special rule: diff\n",
1422            "              compares resolved bounds, so it surfaces here on every\n",
1423            "              defaulted interaction (ridl 9.1)"
1424        ),
1425        Category::RpcBoundChanged => concat!(
1426            "A command or query declared RPC bound changed (ADR-0015 d8).\n",
1427            "  compatible  min lowered (the caller may call more often) or max lowered\n",
1428            "              (a stronger provider promise), with the mode unchanged;\n",
1429            "              default_applied flipped over identical resolved bounds — a\n",
1430            "              default made explicit\n",
1431            "  breaking    min raised — on an RPC, min is the call throttle and\n",
1432            "              constrains the caller, so raising it withdraws a call rate\n",
1433            "              the caller was entitled to use; max raised (a weaker provider\n",
1434            "              promise); a bound added or removed, the whole annotation\n",
1435            "              included\n",
1436            "  note        the min direction is the inverse of timing_changed's, which\n",
1437            "              is why this is a category of its own rather than a branch:\n",
1438            "              a missed branch would inherit the signal rule and call a\n",
1439            "              raised RPC min compatible (ADR-0012 d9, fail closed).\n",
1440            "              an RPC bound may come from a default, and diff compares\n",
1441            "              resolved bounds, so editing a default surfaces here on\n",
1442            "              every defaulted command or query (ridl 9.1)"
1443        ),
1444        Category::LimitChanged => concat!(
1445            "The payload limit of the interaction changed; every change of a limit is\n",
1446            "breaking, ADR-0030 decision 13.\n",
1447            "  breaking    a limit raised, lowered, added where none was, or removed"
1448        ),
1449        Category::ContractChanged => concat!(
1450            "A command or query require/ensure clause set changed (ridl 13).\n",
1451            "  compatible  a require removed, or an ensure added\n",
1452            "  breaking    a require added or its text changed, or an ensure removed or\n",
1453            "              its text changed. Clause text is compared verbatim: the\n",
1454            "              classifier does not prove that one clause implies another\n",
1455            "              (ADR-0008 d14)"
1456        ),
1457        Category::InteractionClassChanged => concat!(
1458            "A name-paired interaction's family or operation shape changed\n",
1459            "(ADR-0012 d6).\n",
1460            "  breaking    any change, in either direction: the family selects the\n",
1461            "              obligations a consumer compiled against, and the shape\n",
1462            "              the gesture an intent command is. No source writes a\n",
1463            "              family other than dispatch yet; the walk compares the\n",
1464            "              fields from the start so the diff fails closed (ADR-0012 d9)"
1465        ),
1466        Category::WidthChanged => concat!(
1467            "A derived wire width or scalar backing changed.\n",
1468            "  breaking    any IntWidth or FloatWidth change, uint64 versus int64\n",
1469            "              included — the resolved width is part of the contract\n",
1470            "              (typl 4.2, 5.6)"
1471        ),
1472        Category::ConstraintChanged => concat!(
1473            "A scalar constraint changed, or a composite body changed in place.\n",
1474            "  compatible  widened only on a type reached by at least one interaction\n",
1475            "              and exclusively sent by the consumer (command or query\n",
1476            "              parameters, including streams). Widened means min lowered\n",
1477            "              without shifting a stepped grid, max\n",
1478            "              raised, a length bound loosened,\n",
1479            "              a step removed, a match pattern removed (by literal or by\n",
1480            "              named constant), or the whole constraint dropped so the\n",
1481            "              value is unbounded again\n",
1482            "  breaking    widened on a received value (signal, event, fixed or query\n",
1483            "              reply, both fallible arms and stream elements included),\n",
1484            "              on a type reached in both directions, or on an unreached\n",
1485            "              type. Reachability follows nested types across packages.\n",
1486            "              Narrowed — min raised, max lowered, a length bound\n",
1487            "              tightened, a stepped grid shifted, a step added or changed\n",
1488            "              (divisibility between different steps is never\n",
1489            "              proved), a match pattern added or rewritten (by literal or\n",
1490            "              by named constant), or a constraint appearing where there\n",
1491            "              was none, which bounds a previously unbounded value. A\n",
1492            "              composite body changed in place is breaking: the walk\n",
1493            "              does not say which member changed inside it\n",
1494            "  note        each facet is judged on its own and any one narrowing\n",
1495            "              decides the change, so a mixed edit is breaking on the half\n",
1496            "              that narrows. A widening that flips the resolved wire width\n",
1497            "              is separately reported as width_changed, which is always\n",
1498            "              breaking (typl 5.6). Per-side remote contexts report a changed\n",
1499            "              scalar constraint at each surviving consumer interaction path,\n",
1500            "              once per path and remote declaration, with the same rule.\n",
1501            "              Missing per-side context supplies no comparison."
1502        ),
1503        Category::InitChanged => concat!(
1504            "A declared or resolved init value changed.\n",
1505            "  breaking    any direction — the init is the value a consumer reads before\n",
1506            "              the first publish, so it is part of the contract (ridl 9.1)"
1507        ),
1508        Category::ReservedNameRedeclared => concat!(
1509            "A name retired by a `reserved` tombstone is live again — an interaction\n",
1510            "inside an interface body.\n",
1511            "  breaking    always — a retired identity is never reused (ridl 11,\n",
1512            "              RIDL-401)"
1513        ),
1514        Category::ServiceChanged => concat!(
1515            "A service switched between the named list and an inline shape.\n",
1516            "  breaking    always — extraction rewrites the transport identity of every\n",
1517            "              fallible query in the shape: an inline shape derives it from\n",
1518            "              the service's dotted name, a named interface from its own name\n",
1519            "              (ADR-0008 d4, ADR-0015 d15). A changed list is not this\n",
1520            "              category: it is read as a set by the service_interface_*\n",
1521            "              rows (ADR-0015 d19, as amended 2026-09-15)"
1522        ),
1523        Category::ServiceInterfaceAdded => concat!(
1524            "An interface joined a service's set of interfaces.\n",
1525            "  compatible  always — nothing that existed moved: an interface's number\n",
1526            "              comes from its unit's interfaces.lock, not from its place\n",
1527            "              in the list, and the routing key does not contain the service\n",
1528            "              (ADR-0015 d19, as amended 2026-09-15)"
1529        ),
1530        Category::ServiceInterfaceRemoved => concat!(
1531            "An interface left a service's set of interfaces.\n",
1532            "  compatible  always — on the wire: the routing key does not contain the\n",
1533            "              service, so no identity moves, and a split into two services\n",
1534            "              is a removal plus an addition. Visible in source: the\n",
1535            "              service.member addresses of that interface stop resolving\n",
1536            "              under this service, which is why the text report lists it\n",
1537            "              under the heading \"compatible on the wire, visible in\n",
1538            "              source\". A consumer that loses its only provider is a\n",
1539            "              wiring error for rsdl, not a package diff (ADR-0015 d19, as\n",
1540            "              amended 2026-09-15)"
1541        ),
1542        Category::DocOnly => concat!(
1543            "Only doc comment, labels, or deprecation metadata changed.\n",
1544            "  compatible  always — none of it reaches a consumer's build.\n",
1545            "              Visibility is NOT in this category: see\n",
1546            "              visibility_changed"
1547        ),
1548        Category::VisibilityChanged => concat!(
1549            "The visibility a declaration is published at changed.\n",
1550            "  compatible  internal -> public: the declaration is offered to more\n",
1551            "              consumers than before\n",
1552            "  breaking    public -> internal: `internal` maps to the target's\n",
1553            "              package-private mechanism — Rust `pub(crate)`, a\n",
1554            "              non-exported TypeScript member (ADR-0002 8) — so the\n",
1555            "              declaration disappears from every out-of-package\n",
1556            "              consumer's build. The wire layout does not move, but the\n",
1557            "              consumer-visible guarantee narrows (ADR-0008 d14). Any\n",
1558            "              direction involving an unset visibility is breaking"
1559        ),
1560        Category::PodbufRemoteInlineGrowth => concat!(
1561            "A remote declaration held inline by an old consumer has a larger podbuf size.\n",
1562            "The path belongs to the consumer; the values name the remote declaration\n",
1563            "and its old and new inline sizes. An inline member has no nested producer-size\n",
1564            "boundary, so its growth can move the fields after it even when only a remote\n",
1565            "pin changes and the local consumer declaration is unchanged. Producer-sized\n",
1566            "roots, array elements, map entries and union arms may grow, but their inline\n",
1567            "members may not. An append that fits entirely in the old head's pad bytes\n",
1568            "keeps the head size and draws no line; verify does not check pads.\n",
1569            "Shrinkage, other equal-size layout changes and general dependency semantic\n",
1570            "changes are deferred; this category judges only remote inline growth.\n",
1571            "  breaking    with `--encoding podbuf`\n",
1572            "  compatible  otherwise; listed under the heading \"breaking under podbuf\""
1573        ),
1574        Category::PodbufInlineAppend => concat!(
1575            "A struct field appended, compatible under the generic rule, to a\n",
1576            "struct another head holds inline on the old side — as a struct field,\n",
1577            "a tuple member, or an element of an exact-length array, in a struct,\n",
1578            "in the argument struct a call with several parameters induces, or in\n",
1579            "a tuple reply — when the field does not fit entirely inside the old\n",
1580            "head: the first-fit law places any of its bytes past the old head's\n",
1581            "size, so that the head grows. A field the law places entirely inside\n",
1582            "the old head, in its pad bytes, draws no line, because `verify` does\n",
1583            "not check pads; a field that starts in the pads and ends past the\n",
1584            "old size draws it. When several fields are appended at once, each is\n",
1585            "judged by its own bytes. Only a holder of the old side counts, because\n",
1586            "a holder new on the new side has no published copy;\n",
1587            "the detail names each inline use of the old side. The search mirrors\n",
1588            "the heads the encoder lays out, a declaration and a named induced\n",
1589            "tuple: a struct that is a root of its own (a single named parameter, a\n",
1590            "named reply, a signal, event or fixed payload), that is used only\n",
1591            "behind a descriptor (the element of a bounded array, the key or value\n",
1592            "of a map entry, a union arm), or only inside an exact-length array\n",
1593            "that is itself a root (a fixed payload `[S; 2..2]`, which has no head)\n",
1594            "is not reported: the root or the stride gives the producer's size, and\n",
1595            "the fields past it read as 0. A tuple inside such a root is a head,\n",
1596            "and a struct inside that tuple is a use.\n",
1597            "  breaking    with `--encoding podbuf`: the inline copy cannot grow\n",
1598            "              without moving the fields after it\n",
1599            "  compatible  otherwise; listed under the heading \"breaking under\n",
1600            "              podbuf\", so that a workspace that builds podbuf sees it"
1601        ),
1602        Category::PodbufWidthChange => concat!(
1603            "An enum value, an enum-set flag or a union arm appended, compatible\n",
1604            "under the generic rule, after which the podbuf integer of the enum or\n",
1605            "the enum set or the tag of the union is a different integer, by width\n",
1606            "or by signedness. podbuf lays an enum out as the narrowest integer\n",
1607            "that holds every declared value, signed when a value is negative\n",
1608            "(ADR-0031 decision 5), an enum set as its width, the narrowest\n",
1609            "unsigned integer that holds its highest bit, and a union's tag as the\n",
1610            "narrowest unsigned integer that holds the largest arm ordinal: a value\n",
1611            "above 255, a flag at bit 8 or an arm past ordinal 255 widens a `u8` to\n",
1612            "a `u16`, a value above 65535 or a flag at bit 16 a `u16` to a `u32`,\n",
1613            "and a flag at bit 32 widens a `u32` to a `u64`.\n",
1614            "A negative value appended to an enum that has values is below its\n",
1615            "highest value, an insert, which the generic rule reports as a breaking\n",
1616            "`decl_added` line and not as a width line; the integer turns signed\n",
1617            "only when an enum with no value gains values (`-1` gives an `i8`,\n",
1618            "`-1` and `200` an `i16`). The line is reported once per declaration\n",
1619            "and carries the old and the new integer. An append that keeps the\n",
1620            "integer draws no such line.\n",
1621            "  breaking    with `--encoding podbuf`: every head that holds the enum,\n",
1622            "              the enum set or the union lays out a different integer,\n",
1623            "              and an older reader misreads the value\n",
1624            "  compatible  otherwise; listed under the\n",
1625            "              heading \"breaking under podbuf\", so that a workspace\n",
1626            "              that builds podbuf sees it. An enum-set flag that widens\n",
1627            "              the integer also widens the enum set's FlatBuffers\n",
1628            "              scalar, which `flatbuffers_width_change` reports, and a\n",
1629            "              flag at bit 32 also widens the proto3 field, which\n",
1630            "              `proto3_width_change` reports"
1631        ),
1632        Category::PodbufStrictEnumAppend => concat!(
1633            "Superseded by `strict_enum_append`, which is breaking for every\n",
1634            "encoding. `ridl diff` no longer reports this category; the word stays\n",
1635            "so that a report or a script that names it still reads.\n",
1636            "  breaking    with `--encoding podbuf`\n",
1637            "  compatible  otherwise"
1638        ),
1639        Category::StrictEnumAppend => concat!(
1640            "An enum value or an enum-set flag appended to an enum or an enum set\n",
1641            "that is not declared `open`. A reader built from the old declaration\n",
1642            "refuses a value or a flag it does not name: the `verify` of podbuf\n",
1643            "does, and so does the codec of every encoding that checks the\n",
1644            "declaration, so the append is breaking whatever encodings the\n",
1645            "comparison is judged for. To let readers accept values a later\n",
1646            "version adds, declare an open enum or an open enum set (the `open`\n",
1647            "keyword) before the first release that readers depend on: an append\n",
1648            "to an open enum or an open enum set is compatible. For a compared\n",
1649            "declaration, the line is reported once at `<package>/<decl>`, with\n",
1650            "the appended names. With per-side remote contexts, a surviving old\n",
1651            "consumer use reports the line at its consumer path, once per path\n",
1652            "and remote declaration, with `<remote declaration>: <names>` values\n",
1653            "before and after (ADR-0031 decision 13). A side without remote\n",
1654            "context draws no remote strict-append line.\n",
1655            "  breaking    always, for every encoding\n",
1656            "  note        for a compared declaration, a value or flag that is\n",
1657            "              not an append (an insert below the highest number, or a\n",
1658            "              reused number) is decl_added, breaking, instead"
1659        ),
1660        Category::EnumOpened => concat!(
1661            "An enum or an enum set that gained the `open` keyword. A reader built\n",
1662            "from the old declaration already refuses nothing that the new one\n",
1663            "names, and a reader built from the new declaration accepts any\n",
1664            "integer, so no producer or reader of either side is refused by the\n",
1665            "other. The path is the declaration's; there is no detail.\n",
1666            "  compatible  always"
1667        ),
1668        Category::EnumClosed => concat!(
1669            "An enum or an enum set that lost the `open` keyword. A reader built\n",
1670            "from the new declaration refuses a value that a producer of the old\n",
1671            "declaration may still send, because the old declaration accepted any\n",
1672            "integer. The path is the declaration's; there is no detail.\n",
1673            "  breaking    always"
1674        ),
1675        Category::FlatbuffersWidthChange => concat!(
1676            "An enum-set flag appended, compatible under the\n",
1677            "generic rule, after which the FlatBuffers integer of the\n",
1678            "enum set is a different integer. FlatBuffers stores an enum set as the\n",
1679            "unsigned scalar of its width, the narrowest that holds its highest\n",
1680            "bit: a flag at bit 8 widens a `u8` (`ubyte`) to a `u16` (`ushort`),\n",
1681            "a flag at bit 16 a `u16` to a `u32` (`uint`), and a flag at bit 32 a\n",
1682            "`u32` to a `u64` (`ulong`). Every enum is stored as fixed `int` whatever\n",
1683            "its values, so an appended enum value keeps the integer; a union's\n",
1684            "type field is always `ubyte`. The line is reported once per\n",
1685            "declaration and carries the old and the new integer. An append that\n",
1686            "keeps the integer draws no such line.\n",
1687            "Only per-side context entry points report a remote declaration reached\n",
1688            "by a surviving old consumer use once per consumer path and remote\n",
1689            "declaration, at the consumer path with `<remote declaration>: <integer>`\n",
1690            "values; a side without remote context draws no such line.\n",
1691            "  breaking    with `--encoding flatbuffers`: every table field and\n",
1692            "              vector element of the type changes its scalar, so a\n",
1693            "              reader of the new schema rejects or misreads an old\n",
1694            "              buffer and a reader of the old schema drops the flag\n",
1695            "  compatible  otherwise; listed under the heading \"breaking under\n",
1696            "              flatbuffers\", so that a workspace that builds\n",
1697            "              FlatBuffers sees it"
1698        ),
1699        Category::Proto3WidthChange => concat!(
1700            "An enum-set flag appended, compatible under the generic rule, after\n",
1701            "which the proto3 scalar of the enum set is a different scalar. proto3\n",
1702            "has no 8-bit or 16-bit integer, so an enum set of width `u8`, `u16`\n",
1703            "or `u32` is a `uint32` field and one of width `u64` is a `uint64`\n",
1704            "field: a flag at bit 32 above a highest bit of 31 or below widens\n",
1705            "`uint32` to `uint64`, and a flag at bit 8 or 16 keeps `uint32`. Every\n",
1706            "enum is a proto3 `enum`, an `int32`, and the proto3 backend refuses a\n",
1707            "value outside `int32`, so an appended enum value never changes it.\n",
1708            "The line is reported once per declaration and carries the old and the\n",
1709            "new scalar. An append that keeps the scalar draws no such line.\n",
1710            "Only per-side context entry points report a remote declaration reached\n",
1711            "by a surviving old consumer use once per consumer path and remote\n",
1712            "declaration, at the consumer path with `<remote declaration>: <integer>`\n",
1713            "values; a side without remote context draws no such line.\n",
1714            "  breaking    with `--encoding proto3`: a reader of the old schema\n",
1715            "              refuses the value (the generated Rust codec) or truncates\n",
1716            "              it to 32 bits and drops the flag\n",
1717            "  compatible  otherwise; listed under the heading \"breaking under\n",
1718            "              proto3\", so that a workspace that builds proto3 sees it"
1719        ),
1720    }
1721}