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