structs.rs

use super::*;

#[derive(Clone, Debug)]
pub enum EnumVariantData {
    Inlined(RustRecord),
    RustType(RustType),
}

// rep is Optional - None means we just serialize raw, ie for type choices
#[derive(Clone)]
pub struct EnumVariant {
    pub name: VariantIdent,
    /// Whether `name` was derived from `data` rather than explicitly requested with `@name`.
    /// Deferred generic inline choices rewrite a parser-only placeholder in `data` to a concrete
    /// enum owner, and only a derived variant label may follow that rewrite.
    pub derived_name: bool,
    pub data: EnumVariantData,
    pub serialize_as_embedded_group: bool,
    pub doc: Option<String>,
    /// For a map-representation group choice arm that collapsed a single keyed entry
    /// (`{ a: uint // ... }` → `A(u64)`), this holds the fixed member key (`a`). The value
    /// still lives in `data`; the key is written before it on serialization and read+verified
    /// before it on deserialization. `None` for array reps, type choices, and keyless entries.
    pub key: Option<FixedValue>,
}

impl std::fmt::Debug for EnumVariant {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // `derived_name` is parser/materialization bookkeeping rather than a semantic IR field.
        // Keeping it out of the debug projection preserves the IR snapshot contract, which records
        // emitted-shape semantics rather than the path that settled a variant's spelling.
        f.debug_struct("EnumVariant")
            .field("name", &self.name)
            .field("data", &self.data)
            .field(
                "serialize_as_embedded_group",
                &self.serialize_as_embedded_group,
            )
            .field("doc", &self.doc)
            .field("key", &self.key)
            .finish()
    }
}

impl EnumVariant {
    pub fn new(
        name: VariantIdent,
        rust_type: RustType,
        serialize_as_embedded_group: bool,
        doc: Option<String>,
    ) -> Self {
        Self {
            name,
            derived_name: false,
            data: EnumVariantData::RustType(rust_type),
            serialize_as_embedded_group,
            doc,
            key: None,
        }
    }

    pub fn new_embedded(
        name: VariantIdent,
        embedded_record: RustRecord,
        doc: Option<String>,
    ) -> Self {
        Self {
            name,
            derived_name: false,
            data: EnumVariantData::Inlined(embedded_record),
            serialize_as_embedded_group: false,
            doc,
            key: None,
        }
    }

    pub fn with_derived_name(mut self) -> Self {
        self.derived_name = true;
        self
    }

    /// Builder for the collapse site: attach the fixed member key of a collapsed map-rep arm.
    pub fn with_key(mut self, key: Option<FixedValue>) -> Self {
        self.key = key;
        self
    }

    /// Gets the next CBOR type after the passed in rep (array/map) tag
    /// Returns None if this is not possible and brute-force deserialization
    /// trying every variant should be used instead
    pub fn cbor_types_inner(
        &self,
        types: &IntermediateTypes,
        outer_rep: Option<Representation>,
    ) -> Option<Vec<CBORType>> {
        // A collapsed map-rep arm dispatches on the type of its fixed member KEY, not its value:
        // spec-valid bytes for `{ a: uint // ... }` start with the key `"a"`, so the first CBOR
        // type after the map tag is the key's. (Array reps / type choices leave `key == None`.)
        if outer_rep == Some(Representation::Map)
            && let Some(key) = &self.key
        {
            return Some(vec![fixed_value_cbor_type(key)]);
        }
        match &self.data {
            EnumVariantData::RustType(ty) => {
                if ty.encodings.is_empty() && outer_rep.is_some() {
                    if let ConceptualRustType::Rust(ident) =
                        ty.conceptual_type.resolve_alias_shallow()
                    {
                        match types.rust_struct(ident).unwrap().variant() {
                            // we can't know this unless there's a way to provide this info
                            RustStructType::Extern => None,
                            RustStructType::Record(record) => {
                                // Reconcile with the serializer's `serialize_as_embedded_group`
                                // split (`generate_enum`): an embedded plain-group arm flattens
                                // the record's fields directly after the outer header, so the arm
                                // discriminant peeks the record's FIRST FIELD. A non-embedded
                                // named/aliased record arm instead serializes NESTED — the outer
                                // header then the record's OWN Array/Map header (or struct-level
                                // tag) — so the discriminant must peek that own wire type, which
                                // `RustType::cbor_types` already derives from `record.rep` and any
                                // struct tag. Hand-mapping `record.rep` here would drop the tag.
                                if self.serialize_as_embedded_group {
                                    Self::record_first_cbor_types(types, record)
                                } else {
                                    Some(ty.cbor_types(types))
                                }
                            }
                            // Conservative, not a gap: `None` = brute-force try-each-variant,
                            // which is always correct. By the same wire-form analysis as the
                            // Record arm above, a NON-embedded group-choice arm could dispatch on
                            // its own rep header (its serialize writes outer header then its own
                            // per-arm header), i.e. `Some(ty.cbor_types(types))` — but no row/cell
                            // pins that shape's dispatch today, so keep brute force until one does
                            // (enumerate the row first, per cddl-matrix/roadmap.toml's
                            // "Intra-alternative variation rows" rule).
                            RustStructType::GroupChoice { .. } => None,
                            _ => Some(ty.cbor_types(types)),
                        }
                    } else {
                        Some(ty.cbor_types(types))
                    }
                } else {
                    Some(ty.cbor_types(types))
                }
            }
            EnumVariantData::Inlined(record) => {
                if outer_rep.is_some() {
                    Self::record_first_cbor_types(types, record)
                } else {
                    Some(match record.rep {
                        Representation::Array => vec![CBORType::Array],
                        Representation::Map => vec![CBORType::Map],
                    })
                }
            }
        }
    }

    /// The set of CBOR types the first data item of a record-representation arm can take, used for
    /// enum dispatch. Arrays are positional: only the first (non-optional-prefix) field matters. A
    /// map presents its entries in any order, so the first item is any KEY — dispatch must union
    /// every field's key type. A non-fixed key (`k => v`) is unknowable → `None` (brute force).
    fn record_first_cbor_types(
        types: &IntermediateTypes,
        record: &RustRecord,
    ) -> Option<Vec<CBORType>> {
        match record.rep {
            Representation::Map => {
                let mut ret = vec![];
                for field in record.fields.iter() {
                    ret.push(fixed_value_cbor_type(field.key.as_ref()?));
                }
                Some(ret)
            }
            Representation::Array => {
                let mut ret = vec![];
                for field in record.fields.iter() {
                    ret.extend(field.rust_type.cbor_types(types));
                    if !field.optional {
                        break;
                    }
                }
                Some(ret)
            }
        }
    }

    /// The Record fields a GROUP choice expands into this variant's `new_<variant>` ctor as
    /// direct parameters (both the rust and the wasm pass), when the variant is a NAMED type
    /// resolving to a Record struct — `None` for every other variant shape (incl. aliases to
    /// records: the emitters match the bare `Rust` ident only, deliberately not
    /// `resolve_alias_shallow`, and an alias arm gets the single-arg ctor instead).
    /// `scope_references` marks exactly these field types so a ctor expanded from a record in
    /// ANOTHER module still imports what its parameters name; the emitters and that import walk
    /// all go through this one helper so the parameter list and the import set can't drift.
    /// Panics on an unresolvable ident (`enum_ident` names the enum for the message) — the
    /// resolution the emitters previously did inline.
    pub fn group_ctor_record_fields<'a>(
        &self,
        types: &'a IntermediateTypes,
        enum_ident: &RustIdent,
    ) -> Option<Vec<&'a RustField>> {
        let EnumVariantData::RustType(ty) = &self.data else {
            return None;
        };
        let ConceptualRustType::Rust(ident) = &ty.conceptual_type else {
            return None;
        };
        let resolved = types.rust_struct(ident).unwrap_or_else(|| {
            // Constant text LEADS so the recombination sweep's panic-class ledger can key on the
            // message (its key-shape floor rejects site-only keys; the idents vary per spec).
            panic!("variant ctor refers to undefined ident: {enum_ident} -> {ident}")
        });
        let RustStructType::Record(record) = resolved.variant() else {
            return None;
        };
        Some(
            record
                .fields
                .iter()
                .filter(|f| !f.optional && !f.rust_type.conceptual_type.is_fixed_value())
                .collect(),
        )
    }

    // Can only be used on RustType variants, panics otherwise.
    // So don't call this when we're embedding the variant types
    pub fn rust_type(&self) -> &RustType {
        match &self.data {
            EnumVariantData::RustType(ty) => ty,
            EnumVariantData::Inlined(_) => {
                panic!("only call rust_type() when you know it can't be inlined")
            }
        }
    }

    pub fn name_as_var(&self) -> String {
        let snake = convert_to_snake_case(&self.name.to_string());
        // we can't use (rust) reserved keywords as param: eg new_u32(u32: u32)
        // TODO: do we need to cover any other (rust) reserved keywords?
        String::from(match snake.as_str() {
            "u8" | "u16" | "u32" | "u64" => "uint",
            "i8" | "i16" | "i32" | "i64" => "int",
            "f32" => "float32",
            "f64" => "float64",
            x => x,
        })
    }

    pub fn can_embed_fields(types: &IntermediateTypes, ty: &ConceptualRustType) -> bool {
        match ty {
            ConceptualRustType::Rust(ident) => {
                if let RustStructType::Record(record) = types.rust_struct(ident).unwrap().variant()
                {
                    // Only ARRAY records can be inlined into an enum variant: the inlined
                    // serializer (`generate_array_struct_serialization`) asserts array rep, and a
                    // map record's keys must still be written/read via the record path. A map arm
                    // with <=1 non-fixed fields therefore stays a named `GroupN` reference handled
                    // by the (key-aware) record path instead of being embedded (which panicked).
                    return record.rep == Representation::Array
                        && record
                            .fields
                            .iter()
                            .filter(|field| !field.rust_type.conceptual_type.is_fixed_value())
                            .count()
                            <= 1;
                }
                false
            }
            ConceptualRustType::Alias(_, ty) => Self::can_embed_fields(types, ty),
            _ => false,
        }
    }
}

/// The CBOR major type a fixed value serializes to — used to dispatch enum variants on their fixed
/// map key. Mirrors `RustType::cbor_types` for `ConceptualRustType::Fixed`.
fn fixed_value_cbor_type(value: &FixedValue) -> CBORType {
    match value {
        FixedValue::Uint(_) => CBORType::UnsignedInteger,
        FixedValue::Nint(_) => CBORType::NegativeInteger,
        FixedValue::Float(_) => CBORType::Special,
        FixedValue::Text(_) => CBORType::Text,
        FixedValue::Bytes(_) => CBORType::Bytes,
        FixedValue::Null => CBORType::Special,
        FixedValue::Undefined => CBORType::Special,
        FixedValue::Bool(_) => CBORType::Special,
    }
}

#[derive(Clone, Debug)]
pub struct RustField {
    pub name: String,
    /// Original group-entry order.  Most emitters deliberately use their own canonical ordering,
    /// but transparent group-body projection must interleave value fields with exact-zero metadata.
    pub source_index: usize,
    /// Invariant held by the record-field construction seam (`parse_record_from_group_choice`):
    /// `rust_type.config.default` is `Some` only when `optional` — a `.default` on a mandatory
    /// member is inert by RFC 8610 §3.8.2 (a default fills an ABSENT value) and is stripped, with
    /// a warning, before the field is built. Every face may therefore read a defaulted field as
    /// an optional one.
    pub rust_type: RustType,
    pub optional: bool,
    // None for array fields, Some for map fields. FixedValue for (de)serialization for map keys
    pub key: Option<FixedValue>,
    // comment DSL metadata applied to this field
    pub rule_metadata: RuleMetadata,
}

impl RustField {
    pub fn new(
        name: String,
        rust_type: RustType,
        optional: bool,
        key: Option<FixedValue>,
        rule_metadata: RuleMetadata,
    ) -> Self {
        Self {
            name,
            source_index: usize::MAX,
            rust_type,
            optional,
            key,
            rule_metadata,
        }
    }

    pub fn with_source_index(mut self, source_index: usize) -> Self {
        self.source_index = source_index;
        self
    }

    /// Whether this member's rust type is a nested `Option<Option<…>>`: an OPTIONAL member
    /// (`? f: …`, which the struct stores behind a presence-`Option`) whose own type is NULLABLE
    /// (`T / null` → `Option<T>`). The single source of truth for that shape — the serde
    /// `double_option` adapter's emission condition, the runtime module's usage gate and the wasm
    /// face's flatten condition are all the same predicate, so they cannot drift.
    ///
    /// A member with a `.default` is NOT stored behind a presence-`Option` (the default fills the
    /// absent case), so it is excluded: its rust type is the nullable's single `Option`.
    pub fn is_double_option(&self) -> bool {
        self.optional
            && self.rust_type.config.default.is_none()
            && matches!(
                self.rust_type.conceptual_type.resolve_alias_shallow(),
                ConceptualRustType::Optional(_)
            )
    }

    pub fn to_embedded_rust_type(&self) -> Cow<'_, RustType> {
        if self.optional {
            Cow::Owned(RustType::new(ConceptualRustType::Optional(Box::new(
                self.rust_type.clone(),
            ))))
        } else {
            Cow::Borrowed(&self.rust_type)
        }
    }
}

#[derive(Clone, Debug, Copy)]
pub enum RustStructCBORLen {
    // always a fixed number of CBOR length
    Fixed(usize),
    // can vary with no min/max
    Dynamic,
    // has optional fields. (mandatory fields) - skips over type choices (including T / nil -> Option<T>)
    OptionalFields(usize),
}

#[derive(Clone, Debug, Default)]
pub struct RustStructConfig {
    pub custom_json: bool,
    pub custom_serialize: Option<String>,
    pub custom_deserialize: Option<String>,
    /// `@custom_encodings` written on the RULE. Carried for exactly one reader:
    /// `IntermediateTypes::finalize`'s refusal of a declaration on a rule that mints a STRUCT. A
    /// struct owns its encoding metadata inside itself (its `encodings` member), so no codec-visible
    /// tuple crosses the boundary for a declaration to describe — honoring it is impossible and
    /// dropping it silently is the class this DSL rejects. The declaration is honored only on a
    /// transparent ALIAS rule (where it rides `AliasInfo::rule_metadata`) or on a FIELD (where it
    /// rides `RustField::rule_metadata`).
    pub custom_encodings: Option<Vec<crate::comment_ast::EncodingKind>>,
    /// `@custom_wire_major` written on the RULE. Carried for exactly one reader:
    /// `IntermediateTypes::finalize`'s refusal of a declaration on a rule that mints a STRUCT. The
    /// declared major is read only through the ALIAS channel (`AliasInfo::rule_metadata`), when the
    /// rule keys an OPEN TABLE's typed row or proves a variable middle ARRAY boundary — a
    /// struct-minting rule has no such channel, so honoring it is impossible and dropping it
    /// silently is the class this DSL rejects.
    pub custom_wire_major: Option<crate::comment_ast::WireMajor>,
    pub doc: Option<String>,
    pub newtype_getter: Option<Option<String>>,
    /// `@duplicates` policy for a collection rule (`[* a]` / `[+ a]` / the tag-258 set idiom / a
    /// table). Carried onto the registered transparent alias's `RustType` at `register_rust_struct`
    /// so every embed site (and generic use-site re-resolution) sees the policy.
    pub duplicates: Option<DuplicatesPolicy>,
    /// A named non-generic SET rule (the tag-258 idiom or single-arm mandatory-258 form) nominalized
    /// into a `Wrapper` struct that OWNS its `{tag, len, elem}` encodings (Phase 2.2). Distinct from
    /// a plain `@newtype` wrapper: the set nominal suppresses the inherent `get()` (it shadows
    /// `OrderedSet::get(index)` through `Deref` — E0061), emits the set ergonomics
    /// (`Deref`/`DerefMut`/`IntoIterator`/`From`/`TryFrom`), and mandates always-on
    /// encodings-ignored comparison derives for parity with `OrderedSet`'s unconditional derives.
    pub set_nominal: bool,
}

impl RustStructConfig {
    /// Whether the rule carries `@duplicates reject`. The struct-config twin of
    /// `RustType::duplicates_reject`.
    pub fn duplicates_reject(&self) -> bool {
        self.duplicates == Some(DuplicatesPolicy::Reject)
    }

    /// Whether the rule carries `@duplicates preserve`.
    pub fn duplicates_preserve(&self) -> bool {
        self.duplicates == Some(DuplicatesPolicy::Preserve)
    }
}

impl From<Option<&RuleMetadata>> for RustStructConfig {
    fn from(rule_metadata: Option<&RuleMetadata>) -> Self {
        match rule_metadata {
            Some(rule_metadata) => Self {
                custom_json: rule_metadata.custom_json,
                custom_serialize: rule_metadata.custom_serialize.clone(),
                custom_deserialize: rule_metadata.custom_deserialize.clone(),
                custom_encodings: rule_metadata.custom_encodings.clone(),
                custom_wire_major: rule_metadata.custom_wire_major,
                doc: rule_metadata.doc.clone(),
                newtype_getter: rule_metadata.newtype.clone(),
                duplicates: rule_metadata.duplicates,
                set_nominal: false,
            },
            None => Self::default(),
        }
    }
}

/// A struct's structural/wire identity: the `Debug` rendering of `(tag, tag_optional, config,
/// variant)`. Hand-written `Debug` omits `RustType::generic_param_binding` and
/// `EnumVariant::derived_name`; neither field bears identity. Compare only; never order or render.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StructuralFingerprint(String);

#[derive(Clone, Debug)]
pub struct RustStruct {
    pub(super) ident: RustIdent,
    pub(super) tag: Option<usize>,
    /// When `tag` is set, whether that tag is OPTIONALLY present on the wire (the transparent
    /// tag-set idiom, `x = #6.N([* a]) / [* a]`) rather than mandatory. Only ever true on an
    /// `Array`/`Table` variant produced by the `parse_type_choices` collapse; drives
    /// `register_rust_struct` to attach `OptionallyTagged` instead of `Tagged` to the registered
    /// alias. `false` everywhere else, so every pre-existing tagged rule stays byte-identical.
    pub(super) tag_optional: bool,
    config: RustStructConfig,
    pub(crate) variant: RustStructType,
}

// Keep the public Table domain/range payloads inline as owned RustTypes. The bounds-role tag
// increases the size gap past Clippy's threshold; retain this representation without adding
// per-table allocations or changing those public field types solely to satisfy that threshold.
#[allow(clippy::large_enum_variant)]
#[derive(Clone, Debug)]
pub enum RustStructType {
    Record(RustRecord),
    Table {
        domain: RustType,
        range: RustType,
        /// occurrence-count bounds (`+` / `n*m`) — a cardinality constraint on the table itself.
        /// [`OccurrenceWindow`] retains authored optional endpoints; use its `raw` method for the legacy tuple.
        /// `None` is the unbounded `*` table, the `+` / `1*` shape `(Some(1), None)` selects
        /// `NonEmptyMap`, and every other window selects `BoundedMap` (`NonEmptyPairMap` /
        /// `BoundedPairMap` under `@duplicates preserve`). Rides the registered alias's `RustType` so
        /// embed sites enforce it, exactly like `Array` bounds.
        bounds: Option<OccurrenceWindow>,
    },
    Array {
        element_type: RustType,
        /// occurrence-count bounds (`+` / `n*m`) — a LENGTH constraint on the array itself.
        /// [`OccurrenceWindow`] retains authored optional endpoints; use its `raw` method for the legacy tuple.
        /// Applied to the registered alias RustType's config so embed sites enforce it; kept off
        /// the element_type so it can't be misread as an element VALUE bound.
        bounds: Option<OccurrenceWindow>,
    },
    TypeChoice {
        variants: Vec<EnumVariant>,
    },
    GroupChoice {
        variants: Vec<EnumVariant>,
        rep: Representation,
    },
    Wrapper {
        wrapped: RustType,
        min_max: Option<IntWindow>,
        /// NaN-safe float window for a float-typed wrapper (`c = 0.5..10.5`, `#6.5(0.5..10.5)`).
        /// Mutually exclusive with `min_max` (a wrapper never carries both). Its presence — like a
        /// `Some` `min_max` — makes the wrapper's `new()`/deserialize fallible.
        float_min_max: Option<FloatWindow>,
    },
    /// This is a no-op in generation but to prevent lookups of things in the prelude
    /// e.g. `int` from not being resolved while still being able to detect it when
    /// referring to a struct that doesn't exist even after generation.
    Extern,
    CStyleEnum {
        variants: Vec<EnumVariant>,
    },
    RawBytesType,
}

impl RustStruct {
    pub fn new_record(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        record: RustRecord,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::Record(record),
        }
    }

    pub fn new_table(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        domain: RustType,
        range: RustType,
        bounds: Option<IntWindow>,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::Table {
                domain,
                range,
                bounds: bounds.map(OccurrenceWindow::from_raw),
            },
        }
    }

    pub fn new_array(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        element_type: RustType,
        bounds: Option<IntWindow>,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::Array {
                element_type,
                bounds: bounds.map(OccurrenceWindow::from_raw),
            },
        }
    }

    /// This will automatically check if it's a c-stlye enum and use that instead if possible
    pub fn new_type_choice(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        variants: Vec<EnumVariant>,
        cli: &Cli,
    ) -> Self {
        // we could potentially push these encoding vars out too but this is extremely low priority
        // unless people want to have tagged c-style enums encoded in different ways
        let cant_store_tag = tag.is_some() && cli.preserve_encodings;
        let not_fixed_or_cant_store_enc_vars_or_outer_len =
            variants.iter().any(|ev: &EnumVariant| {
                ev.serialize_as_embedded_group
                    || (cli.preserve_encodings && !ev.rust_type().encodings.is_empty())
                    || !matches!(
                        ev.rust_type().conceptual_type.resolve_alias_shallow(),
                        ConceptualRustType::Fixed(_)
                    )
            });
        if cant_store_tag
            || not_fixed_or_cant_store_enc_vars_or_outer_len
            || (cli.preserve_encodings && !enum_variants_have_same_encoding_var(&variants))
        {
            Self {
                ident,
                tag,
                tag_optional: false,
                config: RustStructConfig::from(rule_metadata),
                variant: RustStructType::TypeChoice { variants },
            }
        } else {
            Self {
                ident,
                tag,
                tag_optional: false,
                config: RustStructConfig::from(rule_metadata),
                variant: RustStructType::CStyleEnum { variants },
            }
        }
    }

    /// A nominal owner for one fixed value.  Deliberately bypasses `new_type_choice`'s all-fixed
    /// C-style-enum optimization: only `TypeChoice` owns standalone codecs and preserve encoding
    /// metadata, which a named fixed rule (and a fixed/null inner) needs.
    pub fn new_fixed_singleton(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        fixed_type: RustType,
    ) -> Self {
        let fixed = match fixed_type.conceptual_type.resolve_alias_shallow() {
            ConceptualRustType::Fixed(fixed) => fixed,
            other => panic!("fixed singleton must resolve to Fixed, got {other:?}"),
        };
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::TypeChoice {
                variants: vec![EnumVariant::new(
                    VariantIdent::new_custom(format!("Value{}", fixed.singleton_name_fragment())),
                    fixed_type,
                    false,
                    None,
                )],
            },
        }
    }

    pub fn new_group_choice(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        variants: Vec<EnumVariant>,
        rep: Representation,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::GroupChoice { variants, rep },
        }
    }

    pub fn new_wrapper(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        wrapped_type: RustType,
        min_max: Option<IntWindow>,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::Wrapper {
                wrapped: wrapped_type,
                min_max,
                float_min_max: None,
            },
        }
    }

    /// A float-windowed wrapper (`c = 0.5..10.5`, `#6.5(0.5..10.5)`). Parallel to `new_wrapper` but
    /// carries a NaN-safe `FloatWindow` instead of an integer `min_max`.
    pub fn new_wrapper_float(
        ident: RustIdent,
        tag: Option<usize>,
        rule_metadata: Option<&RuleMetadata>,
        wrapped_type: RustType,
        float_min_max: Option<FloatWindow>,
    ) -> Self {
        Self {
            ident,
            tag,
            tag_optional: false,
            config: RustStructConfig::from(rule_metadata),
            variant: RustStructType::Wrapper {
                wrapped: wrapped_type,
                min_max: None,
                float_min_max,
            },
        }
    }

    pub fn new_extern(ident: RustIdent) -> Self {
        Self {
            ident,
            tag: None,
            tag_optional: false,
            config: RustStructConfig::default(),
            variant: RustStructType::Extern,
        }
    }

    pub fn new_raw_bytes(ident: RustIdent) -> Self {
        Self {
            ident,
            tag: None,
            tag_optional: false,
            config: RustStructConfig::default(),
            variant: RustStructType::RawBytesType,
        }
    }

    pub fn ident(&self) -> &RustIdent {
        &self.ident
    }

    pub fn tag(&self) -> Option<usize> {
        self.tag
    }

    /// Mark this struct's tag as OPTIONALLY present on the wire (the transparent tag-set collapse).
    /// See the `tag_optional` field. Consuming builder, like `RustType::as_alias`/`as_bytes`.
    #[allow(clippy::wrong_self_convention)]
    pub fn as_optionally_tagged(mut self) -> Self {
        self.tag_optional = true;
        self
    }

    /// Mark this `Wrapper` struct as a nominalized SET (Phase 2.2). See `RustStructConfig::set_nominal`.
    #[allow(clippy::wrong_self_convention)]
    pub fn as_set_nominal(mut self) -> Self {
        self.config.set_nominal = true;
        self
    }

    pub fn tag_optional(&self) -> bool {
        self.tag_optional
    }

    pub fn config(&self) -> &RustStructConfig {
        &self.config
    }

    /// Attach a rule-level `@doc` this struct's own config does not already carry. Used for the
    /// structs whose config comes from somewhere other than the annotated rule — a generic
    /// INSTANCE's config is the generic DEFINITION's, so the binding rule's own doc has no other
    /// route in. Never overwrites: a config that already has a doc got it from the rule that owns
    /// the struct.
    pub fn set_doc_if_absent(&mut self, doc: &str) {
        if self.config.doc.is_none() {
            self.config.doc = Some(doc.to_owned());
        }
    }

    /// Attach a rule-level `@custom_json` this struct's own config could not carry — the generic
    /// INSTANCE whose config belongs to the generic definition, and the plain GROUP rule whose
    /// metadata is read off a comment slot cddl leaves empty. Set-only, never cleared: the flag is a
    /// statement by the rule that owns the struct either way, so the two sources cannot disagree.
    pub fn set_custom_json(&mut self) {
        self.config.custom_json = true;
    }

    pub fn variant(&self) -> &RustStructType {
        &self.variant
    }

    /// Whether `self` and `other` describe the same generated type up to their NAME — same wire
    /// shape, same fields, same config, same tag.
    ///
    /// The global Rust-struct registration guard uses this to retain the first owner for every
    /// generated-name overlap, reusing a structurally equivalent claimant and rejecting an
    /// incompatible one before it can retarget shared IR. Multi-arm group-choice arms in different
    /// rules are the original benign case: generic arm names like `first`/`second` are idiomatic and
    /// recur across rules, so identical arms share one generated struct while differing arms are
    /// rejected.
    ///
    /// Compared through `Debug` rather than a derived `PartialEq`: equality on the IR type tree
    /// would be a much broader semantic commitment (what `encodings` or a doc comment mean for
    /// "equal") than this one question needs, and the `Debug` rendering is already the IR's
    /// structural fingerprint elsewhere (`api::ir_structs_debug`). `ident` is deliberately excluded —
    /// it is the very thing that differs — and it does not appear in any of the compared fields.
    pub fn structurally_equivalent(&self, other: &RustStruct) -> bool {
        self.structural_fingerprint() == other.structural_fingerprint()
    }

    /// The deterministic structural/wire identity used by the nominal-name mint registry.  Keep
    /// this exactly aligned with [`Self::structurally_equivalent`]: the registry is an earlier
    /// observation point for the global registration guard, not a second ownership policy.
    pub fn structural_fingerprint(&self) -> StructuralFingerprint {
        StructuralFingerprint(format!(
            "{:?}",
            (&self.tag, self.tag_optional, &self.config, &self.variant)
        ))
    }

    // The following methods are used internally to generate serialize/deserialize code
    // INSIDE of the serialize/deserialize implementations for this specific type.
    // You probably aren't interested in this from outside of that use-case.

    // Some(count) if it always has the same number of fields (ie no optional fields), None otherwise
    pub fn fixed_field_count(&self, types: &IntermediateTypes) -> Option<usize> {
        match &self.variant {
            RustStructType::Record(record) => record.fixed_field_count(types),
            RustStructType::Table { .. } => None,
            RustStructType::Array { .. } => None,
            // TODO: investigate if we should be supporting this for TypeChoice (also wrapper?)
            //RustStructType::TypeChoice { .. } => None,
            RustStructType::TypeChoice { .. } => {
                unreachable!("I don't think type choices should be using length?")
            }
            RustStructType::GroupChoice { .. } => {
                unreachable!("I don't think group choices should be using length?")
            }
            RustStructType::Wrapper { .. } => unreachable!("wrapper types don't use length"),
            RustStructType::Extern => panic!(
                "do we need to look this up ever? will the prelude have structs with fields?"
            ),
            RustStructType::CStyleEnum { .. } => Some(1),
            RustStructType::RawBytesType => Some(1),
        }
    }

    /// Even if fixed_field_count() == None, this will return an expression for
    /// a definite length, e.g. with optional field checks in the expression
    /// This is useful for definite-length serialization
    /// self_expr is an expression that evaluates to this struct (e.g. "self") at the point where
    /// the return of this function will be used.
    /// self_is_ref whether the above expression is by-ref
    pub fn definite_info(
        &self,
        self_expr: &str,
        self_is_ref: bool,
        types: &IntermediateTypes,
        cli: &Cli,
    ) -> String {
        match &self.variant {
            RustStructType::Record(record) => {
                record.definite_info(self_expr, self_is_ref, types, cli)
            }
            RustStructType::Table { .. } => format!("{self_expr}.0.len() as u64"),
            RustStructType::Array { .. } => format!("{self_expr}.0.len() as u64"),
            RustStructType::TypeChoice { .. } => {
                unreachable!("I don't think type choices should be using length?")
            }
            RustStructType::GroupChoice { .. } => {
                unreachable!("I don't think group choices should be using length?")
            }
            RustStructType::Wrapper { .. } => unreachable!("wrapper types don't use length"),
            RustStructType::Extern => panic!(
                "do we need to look this up ever? will the prelude have structs with fields?"
            ),
            RustStructType::CStyleEnum { .. } => "1".into(),
            RustStructType::RawBytesType => "1".into(),
        }
    }

    // the minimum cbor length of this struct - can be useful for deserialization length checks
    // does not count ANY type choice like types including Optional UNLESS the option Some type
    // has cbor len 1 too - to be consistent with expanded_field_count
    pub fn expanded_mandatory_field_count(&self, types: &IntermediateTypes) -> usize {
        match &self.variant {
            RustStructType::Record(record) => record.expanded_mandatory_field_count(types),
            RustStructType::Table { .. } => 0,
            RustStructType::Array { .. } => 0,
            //RustStructType::TypeChoice{ .. } => 0,
            RustStructType::TypeChoice { .. } => {
                unreachable!("I don't think type choices should be using length?")
            }
            RustStructType::GroupChoice { .. } => {
                unreachable!("I don't think group choices should be using length?")
            }
            RustStructType::Wrapper { .. } => unreachable!("wrapper types don't use length"),
            RustStructType::Extern => panic!(
                "do we need to look this up ever? will the prelude have structs with fields?"
            ),
            RustStructType::CStyleEnum { .. } => 1,
            RustStructType::RawBytesType => 1,
        }
    }

    pub fn cbor_len_info(&self, types: &IntermediateTypes) -> RustStructCBORLen {
        match &self.variant {
            RustStructType::Record(record) => record.cbor_len_info(types),
            RustStructType::Table { .. } => RustStructCBORLen::Dynamic,
            RustStructType::Array { .. } => RustStructCBORLen::Dynamic,
            //RustStructType::TypeChoice{ .. } => RustStructCBORLen::Dynamic,
            RustStructType::TypeChoice { .. } => {
                unreachable!("I don't think type choices should be using length?")
            }
            RustStructType::GroupChoice { .. } => {
                unreachable!("I don't think group choices should be using length?")
            }
            RustStructType::Wrapper { .. } => unreachable!("wrapper types don't use length"),
            RustStructType::Extern => panic!(
                "do we need to look this up ever? will the prelude have structs with fields?"
            ),
            RustStructType::CStyleEnum { .. } => RustStructCBORLen::Fixed(1),
            RustStructType::RawBytesType => RustStructCBORLen::Fixed(1),
        }
    }

    pub fn visit_types<F: FnMut(&ConceptualRustType)>(&self, types: &IntermediateTypes, f: &mut F) {
        self.visit_types_excluding(types, f, &mut BTreeSet::new())
    }
    pub fn visit_types_excluding<F: FnMut(&ConceptualRustType)>(
        &self,
        types: &IntermediateTypes,
        f: &mut F,
        already_visited: &mut BTreeSet<RustIdent>,
    ) {
        match &self.variant {
            RustStructType::Array { element_type, .. } => element_type
                .conceptual_type
                .visit_types_excluding(types, f, already_visited),
            RustStructType::GroupChoice { variants, .. }
            | RustStructType::TypeChoice { variants, .. }
            | RustStructType::CStyleEnum { variants } => {
                variants.iter().for_each(|v| match &v.data {
                    EnumVariantData::RustType(ty) => {
                        ty.conceptual_type
                            .visit_types_excluding(types, f, already_visited)
                    }
                    EnumVariantData::Inlined(record) => {
                        record.fields.iter().for_each(|field| {
                            field.rust_type.conceptual_type.visit_types_excluding(
                                types,
                                f,
                                already_visited,
                            )
                        });
                        record.forbidden_fields.iter().for_each(|field| {
                            field.rust_type.conceptual_type.visit_types_excluding(
                                types,
                                f,
                                already_visited,
                            )
                        });
                    }
                })
            }
            RustStructType::Record(record) => {
                record.fields.iter().for_each(|field| {
                    field
                        .rust_type
                        .conceptual_type
                        .visit_types_excluding(types, f, already_visited)
                });
                record.forbidden_fields.iter().for_each(|field| {
                    field
                        .rust_type
                        .conceptual_type
                        .visit_types_excluding(types, f, already_visited)
                });
                // Open rest (map `* k => v` row or array `* t` tail): the inner type(s) are real
                // occurrences (they can reference named rules), so a reference reachable ONLY through
                // the rest stays visible to `is_referenced` and friends. Walk the map K/V pair or the
                // array element per the rest kind.
                // An open table's TYPED row is the same shape and the same kind of occurrence, so it
                // walks through the identical arm — iterating both members rather than only `rest`
                // (a reference reachable only through `K_t`/`V_t` must stay visible too).
                for row in record.dynamic_rows() {
                    match &row.kind {
                        RestKind::MapEntries { domain, range, .. } => {
                            domain
                                .conceptual_type
                                .visit_types_excluding(types, f, already_visited);
                            range
                                .conceptual_type
                                .visit_types_excluding(types, f, already_visited);
                        }
                        RestKind::ArrayTail { element, .. } => {
                            element.conceptual_type.visit_types_excluding(
                                types,
                                f,
                                already_visited,
                            );
                        }
                    }
                }
            }
            RustStructType::Table { domain, range, .. } => {
                domain
                    .conceptual_type
                    .visit_types_excluding(types, f, already_visited);
                range
                    .conceptual_type
                    .visit_types_excluding(types, f, already_visited);
            }
            RustStructType::Wrapper { wrapped, .. } => wrapped
                .conceptual_type
                .visit_types_excluding(types, f, already_visited),
            RustStructType::Extern => (),
            RustStructType::RawBytesType => (),
        }
    }
}

// Regular struct with fields and such
#[derive(Clone)]
pub struct RustRecord {
    pub rep: Representation,
    pub fields: Vec<RustField>,
    /// A fixed map member with the exact occurrence window `0*0` (spelled `*0` too).
    /// It has no Rust value field: it is a constraint on the map key.  Keeping it in the IR (rather
    /// than teaching only the decoder about a list of keys) is important for extern-interface
    /// projection and for every construction boundary which must reject an open-row entry.
    pub forbidden_fields: Vec<ForbiddenField>,
    /// The open ("rest") part of an open struct-map (`{ 1: a, ..., * K => V }`) or an open array
    /// (`[ a, ..., * T ]`) — the trailing `* K => V` row / `* T` tail captured alongside the fixed
    /// fields, rather than a fake `RustField` (fields drive `new()`/JSON/wasm/`orig_deser_order`
    /// indices; the rest row does not participate in those). `None` for every closed struct — the
    /// snapshot corpus enforces byte-identical output for those. `Some` on a `Map`-rep record (rest
    /// row) or an `Array`-rep record (rest tail). `Box`ed to keep `RustRecord` (and the
    /// `EnumVariantData::Inlined` embedding it) small — `RestRow` holds one or two `RustType`s.
    pub rest: Option<Box<RestRow>>,
    /// Later positional occurrence segments of an ARRAY record.  The first segment remains in
    /// `rest` for the zero/one-segment ABI; this empty-by-default tail carries the remaining
    /// occurrence segments in authored wire order. Map records never populate it.
    pub array_segments: Vec<RestRow>,
    /// The TYPED row of an OPEN TABLE (`t = { * K_t => V_t, * K_r => V_r }`) — the leading
    /// `* K_t => V_t` row that claims exactly its key's single statically-known CBOR major, with
    /// `rest` holding the trailing catch-all that sees only the complement. `None` for every other
    /// record shape (closed struct, open struct-map with fixed keys, open array), so the snapshot
    /// corpus stays byte-identical for those.
    ///
    /// Deliberately a second `RestRow` rather than a new `RustStructType` variant or a fake
    /// `RustField`: the row is a DYNAMIC sequence exactly like `rest` (no `new()` argument, no JSON
    /// member name, no codegen-time key bytes, no mandatory-field check), so every piece of the
    /// delivered capture engine — `container_type()`, the duplicates policy, the encoding sidecars,
    /// the per-entry capture and serialize — applies to it verbatim. An open table is therefore a
    /// Record with ZERO fixed fields plus these two rows (`is_open_table()`), and the emitted
    /// deserialize loop is the delivered zero-declared-keys form, which already IS pure major-type
    /// dispatch.
    pub typed_row: Option<Box<RestRow>>,
}

// IR snapshots are a compatibility surface too.  Keep the empty-by-default extension invisible so
// every existing closed/single-segment record retains its byte-identical debug projection; a
// populated multi-segment record spells the new state explicitly for IR diagnostics.
impl std::fmt::Debug for RustRecord {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut debug = f.debug_struct("RustRecord");
        debug
            .field("rep", &self.rep)
            .field("fields", &self.fields)
            .field("forbidden_fields", &self.forbidden_fields)
            .field("rest", &self.rest)
            .field("typed_row", &self.typed_row);
        if !self.array_segments.is_empty() {
            debug.field("array_segments", &self.array_segments);
        }
        debug.finish()
    }
}

#[derive(Clone, Debug)]
pub struct ForbiddenField {
    pub key: FixedValue,
    /// The member's generated JSON spelling.  There is deliberately no public value member with
    /// this name, but JSON and extern-interface projection still need the authored identity.
    pub name: String,
    /// Retained for a faithful materialized-group projection and reference closure.
    pub rust_type: RustType,
    /// Source order among the group's entries, used by projections which preserve group order.
    pub source_index: usize,
}

/// Which of the two open struct-map flavors a rest row selects.
///
/// - `Capture` (the default): unknown entries are retained in a `pub` map field and round-tripped.
/// - `Ignore` (`@ignore` on the row): unknown entries are typed-deserialized and then DROPPED — no
///   struct field, serialize writes only the declared members. Deliberately lossy (documented), so
///   byte round-trips do not hold for wire data carrying unknown entries.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum RestSemantics {
    Capture,
    Ignore,
}

/// The rep-specific shape of a rest row: the map-only `* K => V` data (domain/range/duplicates) vs
/// the array-only `* T` tail element. Keeping them in separate variants makes the map-only fields
/// STRUCTURALLY UNREPRESENTABLE for an array tail (there is no `domain`/`duplicates` to mis-populate),
/// while `RestRow`'s shared `semantics`/`field_name` serve both. Every map-path accessor
/// (`domain()`/`range()`/`duplicates()`) is only reached on a `Map`-rep record, so it reads through
/// this without a rep check; the two rep-agnostic sites (the type visitor / dependency walk) match on
/// the variant to walk the right inner type(s).
// The map variant carries two `RustType`s and the array variant one, so the variants differ in size —
// immaterial here because a `RestRow` is only ever held behind `Option<Box<RestRow>>` on `RustRecord`,
// so the enum never sits inline in a hot value.
#[allow(clippy::large_enum_variant)]
#[derive(Clone, Debug)]
pub enum RestKind {
    /// `* K => V` rest row of an open struct-map.
    MapEntries {
        /// The key type (`K`). Supported key domains: `uint`, `text`, and `any`.
        domain: RustType,
        /// The value type (`V`). Any supported type, including `any`.
        range: RustType,
        /// `@duplicates` policy on the row. In the non-preserve capture flavor the container's `Eq`
        /// is value equality, so the default (reject) is enforced structurally by
        /// `insert().is_some()`; `Preserve` (the positional pair-list twin) selects the `PairMap`
        /// container.
        duplicates: Option<DuplicatesPolicy>,
    },
    /// `* T` occurrence-bearing segment of an open array (a positional analog of the map rest row:
    /// no keys, so no key dispatch, no duplicate policy, no canonical key merge).  Most shipped
    /// shapes are final tails; a variable major-disjoint or exact count-delimited middle segment
    /// retains its flattened source position so the wire emitters can interleave it with fixed fields.
    ArrayTail {
        /// The repeated element type (`T`). Any supported type, including `any`. Fixed-value
        /// elements (`* 5`) are rejected at recognition (a `Vec<FixedValue>` has no Rust
        /// representation).
        element: RustType,
        /// Flattened authored position of this occurrence-bearing array member.  Map rest rows do
        /// not carry a source position because their key dispatch is order-independent.
        source_index: usize,
    },
}

/// The dynamic ("rest") part of an open struct-map (`* K => V`) or an open array (`* T` segment).
/// Under the CAPTURE flavor the content lands in a `pub` field (`rest` by default, `@name`-overridable)
/// — a map container (`BTreeMap`/`OrderedHashMap`) for a loose map rest, a `Vec<T>` for a loose
/// array tail, or its checked `NonEmpty*` / `Bounded*` twin for a restricted window; under the
/// IGNORE flavor nothing is stored. Not a `RustField`: a loose rest row/tail is excluded from
/// `new()` (defaults empty), while every restricted map row is an explicit checked-carrier input so
/// the public value is valid by construction.
#[derive(Clone, Debug)]
pub struct RestRow {
    /// The rep-specific inner shape (map `* K => V` vs array `* T`).
    pub kind: RestKind,
    /// Capture (retain + round-trip) vs Ignore (tolerate-and-drop). Selects, at every emitter branch
    /// point, whether a `pub` field / constructor line / getter / encoding sidecar / serialize-back /
    /// JSON surface is emitted at all (capture-only) — while the deserialize arms and the IR visitors
    /// walk the row for BOTH flavors (both must consume the wire entries and both may pull in a runtime
    /// type through the inner type(s)).
    pub semantics: RestSemantics,
    /// The captured field's Rust name (default `rest`, overridable with `@name` on the row/tail).
    /// Only meaningful under `Capture`; `Ignore` emits no field.
    pub field_name: String,
    /// The single CBOR major type this row CLAIMS in the deserialize loop's `match raw.cbor_type()?`
    /// dispatch. `Some` only on an open table's TYPED row (`RustRecord::typed_row`), where it is
    /// derived in `IntermediateTypes::finalize` — never in the parse walk, because deriving it needs
    /// `cbor_types()` (which panics on an unregistered ident) and must run AFTER generic resolution,
    /// the same tier and the same reason as the float-key instruments. `None` on every catch-all rest
    /// row and array tail: those see the COMPLEMENT of the typed row's major (or, with no typed row,
    /// everything), which is not a single major and is expressed by the loop's arm layout instead.
    pub dispatch_major: Option<CBORType>,
    /// The normalized inclusive occurrence window for this dynamic sequence.
    /// `None` is the loose zero/MAX case; `Some(RestOccurrenceWindow::from_raw((1, u64::MAX)))` is the established `+` / `1*` NonEmpty carrier.
    /// Every other normalized window selects the appropriate Bounded carrier.
    /// [`RestOccurrenceWindow::raw`] exposes numeric endpoints; these are not authored optional endpoints like [`OccurrenceWindow`].
    /// The normalization lives on the row rather than in an emitter-local flag, so field spelling, decode conversion, JSON, wasm, WIT, and wrapper ownership all see the SAME invariant.
    /// Both array tails and dynamic map rows use the full loose/NonEmpty/Bounded carrier vocabulary.
    pub occurrence: Option<RestOccurrenceWindow>,
}

/// Whether any alias in `ty`'s alias chain carries a `@custom_serialize`/`@custom_deserialize`
/// directive. Only the ALIAS chain is walked: a rest-row domain reaches the peeked-key fast path only
/// when it resolves to a bare primitive/`any`, so an owning `Rust(ident)` struct (whose custom pair
/// lives on the struct config) is already on the typed path by shape.
pub(super) fn custom_codec_on_alias_chain(
    ty: &ConceptualRustType,
    types: &IntermediateTypes,
) -> bool {
    let mut cur = ty;
    while let ConceptualRustType::Alias(alias_ident, inner) = cur {
        if let Some(info) = types.type_aliases().get(alias_ident)
            && let Some(rmd) = info.rule_metadata.as_ref()
            && (rmd.custom_serialize.is_some() || rmd.custom_deserialize.is_some())
        {
            return true;
        }
        cur = inner;
    }
    false
}

/// The `@custom_wire_major` declaration on `ty`'s ALIAS CHAIN, if any — the declared-major channel
/// for a key whose wire a custom codec owns. Walked exactly like `custom_codec_on_alias_chain` (an
/// alias rule's directives ride `AliasInfo::rule_metadata`), and returning the FIRST declaration
/// found, walking outward-in: the outermost alias is the one whose codec actually writes the wire.
pub(super) fn declared_wire_major_on_alias_chain(
    ty: &ConceptualRustType,
    types: &IntermediateTypes,
) -> Option<crate::comment_ast::WireMajor> {
    let mut cur = ty;
    while let ConceptualRustType::Alias(alias_ident, inner) = cur {
        if let Some(info) = types.type_aliases().get(alias_ident)
            && let Some(rmd) = info.rule_metadata.as_ref()
            && let Some(major) = rmd.custom_wire_major
        {
            return Some(major);
        }
        cur = inner;
    }
    None
}

/// Record every alias on `ty`'s chain that carries a `@custom_wire_major`, so the
/// no-silent-directive check can tell a CONSUMED declaration from an inert one. Walks the whole
/// chain (not just to the first hit): an inner alias's declaration is equally consumed by the
/// dispatch that reads through it.
///
/// A declaration reached through an alias that INHERITED it (a re-alias, or a rule-body `.cbor`,
/// whose registration could not keep the `Alias` node the facts rode on) counts as consuming the
/// rule that WROTE it — so `AliasInfo::wire_metadata_inherited_from` is marked alongside. Without
/// that hop the author's own rule reads as inert and is rejected for a declaration a dispatch is
/// demonstrably reading.
pub(super) fn mark_wire_major_consumed(
    ty: &ConceptualRustType,
    types: &IntermediateTypes,
    consumed: &mut BTreeSet<AliasIdent>,
) {
    let mut cur = ty;
    while let ConceptualRustType::Alias(alias_ident, inner) = cur {
        if let Some(info) = types.type_aliases().get(alias_ident)
            && let Some(rmd) = info.rule_metadata.as_ref()
            && rmd.custom_wire_major.is_some()
        {
            consumed.insert(alias_ident.clone());
            if let Some(origin) = info.wire_metadata_inherited_from.as_ref() {
                consumed.insert(origin.clone());
            }
        }
        cur = inner;
    }
}

/// The `cbor_event` major-type value a `@custom_wire_major` token names. The one place the DSL
/// vocabulary meets the eight CBOR majors, so the mapping cannot drift between the parser and the
/// dispatch emitter.
pub(super) fn wire_major_to_cbor_type(major: crate::comment_ast::WireMajor) -> CBORType {
    use crate::comment_ast::WireMajor;
    match major {
        WireMajor::Uint => CBORType::UnsignedInteger,
        WireMajor::Nint => CBORType::NegativeInteger,
        WireMajor::Bytes => CBORType::Bytes,
        WireMajor::Text => CBORType::Text,
        WireMajor::Array => CBORType::Array,
        WireMajor::Map => CBORType::Map,
        WireMajor::Tag => CBORType::Tag,
        WireMajor::Simple => CBORType::Special,
    }
}

impl RestRow {
    /// The key type (`K`) of a map rest row. Only reached on a `Map`-rep record's rest row.
    pub fn domain(&self) -> &RustType {
        match &self.kind {
            RestKind::MapEntries { domain, .. } => domain,
            RestKind::ArrayTail { .. } => unreachable!("domain() on an array occurrence segment"),
        }
    }

    /// The value type (`V`) of a map rest row. Only reached on a `Map`-rep record's rest row.
    pub fn range(&self) -> &RustType {
        match &self.kind {
            RestKind::MapEntries { range, .. } => range,
            RestKind::ArrayTail { .. } => unreachable!("range() on an array occurrence segment"),
        }
    }

    /// The `@duplicates` policy of a map rest row; `None` for an array tail (no keys → no duplicate
    /// policy, so an array tail is never a `PairMap`).
    pub fn duplicates(&self) -> Option<DuplicatesPolicy> {
        match &self.kind {
            RestKind::MapEntries { duplicates, .. } => *duplicates,
            RestKind::ArrayTail { .. } => None,
        }
    }

    /// The element type (`T`) of an array occurrence segment. Only reached on an `Array`-rep record.
    pub fn element(&self) -> &RustType {
        match &self.kind {
            RestKind::ArrayTail { element, .. } => element,
            RestKind::MapEntries { .. } => unreachable!("element() on a map rest row"),
        }
    }

    /// The flattened authored position of an array occurrence segment. `None` for map rows, whose
    /// on-wire order is driven by keys rather than source position.
    pub fn array_source_index(&self) -> Option<usize> {
        match &self.kind {
            RestKind::ArrayTail { source_index, .. } => Some(*source_index),
            RestKind::MapEntries { .. } => None,
        }
    }

    /// Whether this rest is an occurrence-bearing array segment (vs a dynamic map `* K => V` row).
    pub fn is_array_tail(&self) -> bool {
        matches!(self.kind, RestKind::ArrayTail { .. })
    }

    /// Whether this is the one-or-more (`+` / `1*`) array-tail flavor. The container returned by
    /// `container_type` carries the same bound, so every type walk sees `NonEmptyVec<T>` rather than
    /// a detached boolean beside a loose `Vec<T>`.
    pub fn is_non_empty_array_tail(&self) -> bool {
        self.is_array_tail() && self.is_non_empty()
    }

    /// Whether this row is restricted at all (rather than the loose `*` / `0*` form).
    pub fn is_restricted(&self) -> bool {
        self.occurrence.is_some()
    }

    /// Whether this dynamic sequence has a finite, exact cardinality. `1*1` deliberately never
    /// reaches a rest row: it remains the ordinary mandatory-field path. Every other exact window
    /// is a Bounded carrier and gives a middle array segment a count boundary independent of the
    /// repeated element's wire head.
    pub fn has_exact_occurrence_window(&self) -> bool {
        self.occurrence.is_some_and(RestOccurrenceWindow::is_exact)
    }

    /// The row's established min-one window (`+` / `1*`). This remains its own predicate because
    /// the public constructor ABI for a typed open-table `+` is the shipped first-entry door.
    pub fn is_non_empty(&self) -> bool {
        self.occurrence
            .is_some_and(RestOccurrenceWindow::is_non_empty)
    }

    /// The RustType-form window used by the collection carriers: `u64::MAX` is rendered as the
    /// existing unbounded endpoint, and a zero lower endpoint stays absent so `BoundedMap` derives
    /// the conventional `min: None` range payload.
    pub fn rust_bounds(&self) -> Option<IntWindow> {
        self.occurrence.map(RestOccurrenceWindow::rust_bounds)
    }

    /// Whether a map rest row's key domain takes the FAST (peeked-key) deserialize path — the record
    /// loop's own `cbor_type()` dispatch has already read the key as a `u64`/`String`/`AnyCbor`, so the
    /// capture reconstructs it from those parts instead of running `K::deserialize`.
    ///
    /// That reconstruction is only FAITHFUL when the domain's whole wire image is the bare uint/text
    /// the dispatch read (or is `any`, which images every wire shape by construction). Three things
    /// each break the equivalence, so each routes the row to the typed seek path instead:
    ///
    /// * a non-empty `encodings` chain — `* #6.24(uint) => v` writes a tag the peeked read never
    ///   consumes, `* bytes .cbor uint => v` writes a byte string the peeked read never sees;
    /// * a `@custom_serialize`/`@custom_deserialize` pair anywhere on the alias chain — the writer is
    ///   honored inside `generate_serialize` while the peeked path never calls the READER, so a
    ///   transforming codec would write transformed keys and read raw ones;
    /// * anything whose conceptual type is not bare `uint`/`text`/`any` — there is nothing to
    ///   reconstruct from.
    ///
    /// The typed path costs one hoisted `raw.position()` anchor per loop body and a rewind in the
    /// declared-key catch-all, and is symmetric by construction (the same `K::deserialize` /
    /// `K::serialize` pair as every other position). Keeping the fast path for exactly the domains it
    /// is faithful for is what makes today's accepted rows byte-identical.
    pub fn map_key_uses_peeked_path(&self, types: &IntermediateTypes) -> bool {
        let domain = self.domain();
        if !domain.encodings.is_empty() {
            return false;
        }
        if custom_codec_on_alias_chain(&domain.conceptual_type, types) {
            return false;
        }
        matches!(
            domain.conceptual_type.resolve_alias_shallow(),
            ConceptualRustType::Any
                | ConceptualRustType::Primitive(Primitive::U64 | Primitive::Str)
        )
    }

    /// The rest row's CONTAINER type — the composite the emitted code actually names: `Array(T)` for
    /// an array `* T` tail, `Map(K, V)` carrying the row's `@duplicates` policy and, for a `+` typed
    /// open-table row, its `>= 1` bound (so `for_rust_member` routes a `preserve` row to the
    /// `PairMap<K, V>` / `NonEmptyPairMap<K, V>` twin and
    /// `for_wasm_member` / `wasm_collection_wrapper` name the `PairMapKToV` class rather than the
    /// loose `MapKToV`).
    ///
    /// The IR stores the inner types FLAT (`RestKind`), so without this every walk sees a rest row's
    /// `domain`/`range`/`element` as unrelated occurrences and never as a container — which is why
    /// the wasm wrapper the rest accessor returns has to be minted explicitly and why the
    /// dependency walk has to be told about it. Every consumer that needs the container goes
    /// through HERE (the rust member type, the wasm wrapper mint, `scope_references`' Record rest
    /// arm), so the container spelling cannot drift between them — a rest row's container is
    /// indistinguishable from a map/array FIELD's container to each of them.
    pub fn container_type(&self) -> RustType {
        let ty = self.staging_container_type();
        match self.rust_bounds() {
            Some(bounds) => ty.with_occurrence_bounds(bounds),
            None => ty,
        }
    }

    /// The deliberately loose container used only while decoding or transporting a dynamic row to
    /// its checked door. This is not a second representation: it is the source accepted by the
    /// carrier's `TryFrom`, with the same key/value and duplicate policy but no occurrence window.
    /// In particular, wasm uses it as the bounded typed-row constructor builder while keeping that
    /// row's public surface flattened on the owner class.
    pub fn staging_container_type(&self) -> RustType {
        match &self.kind {
            RestKind::ArrayTail { element, .. } => {
                ConceptualRustType::Array(Box::new(element.clone())).into()
            }
            RestKind::MapEntries {
                domain,
                range,
                duplicates,
            } => {
                let ty: RustType =
                    ConceptualRustType::Map(Box::new(domain.clone()), Box::new(range.clone()))
                        .into();
                ty.with_duplicates_policy(*duplicates)
            }
        }
    }
}

impl RustRecord {
    /// The declared JSON member names this record owns, followed by exact-zero forbidden names.
    /// The flattened rest writer reserves them; emitted JSON tests recognize all other members as
    /// dynamic-row entries.
    pub fn json_reserved_member_names(&self) -> Vec<String> {
        self.fields
            .iter()
            .filter(|f| !f.rust_type.conceptual_type.is_fixed_value() || f.optional)
            .map(|f| f.name.to_string())
            .chain(self.forbidden_fields.iter().map(|f| f.name.clone()))
            .collect()
    }

    /// Whether the native record constructor returns `Result` for value bounds or protected
    /// complete-rest validation. Boundary conversions (such as WASM's loose map builder) can
    /// introduce additional fallibility. Defaulted fields retain the mandatory-field rule.
    pub fn native_ctor_can_fail(&self, types: &IntermediateTypes) -> bool {
        self.fields
            .iter()
            .any(|f| !f.optional && f.rust_type.has_value_bounds())
            || self.captured_dynamic_rows().any(|row| {
                row.is_array_tail()
                    && row.element().has_value_bounds()
                    && (row.is_non_empty_array_tail() || !self.array_segments.is_empty())
            })
            || (self.is_non_empty_open_table()
                && self.typed_row().is_some_and(|row| {
                    row.domain().has_value_bounds() || row.range().has_value_bounds()
                }))
            || (self.has_forbidden_fields() && self.has_protected_rest_keys(types))
            || (self.has_protected_rest_keys(types)
                && self
                    .captured_rest()
                    .is_some_and(|row| !row.is_array_tail() && row.is_restricted()))
    }

    /// Whether constructor `new` takes this captured MAP row as its complete checked carrier: a
    /// restricted row (its occurrence window is enforced by the carrier), or any map row of a record
    /// whose forbidden fixed keys fall in the row's key space (its keys must be validated against
    /// them, so it cannot default empty and be filled through an unchecked door). The one predicate
    /// the native and wasm constructors and both emitted-test ABIs share, so they cannot disagree
    /// on arity. Callers still route the open-table typed row through its own door: NonEmpty takes
    /// first key/value and a bounded one a loose wasm builder. Parsing rejects an open table with
    /// any fixed or forbidden key, so its typed row is admitted here exactly when it is restricted.
    pub fn ctor_takes_complete_map_row(&self, row: &RestRow, types: &IntermediateTypes) -> bool {
        !row.is_array_tail()
            && (row.is_restricted()
                || (self.has_forbidden_fields() && self.has_protected_rest_keys(types)))
    }

    pub fn has_forbidden_fields(&self) -> bool {
        !self.forbidden_fields.is_empty()
    }

    /// A captured MAP row is protected when one of its possible CBOR key values can equal a fixed
    /// key in the same record. Such a row cannot expose its carrier for direct mutation: a collision
    /// would make the record serialize a duplicate map key.
    ///
    /// Bare `uint` and `text` domains have faithful, statically-disjoint wire majors, so a record
    /// whose fixed keys are all of the other kind needs no door. Everything on the typed seek path
    /// remains conservatively protected: tags, encodings and custom codecs can change the actual
    /// top-level wire value, and general domains can admit either fixed-key kind. Open tables have
    /// no fixed fields, so their dynamic rows remain their existing public containers.
    pub fn has_protected_rest_keys(&self, types: &IntermediateTypes) -> bool {
        let Some(rest) = self.captured_rest().filter(|row| !row.is_array_tail()) else {
            return false;
        };
        let has_fixed_kind = |want_uint: bool| {
            self.forbidden_fields
                .iter()
                .map(|field| &field.key)
                .chain(self.fields.iter().filter_map(|field| field.key.as_ref()))
                .any(|key| {
                    matches!(
                        (want_uint, key),
                        (true, FixedValue::Uint(_)) | (false, FixedValue::Text(_))
                    )
                })
        };
        if !rest.map_key_uses_peeked_path(types) {
            return has_fixed_kind(true) || has_fixed_kind(false);
        }
        match rest.domain().conceptual_type.resolve_alias_shallow() {
            ConceptualRustType::Primitive(Primitive::U64) => has_fixed_kind(true),
            ConceptualRustType::Primitive(Primitive::Str) => has_fixed_kind(false),
            ConceptualRustType::Any => has_fixed_kind(true) || has_fixed_kind(false),
            _ => unreachable!("the peeked rest-key path admits only bare uint/text/any"),
        }
    }
    /// The rest row IFF it CAPTURES (a `pub` map field is emitted and re-serialized). `None` for a
    /// closed struct AND for an `@ignore` (tolerate-and-drop) rest row, which stores nothing. Every
    /// capture-only emission (struct field, `new()` line, wasm getter, encoding sidecars, serialize
    /// of rest entries, flattened JSON, `definite_info`'s rest-count fold) keys on THIS, not on
    /// `rest.is_some()` — an ignore struct has no field to reference. The deserialize arms and the IR
    /// visitors keep using `rest` directly (both flavors consume the wire and may need a runtime type
    /// reachable only through `domain`/`range`).
    pub fn captured_rest(&self) -> Option<&RestRow> {
        self.rest
            .as_deref()
            .filter(|r| r.semantics == RestSemantics::Capture)
    }

    /// The rest row IFF it IGNORES (tolerate-and-drop): unknown entries are typed-deserialized and
    /// discarded, so nothing is stored and serialize re-emits only the declared members. `None` for a
    /// closed struct AND for a CAPTURE rest row. Used to attach the deliberate-lossiness rustdoc on
    /// the generated type and its `serialize` fn — the drop is invisible at the API surface otherwise,
    /// so a consumer must be told byte round-trips do not hold for wire data carrying unknown entries.
    pub fn ignored_rest(&self) -> Option<&RestRow> {
        self.rest
            .as_deref()
            .filter(|r| r.semantics == RestSemantics::Ignore)
    }

    /// The open table's TYPED row (`* K_t => V_t`), always a CAPTURE row (`@ignore` is rejected on
    /// it at recognition — an ignored typed row would leave the whole rule storing nothing).
    pub fn typed_row(&self) -> Option<&RestRow> {
        self.typed_row.as_deref()
    }

    /// Whether this record IS an open table (`t = { * K_t => V_t, * K_r => V_r }`): zero fixed
    /// fields plus both dynamic rows. The derived predicate that replaces a new `RustStructType`
    /// variant — every open-table-only behavior keys on THIS rather than on a variant match, so a
    /// plain record and an open-struct-map keep their exact pre-feature emission.
    pub fn is_open_table(&self) -> bool {
        self.fields.is_empty() && self.typed_row.is_some() && self.rest.is_some()
    }

    /// Both dynamic rows in WIRE-DISPATCH order (typed row first, then the catch-all), skipping the
    /// absent ones. The single iteration order every walk that must see BOTH members uses — a walk
    /// that reads only `rest` silently misses an open table's typed row.
    pub fn dynamic_rows(&self) -> impl Iterator<Item = &RestRow> {
        self.typed_row
            .as_deref()
            .into_iter()
            .chain(self.rest.as_deref())
            .chain(self.array_segments.iter())
    }

    /// Choose a deterministic generated identifier that cannot shadow a user-visible record field
    /// or dynamic row. Record constructors and the open-table JSON visitor both introduce names of
    /// their own (`first_key`, `<typed>_builder`, staging maps); row `@name`s are public, so those
    /// helpers suffix themselves instead of silently renaming the row.
    pub fn fresh_generated_member_ident(&self, preferred: &str) -> String {
        let occupied = self
            .fields
            .iter()
            .map(|field| field.name.clone())
            .chain(self.dynamic_rows().map(|row| row.field_name.clone()))
            .collect();
        Self::fresh_generated_ident_from_occupied(preferred, occupied)
    }

    /// Choose a generated parameter name for the typed `+` open-table constructor door. Only
    /// names that are ACTUALLY parameters of that constructor reserve the spelling: a loose row
    /// named `first_key`/`first_value` remains an ordinary field and must not perturb the shipped
    /// ABI. A restricted catch-all, by contrast, is a complete constructor argument and therefore
    /// must be avoided. `also_reserved` makes the second synthesized parameter avoid the first.
    pub fn fresh_open_table_non_empty_param_ident(
        &self,
        preferred: &str,
        also_reserved: impl IntoIterator<Item = String>,
    ) -> String {
        let occupied = self
            .fields
            .iter()
            .filter(|field| !field.optional && !field.rust_type.conceptual_type.is_fixed_value())
            .map(|field| field.name.clone())
            .chain(
                self.captured_dynamic_rows()
                    .filter(|row| {
                        !row.is_array_tail()
                            && row.is_restricted()
                            && !(self.is_typed_row(row) && self.is_non_empty_open_table())
                    })
                    .map(|row| row.field_name.clone()),
            )
            .chain(also_reserved)
            .collect();
        Self::fresh_generated_ident_from_occupied(preferred, occupied)
    }

    /// Choose the loose-builder parameter for a bounded typed open-table row.
    /// It shares a wasm constructor with mandatory fixed fields and restricted catch-all rows, but
    /// NOT with loose rows, so reserve exactly those parameter names rather than every public field.
    pub fn fresh_bounded_typed_wasm_builder_ident(&self, preferred: &str) -> String {
        let occupied = self
            .fields
            .iter()
            .filter(|field| !field.optional && !field.rust_type.conceptual_type.is_fixed_value())
            .map(|field| field.name.clone())
            .chain(
                self.captured_dynamic_rows()
                    .filter(|row| {
                        !self.is_typed_row(row) && !row.is_array_tail() && row.is_restricted()
                    })
                    .map(|row| row.field_name.clone()),
            )
            .collect();
        Self::fresh_generated_ident_from_occupied(preferred, occupied)
    }

    fn fresh_generated_ident_from_occupied(
        preferred: &str,
        occupied: std::collections::BTreeSet<String>,
    ) -> String {
        if !occupied.contains(preferred) {
            return preferred.to_owned();
        }
        for suffix in 2.. {
            let candidate = format!("{preferred}_{suffix}");
            if !occupied.contains(candidate.as_str()) {
                return candidate;
            }
        }
        unreachable!("unbounded suffix search must find a fresh generated member identifier")
    }

    /// Whether this record is the NonEmpty open table (`t = { + K_t => V_t, * K_r => V_r }`): the
    /// min-1 flavor, whose typed container must hold at least one entry. The predicate every
    /// bound-carrying emission keys on (the `new(first_key, first_value)` door, the checked CBOR
    /// staging conversion, the JSON visitor's staged assembly, the WIT constructor's two params).
    pub fn is_non_empty_open_table(&self) -> bool {
        self.is_open_table() && self.typed_row.as_deref().is_some_and(RestRow::is_non_empty)
    }

    /// Whether `row` is THIS record's open-table TYPED row. Pointer identity against `typed_row`,
    /// which is exact for the references `dynamic_rows()` yields (they borrow from `self`) and is a
    /// PARSE-time fact — unlike `RestRow::dispatch_major`, which only `finalize` fills in.
    pub fn is_typed_row(&self, row: &RestRow) -> bool {
        self.typed_row
            .as_deref()
            .is_some_and(|t| std::ptr::eq(t, row))
    }

    /// The CAPTURED dynamic rows in wire-dispatch order — the `dynamic_rows()` twin for every
    /// capture-only emission (struct field, `new()` line, wasm getter, encoding sidecars, serialize
    /// replay, `definite_info`'s length fold).
    pub fn captured_dynamic_rows(&self) -> impl Iterator<Item = &RestRow> {
        self.dynamic_rows()
            .filter(|r| r.semantics == RestSemantics::Capture)
    }

    pub fn fixed_field_count(&self, types: &IntermediateTypes) -> Option<usize> {
        // An OPEN struct (rest row present) has a variable number of wire entries, so it is never a
        // fixed-length map: forcing `None` here routes `cbor_len_info` to the dynamic class (so the
        // deserialize length check accounts each rest entry via `read_len.read_elems(1)` in the loop
        // + `read_len.finish()` after, rather than asserting a fixed count up front) and steers
        // `definite_info` to the additive branch that folds in `rest.len()`.
        // An exact-zero declaration has no serialized entry, but decode must still walk a map of
        // any length far enough to report `ForbiddenKey` rather than rejecting its header before
        // seeing the offending key.  Serialization remains the ordinary fixed-field count because
        // `definite_info` below contains no forbidden-member contribution.
        if self.rest.is_some() || self.typed_row.is_some() || self.has_forbidden_fields() {
            return None;
        }
        let mut count = 0;
        for field in &self.fields {
            if field.optional {
                return None;
            }
            count += match self.rep {
                Representation::Array => field.rust_type.expanded_field_count(types)?,
                Representation::Map => 1,
            };
        }
        Some(count)
    }

    /// This is guaranteed
    /// If inlined_enum is set, assumes the field is accessible via a local reference e.g. match branch
    /// Otherwise assumes it's a field e.g. self.name
    /// self_expr is an expression that evaluates to this struct (e.g. "self") at the point where
    /// the return of this function will be used.
    /// self_is_ref whether the above expression is by-ref
    pub fn definite_info(
        &self,
        self_expr: &str,
        self_is_ref: bool,
        types: &IntermediateTypes,
        cli: &Cli,
    ) -> String {
        match self.fixed_field_count(types) {
            Some(count) => count.to_string(),
            None => {
                let mut fixed_field_count = 0;
                let mut conditional_field_expr = String::new();
                for field in &self.fields {
                    if field.optional {
                        if field.rust_type.conceptual_type.is_fixed_value() {
                            // Optional fixed value (any kind, including float): modeled by a `bool`
                            // presence field (present => exactly one encoded item — an array element
                            // or a map key/value — absent => none). This replaces the former
                            // unconditional skip, which left `conditional_field_expr` empty and
                            // emitted the malformed `Len(1 + )` when it was the only dynamic-length
                            // field.
                            if !conditional_field_expr.is_empty() {
                                conditional_field_expr.push_str(" + ");
                            }
                            let self_field_expr = if self_expr.is_empty() {
                                Cow::Borrowed(&field.name)
                            } else {
                                Cow::Owned(format!("{}.{}", self_expr, field.name))
                            };
                            // An inlined enum arm's serialize match destructures `&self`, so an
                            // empty `self_expr` denotes a local `&bool` presence binding. Normal
                            // record field access (`self.field`) autodereferences its receiver;
                            // only this local-binding form needs an explicit dereference.
                            let presence_expr = if self_expr.is_empty() && self_is_ref {
                                Cow::Owned(format!("*{self_field_expr}"))
                            } else {
                                self_field_expr
                            };
                            conditional_field_expr
                                .push_str(&format!("if {presence_expr} {{ 1 }} else {{ 0 }}"));
                            continue;
                        }
                        if !conditional_field_expr.is_empty() {
                            conditional_field_expr.push_str(" + ");
                        }
                        let self_field_expr = if self_expr.is_empty() {
                            Cow::Borrowed(&field.name)
                        } else {
                            Cow::Owned(format!("{}.{}", self_expr, field.name))
                        };
                        if let Some(default_value) = &field.rust_type.config.default {
                            let field_contribution = match self.rep {
                                Representation::Array => Cow::Owned(field.rust_type.definite_info(
                                    &self_field_expr,
                                    true,
                                    types,
                                    cli,
                                )),
                                // maps are defined by their keys instead (although they shouldn't have multi-length values either...)
                                Representation::Map => Cow::Borrowed("1"),
                            };
                            if cli.preserve_encodings {
                                conditional_field_expr.push_str(&format!(
                                    "if {}.{} != {} || self.encodings.as_ref().map(|encs| encs.{}_default_present).unwrap_or(false) {{ {} }} else {{ 0 }}",
                                    self_expr,
                                    field.name,
                                    default_value.to_primitive_str_compare(),
                                    field.name,
                                    field_contribution));
                            } else {
                                conditional_field_expr.push_str(&format!(
                                    "if {}.{} != {} {{ {} }} else {{ 0 }}",
                                    self_expr,
                                    field.name,
                                    default_value.to_primitive_str_compare(),
                                    field_contribution
                                ));
                            }
                        } else {
                            let (field_expr, field_contribution) = match self.rep {
                                // when expanded_field_count is Some, definite_info returns the
                                // constant count.to_string() and never uses the binding, so bind
                                // `_` to avoid an unused-variable warning in the generated match.
                                Representation::Array => {
                                    match field.rust_type.expanded_field_count(types) {
                                        Some(count) => ("_", count.to_string()),
                                        None => (
                                            "x",
                                            field.rust_type.definite_info("x", true, types, cli),
                                        ),
                                    }
                                }
                                // maps are defined by their keys instead (although they shouldn't have multi-length values either...)
                                Representation::Map => ("_", String::from("1")),
                            };
                            conditional_field_expr.push_str(&format!(
                                "match {}{} {{ Some({}) => {}, None => 0 }}",
                                if self_is_ref { "" } else { "&" },
                                self_field_expr,
                                field_expr,
                                field_contribution
                            ));
                        }
                    } else {
                        match self.rep {
                            Representation::Array => {
                                match field.rust_type.expanded_field_count(types) {
                                    Some(field_expanded_count) => {
                                        fixed_field_count += field_expanded_count
                                    }
                                    None => {
                                        if !conditional_field_expr.is_empty() {
                                            conditional_field_expr.push_str(" + ");
                                        }
                                        let field_len_expr = field.rust_type.definite_info(
                                            &format!("self.{}", field.name),
                                            false,
                                            types,
                                            cli,
                                        );
                                        conditional_field_expr.push_str(&field_len_expr);
                                    }
                                }
                            }
                            Representation::Map => {
                                fixed_field_count += 1;
                            }
                        };
                    }
                }
                // Open struct/array (CAPTURE flavor only): the map/array header must count the captured
                // rest entries too. `rest` is a `pub` map/`Vec` field, so its live entry count is
                // `{self_expr}.rest.len()` (each map entry / trailing array element is one wire item).
                // Folding it in here keeps the serialize header and the deserialize length accounting in
                // agreement (both go through `definite_info`/the dynamic length class). Empty rest → `+
                // 0`, recovering the closed-struct byte count (empty-rest ≡ closed-struct invariant). The
                // IGNORE flavor stores and re-serializes NO rest entries and has no field to reference,
                // so its header is the closed-struct count — no fold (and `fixed_field_count` still
                // returns `None` for it, so the deser loop stays dynamic and tolerates+drops the extras).
                // The all-mandatory-prefix + ignore-tail combo reaches the `conditional_field_expr.
                // is_empty()` branch below (no optional field, no fold) → the plain mandatory count, not
                // a malformed `"{n} + "`.
                // An OPEN TABLE has two captured dynamic rows, so the header folds BOTH live counts
                // (`self.<typed>.len() + self.<rest>.len()`) — the same additive term per row.
                for row in self.captured_dynamic_rows() {
                    // `.len()` is `usize`; the map header (`cbor_event::Len::Len(u64)`) and the
                    // additive expression it joins are `u64`, so cast (`as` binds tighter than `+`).
                    let rest_len_expr = if self_expr.is_empty() {
                        format!("{}.len() as u64", row.field_name)
                    } else {
                        format!("{}.{}.len() as u64", self_expr, row.field_name)
                    };
                    if !conditional_field_expr.is_empty() {
                        conditional_field_expr.push_str(" + ");
                    }
                    conditional_field_expr.push_str(&rest_len_expr);
                }
                if conditional_field_expr.is_empty() {
                    // No optional field and no captured-rest fold (an `@ignore` open struct with only
                    // mandatory map fields reaches here via `fixed_field_count == None`): the definite
                    // length is exactly the mandatory count. Emitting `"{n} + "` would be malformed.
                    // Existing specs never hit this branch — a closed struct returns `Some(count)`
                    // early, and a capture open struct always folds a non-empty `rest.len()` term — so
                    // output for everything that exists today is byte-identical.
                    fixed_field_count.to_string()
                } else if fixed_field_count != 0 {
                    format!("{fixed_field_count} + {conditional_field_expr}")
                } else {
                    conditional_field_expr
                }
            }
        }
    }

    pub fn expanded_mandatory_field_count(&self, types: &IntermediateTypes) -> usize {
        self.fields
            .iter()
            .filter(|field| !field.optional)
            .map(|field| field.rust_type.expanded_mandatory_field_count(types))
            .sum()
    }

    pub fn cbor_len_info(&self, types: &IntermediateTypes) -> RustStructCBORLen {
        match self.fixed_field_count(types) {
            Some(fixed_count) => RustStructCBORLen::Fixed(fixed_count),
            None => RustStructCBORLen::OptionalFields(self.expanded_mandatory_field_count(types)),
        }
    }

    pub fn canonical_ordering<'a>(&'a self) -> Vec<(usize, &'a RustField)> {
        let mut fields: Vec<(usize, &'a RustField)> = self.fields.iter().enumerate().collect();
        if self.rep == Representation::Map {
            fields.sort_by(|lhs, rhs| {
                let lhs_bytes = lhs.1.key.as_ref().unwrap().to_bytes();
                let rhs_bytes = rhs.1.key.as_ref().unwrap().to_bytes();
                match lhs_bytes.len().cmp(&rhs_bytes.len()) {
                    std::cmp::Ordering::Equal => lhs_bytes.cmp(&rhs_bytes),
                    diff_ord => diff_ord,
                }
            });
        }
        fields
    }
}

// definition of a generic type e.g. foo<T, U> = [x: T, y: U]
#[derive(Debug)]
pub struct GenericDef {
    generic_params: Vec<GenericParamBinding>,
    pub(super) orig: RustStruct,
    /// Anonymous type choices parsed inside a generic record/collection body.  Their parser-time
    /// arm types retain exact generic bindings, but their enum owner cannot be registered until an
    /// instance supplies concrete arguments.  The placeholder is private to this definition and is
    /// rewritten to the materialized anonymous enum before the resolved root is registered.
    pub(super) inline_type_choices: Vec<GenericInlineTypeChoiceTemplate>,
    /// Nested generic applications whose arguments depend on this definition's exact lexical
    /// bindings.  They are parser-private templates rather than global instances: an `inner<p>`
    /// occurrence becomes `inner<uint>` only when a concrete `outer<uint>` supplies `p`.
    pub(super) child_instances: Vec<GenericChildInstanceTemplate>,
}

impl GenericDef {
    pub fn new(generic_params: Vec<GenericParamBinding>, orig: RustStruct) -> Self {
        Self {
            generic_params,
            orig,
            inline_type_choices: Vec::new(),
            child_instances: Vec::new(),
        }
    }

    pub(super) fn set_inline_type_choices(
        &mut self,
        inline_type_choices: Vec<GenericInlineTypeChoiceTemplate>,
    ) {
        self.inline_type_choices = inline_type_choices;
    }

    pub(super) fn set_child_instances(
        &mut self,
        child_instances: Vec<GenericChildInstanceTemplate>,
    ) {
        self.child_instances = child_instances;
    }

    #[cfg(test)]
    #[allow(dead_code)]
    pub(crate) fn original(&self) -> &RustStruct {
        &self.orig
    }

    #[cfg(test)]
    #[allow(dead_code)]
    pub(crate) fn inline_type_choices(&self) -> &[GenericInlineTypeChoiceTemplate] {
        &self.inline_type_choices
    }

    #[cfg(test)]
    #[allow(dead_code)]
    pub(crate) fn child_instances(&self) -> &[GenericChildInstanceTemplate] {
        &self.child_instances
    }
}

/// Parser-only nested generic application owned by one generic definition. `placeholder` is
/// returned to the enclosing type tree until finalization has substituted the owning instance's
/// exact bindings and registered the ordinary concrete child instance.
#[derive(Clone, Debug)]
pub struct GenericChildInstanceTemplate {
    pub(super) placeholder: RustIdent,
    pub(super) generic_ident: RustIdent,
    pub(super) generic_args: Vec<RustType>,
}

impl GenericChildInstanceTemplate {
    pub fn new(
        placeholder: RustIdent,
        generic_ident: RustIdent,
        generic_args: Vec<RustType>,
    ) -> Self {
        Self {
            placeholder,
            generic_ident,
            generic_args,
        }
    }
}

/// Parser-only anonymous type-choice template owned by a generic definition.  It deliberately
/// stores an ordinary `RustStruct`: once its arm `RustType`s are substituted it goes through the
/// same structural reuse and incompatible-registration checks as any other anonymous type choice.
#[derive(Clone, Debug)]
pub struct GenericInlineTypeChoiceTemplate {
    pub(super) placeholder: RustIdent,
    pub(super) template: RustStruct,
}

impl GenericInlineTypeChoiceTemplate {
    pub fn new(placeholder: RustIdent, template: RustStruct) -> Self {
        Self {
            placeholder,
            template,
        }
    }

    #[cfg(test)]
    #[allow(dead_code)]
    pub(crate) fn template(&self) -> &RustStruct {
        &self.template
    }
}

// invocation of a generic definition e.g. foo = bar<text>
#[derive(Debug)]
pub struct GenericInstance {
    pub(super) instance_ident: RustIdent,
    pub(super) generic_ident: RustIdent,
    generic_args: Vec<RustType>,
    // `true` when the instance ident was SYNTHESIZED for an anonymous use site (`[a: bar<text>]` →
    // `BarText`), rather than declared by a rule the author wrote (`foo = bar<text>`, ident `Foo`).
    // A synthesized name carries no user intent worth surfacing as its own wasm class: an anonymous
    // instance resolving to a TRANSPARENT COLLECTION lowers wasm-side to the STRUCTURAL wrapper
    // (`BarTextList`), exactly like the equivalent inline `[* text]`, rather than minting a
    // rule-named `#[wasm_bindgen]` class. See `converge_anonymous_collection_instance_wasm`.
    pub(super) anonymous: bool,
    /// The INSTANTIATION-derived nominal ident this instance mints, computed identically for every
    /// spelling of the same instantiation (`<def>_<args' for_variant()>` → `SetKeyHash`; Phase 2.3).
    /// For an anonymous use site this equals `instance_ident`; for a named binding
    /// (`named_set = set<key_hash>`, ident `NamedSet`) it is the instantiation nominal the binding
    /// aliases TO. Only consulted when the resolved def is a SET NOMINAL wrapper — every other
    /// instance keeps minting under `instance_ident` unchanged.
    pub(super) canonical_ident: RustIdent,
}

#[derive(Debug, Clone)]
// internal, short-lived during generic resolution and never stored in bulk,
// so the size gap doesn't matter. Box the Resolved variant only if it ever lands in a hot collection.
#[allow(clippy::large_enum_variant)]
pub enum GenericResolved {
    /// Resolved with types swapped to a concrete instance, plus the definition-owned inline
    /// choices that must be materialized before this root can be registered.
    Resolved {
        resolved: RustStruct,
        inline_type_choices: Vec<ResolvedGenericInlineTypeChoice>,
        child_instances: Vec<ResolvedGenericChildInstance>,
    },
    /// A generic SET-NOMINAL instance (`set<key_hash>` → `SetKeyHash`; Phase 2.3): the instantiation
    /// mints ONE nominal wrapper struct under `canonical_ident`, DEDUPED across every spelling of the
    /// same instantiation. `finalize` registers the struct once per distinct `canonical_ident`, and
    /// registers a transparent alias `instance_ident = canonical_ident` whenever the two differ (a
    /// named binding) — an anonymous instance's `instance_ident` already equals its canonical, so it
    /// needs no alias. The author's spelling is the identity (rev 7): `set<[* uint]>` and
    /// `set<xs_int>` mint DIFFERENT nominals openly.
    SetNominal {
        instance_ident: RustIdent,
        canonical_ident: RustIdent,
        resolved: RustStruct,
    },
    // could not resolve (def is extern)
    Extern {
        // internal generic ident e.g. FooBar for Foo<Bar>
        instance_ident: RustIdent,
        // actual data type e.g. Foo<Bar>
        real_ident: RustIdent,
        // Some(base) when `@raw_bytes_flavor` selected the `<base>RawBytes` wrapper for this
        // instance (a raw-bytes argument was supplied); `finalize` records the base so the extern
        // re-export glue emits `pub use crate::<base>RawBytes;`. None for the plain path.
        flavored_base: Option<RustIdent>,
    },
}

/// One concrete anonymous enum waiting for final registration.  `placeholder` is the parser-only
/// ident that still appears in the resolved generic root; finalization chooses/reuses the concrete
/// anonymous-owner ident and rewrites that reference before registering the root.
#[derive(Debug, Clone)]
pub struct ResolvedGenericInlineTypeChoice {
    pub(super) placeholder: RustIdent,
    pub(super) resolved: RustStruct,
}

/// A definition-owned child application after its owner's bindings have been substituted. Its
/// arguments may still name another child placeholder; finalization resolves that dependency in
/// deterministic child-first order before deriving the ordinary concrete instance identity.
#[derive(Debug, Clone)]
pub struct ResolvedGenericChildInstance {
    pub(super) placeholder: RustIdent,
    pub(super) generic_ident: RustIdent,
    pub(super) generic_args: Vec<RustType>,
}

impl GenericInstance {
    pub fn new(
        instance_ident: RustIdent,
        generic_ident: RustIdent,
        generic_args: Vec<RustType>,
        anonymous: bool,
        canonical_ident: RustIdent,
    ) -> Self {
        Self {
            instance_ident,
            generic_ident,
            generic_args,
            anonymous,
            canonical_ident,
        }
    }

    /// Whether two registrations for one emitted instance ident describe the same ordinary
    /// generic instance. The queue may encounter an equal definition-owned child after its
    /// concrete instance has already completed; that is compatible reuse, never replacement.
    /// Anonymous-versus-authored provenance does not change the concrete generic product; the
    /// first compatible claimant remains its owner just as ordinary struct registration does.
    pub(super) fn registration_compatible_with(&self, other: &Self) -> bool {
        self.generic_ident == other.generic_ident && self.generic_args == other.generic_args
    }

    // TODO: should we rename fields / variant names after-the-fact?
    // (for the cases where the name came from the original generic param)
    // returns None when it can't be resolved i.e. extern defs
    // this will be left to the user instead to handle.
    pub fn resolve(
        &self,
        types: &IntermediateTypes,
        cli: &Cli,
    ) -> Result<GenericResolved, Box<dyn std::error::Error>> {
        let def = match types.generic_defs.get(&self.generic_ident) {
            Some(def) => def,
            None => {
                if types
                    .rust_struct(&self.generic_ident)
                    .map(|rs| matches!(rs.variant(), RustStructType::Extern))
                    .unwrap_or(false)
                {
                    // The instance's `real_ident` is the full `Base<Args>` type expression: the
                    // `@raw_bytes_flavor` base name (`extern_base_ident`) plus the concrete args.
                    // The base-name/flavor decision is owned by `extern_base_ident` /
                    // `uses_raw_bytes_flavor` so this mint and the alias-import walk in
                    // `scope_references` reference the same base and cannot drift.
                    let real_ident = RustIdent::new_generic_with_base(
                        self.extern_base_ident(types).as_ref(),
                        &self.generic_args,
                        types,
                        cli,
                    );
                    let flavored_base = self
                        .uses_raw_bytes_flavor(types)
                        .then(|| self.generic_ident.clone());
                    return Ok(GenericResolved::Extern {
                        instance_ident: self.instance_ident.clone(),
                        real_ident,
                        flavored_base,
                    });
                }
                return Err(format!(
                    "generic instance `{}` references undefined generic type `{}`",
                    self.instance_ident, self.generic_ident
                )
                .into());
            }
        };
        if def.generic_params.len() != self.generic_args.len() {
            return Err(format!(
                "generic `{}` expects {} argument(s) but `{}` supplies {}",
                self.generic_ident,
                def.generic_params.len(),
                self.instance_ident,
                self.generic_args.len()
            )
            .into());
        }
        let resolved_args = def
            .generic_params
            .iter()
            .zip(self.generic_args.iter())
            .collect::<BTreeMap<&GenericParamBinding, &RustType>>();
        let mut instance = def.orig.clone();
        instance.ident = self.instance_ident.clone();

        // A generic SET NOMINAL def (`set<a0> = #6.258([* a0]) / [* a0]`) resolves to ONE nominal
        // wrapper per instantiation (Phase 2.3). Capture the flag before the `&mut instance.variant`
        // borrow so both the element resolution below and the post-match rename can consult it.
        let set_nominal = instance.config.set_nominal;

        match &mut instance.variant {
            RustStructType::Record(record) => {
                for field in record.fields.iter_mut() {
                    field.rust_type = Self::resolve_type(&resolved_args, &field.rust_type)?;
                }
            }
            RustStructType::Table { domain, range, .. } => {
                *domain = Self::resolve_type(&resolved_args, domain)?;
                *range = Self::resolve_type(&resolved_args, range)?;
            }
            RustStructType::Array { element_type, .. } => {
                *element_type = Self::resolve_type(&resolved_args, element_type)?;
            }
            RustStructType::TypeChoice { variants } | RustStructType::CStyleEnum { variants } => {
                for variant in variants.iter_mut() {
                    match &mut variant.data {
                        EnumVariantData::RustType(ty) => {
                            *ty = Self::resolve_type(&resolved_args, ty)?;
                        }
                        EnumVariantData::Inlined(_) => unreachable!(),
                    }
                }
            }
            RustStructType::GroupChoice { .. } => {
                // for variant in variants.mut_iter() {
                //     variant.rust_type = Self::resolve_type(&resolved_args, &variant.rust_type);
                // }
                todo!("we might need to recursively resolve on these");
            }
            RustStructType::Wrapper { wrapped, .. } => {
                // A generic wrapper can own a collection as a nominal type. The set-nominal branch
                // was the original instance of this shape; a complete custom codec pair on a named
                // generic table now self-nominalizes its Map for the same reason (one owner of the
                // whole wire). Resolve only the collection's immediate generic leaves — encoding
                // operations and bounds stay on `wrapped`, exactly as the Array/Table arms above.
                match &mut wrapped.conceptual_type {
                    ConceptualRustType::Array(element) => {
                        **element = Self::resolve_type(&resolved_args, element)?;
                    }
                    ConceptualRustType::Map(domain, range) => {
                        **domain = Self::resolve_type(&resolved_args, domain)?;
                        **range = Self::resolve_type(&resolved_args, range)?;
                    }
                    _ if set_nominal => unreachable!(
                        "a generic set nominal always wraps a homogeneous occurrence array"
                    ),
                    _ => todo!(
                        "generic wrapper substitution is supported only for homogeneous collection inners"
                    ),
                }
            }
            RustStructType::Extern => {
                panic!("generics should not be used on types in the prelude (e.g. int)")
            }
            RustStructType::RawBytesType => {
                panic!("generics not supported on raw bytes types")
            }
        };
        if set_nominal {
            // Mint under the INSTANTIATION-derived canonical ident (`SetKeyHash`), deduped by
            // `finalize` across every spelling of this instantiation; the binding's own ident aliases
            // to it when it differs.
            instance.ident = self.canonical_ident.clone();
            return Ok(GenericResolved::SetNominal {
                instance_ident: self.instance_ident.clone(),
                canonical_ident: self.canonical_ident.clone(),
                resolved: instance,
            });
        }
        let inline_type_choices = def
            .inline_type_choices
            .iter()
            .map(|template| {
                let mut resolved = template.template.clone();
                match &mut resolved.variant {
                    RustStructType::TypeChoice { variants }
                    | RustStructType::CStyleEnum { variants } => {
                        for variant in variants.iter_mut() {
                            match &mut variant.data {
                                EnumVariantData::RustType(ty) => {
                                    *ty = Self::resolve_type(&resolved_args, ty)?;
                                }
                                EnumVariantData::Inlined(_) => unreachable!(
                                    "an inline type-choice template has only type-bearing arms"
                                ),
                            }
                        }
                    }
                    _ => unreachable!("generic inline choice template must be a type choice"),
                }
                resolved.ident = Self::anonymous_type_choice_base_ident(&resolved);
                Ok(ResolvedGenericInlineTypeChoice {
                    placeholder: template.placeholder.clone(),
                    resolved,
                })
            })
            .collect::<Result<Vec<_>, Box<dyn std::error::Error>>>()?;
        let child_instances = def
            .child_instances
            .iter()
            .map(|template| {
                Ok(ResolvedGenericChildInstance {
                    placeholder: template.placeholder.clone(),
                    generic_ident: template.generic_ident.clone(),
                    generic_args: template
                        .generic_args
                        .iter()
                        .map(|arg| Self::resolve_type(&resolved_args, arg))
                        .collect::<Result<Vec<_>, Box<dyn std::error::Error>>>()?,
                })
            })
            .collect::<Result<Vec<_>, Box<dyn std::error::Error>>>()?;
        Ok(GenericResolved::Resolved {
            resolved: instance,
            inline_type_choices,
            child_instances,
        })
    }

    /// The concrete type arguments this instance was invoked with (`ext_set<pub_key>` → `[pub_key]`).
    /// Exposed so `scope_references`'s alias walk can import each argument type the resolved alias
    /// line names bare (`…<PubKey>`).
    pub(super) fn generic_args(&self) -> &[RustType] {
        &self.generic_args
    }

    /// `@raw_bytes_flavor`: the base extern is tagged AND at least one argument resolves to a
    /// `_CDDL_CODEGEN_RAW_BYTES_TYPE_`, so the instance references the convention-named
    /// `<Base>RawBytes` wrapper flavor instead of the plain `<Base>`. Opt-in only — a plain-name
    /// instance keeps compiling for wrappers bound solely on `RawBytesEncoding`, so this never fires
    /// without the tag.
    fn uses_raw_bytes_flavor(&self, types: &IntermediateTypes) -> bool {
        types.raw_bytes_flavor().contains(&self.generic_ident)
            && self
                .generic_args
                .iter()
                .any(|arg| Self::arg_is_raw_bytes(types, arg))
    }

    /// The base name the resolved extern alias references: the `<Base>RawBytes` wrapper flavor when
    /// `@raw_bytes_flavor` selected it (see [`Self::uses_raw_bytes_flavor`]), else the plain
    /// `<Base>`. The ONE owner of the flavor→base-name decision, called from both `resolve` (which
    /// mints the full `Base<Args>` real ident) and `scope_references`'s type-alias walk (which
    /// imports this base at the base extern's declaring scope, where the re-export glue places
    /// `pub use crate::<Base>[RawBytes];`). Single owner so the emitted alias target and its import
    /// cannot drift. The flavored name is built the same way the glue does — `{generic_ident}RawBytes`
    /// (`convert_to_camel_case` is idempotent on an already-camel base, so no name drift).
    pub(super) fn extern_base_ident(&self, types: &IntermediateTypes) -> RustIdent {
        if self.uses_raw_bytes_flavor(types) {
            RustIdent::new(CDDLIdent::new(format!("{}RawBytes", self.generic_ident)))
        } else {
            self.generic_ident.clone()
        }
    }

    fn resolve_type(
        args: &BTreeMap<&GenericParamBinding, &RustType>,
        orig: &RustType,
    ) -> Result<RustType, Box<dyn std::error::Error>> {
        if let Some(binding) = &orig.generic_param_binding
            && let Some(resolved_type) = args.get(binding)
        {
            // An argument's operations are INNER; operations around the parameter occurrence are
            // OUTER.  `SerializingRustType` wraps in vector order, so append the occurrence chain
            // after the argument chain (`#6.10(#6.20(uint))` is `[20, 10]`). A control such as
            // `p .size 3` is lowered before substitution, while its actual meaning depends on the
            // concrete argument's CDDL kind (bytes/string length vs an integer value range). Until
            // controls are represented through instantiation, refuse that occurrence-local config
            // rather than asserting or silently applying the wrong semantics.
            if orig.config != RustTypeSerializeConfig::default() {
                return Err(
                    "generic parameter occurrence has unsupported configuration; move its control/directive to the concrete argument or use site until generic control substitution is modeled"
                        .into(),
                );
            }
            let mut resolved = (*resolved_type).clone();
            resolved.encodings.extend(orig.encodings.iter().cloned());
            resolved.generic_param_binding = None;
            return Ok(resolved);
        }
        let mut resolved = orig.clone();
        match &mut resolved.conceptual_type {
            ConceptualRustType::Array(element) | ConceptualRustType::Optional(element) => {
                **element = Self::resolve_type(args, element)?;
            }
            ConceptualRustType::Map(domain, range) => {
                **domain = Self::resolve_type(args, domain)?;
                **range = Self::resolve_type(args, range)?;
            }
            // A conceptual alias stores only the type-tree, not a full RustType carrying a
            // parameter binding.  Any parameter occurrence that reaches substitution is therefore
            // represented by the Array/Map/Optional children above or the direct binding branch.
            ConceptualRustType::Fixed(_)
            | ConceptualRustType::Primitive(_)
            | ConceptualRustType::Rust(_)
            | ConceptualRustType::Alias(_, _)
            | ConceptualRustType::Any => {}
        }
        Ok(resolved)
    }

    pub(super) fn anonymous_type_choice_base_ident(choice: &RustStruct) -> RustIdent {
        let variants = match choice.variant() {
            RustStructType::TypeChoice { variants } | RustStructType::CStyleEnum { variants } => {
                variants
            }
            _ => unreachable!("generic inline choice template must be a type choice"),
        };
        let mut combined_name = String::new();
        for variant in variants {
            if !combined_name.is_empty() {
                combined_name.push_str("Or");
            }
            combined_name.push_str(
                &variant
                    .rust_type()
                    .conceptual_type
                    .for_variant()
                    .to_string(),
            );
        }
        RustIdent::new(CDDLIdent::new(&combined_name))
    }

    pub(super) fn rewrite_inline_choice_placeholders(
        rust_struct: &mut RustStruct,
        replacements: &BTreeMap<RustIdent, RustIdent>,
    ) {
        fn rewrite_type(ty: &mut RustType, replacements: &BTreeMap<RustIdent, RustIdent>) -> bool {
            match &mut ty.conceptual_type {
                ConceptualRustType::Rust(ident) => {
                    if let Some(replacement) = replacements.get(ident) {
                        *ident = replacement.clone();
                        true
                    } else {
                        false
                    }
                }
                ConceptualRustType::Array(element) | ConceptualRustType::Optional(element) => {
                    rewrite_type(element, replacements)
                }
                ConceptualRustType::Map(domain, range) => {
                    // Both descendants are mutable traversal targets. Do not use `||` directly here:
                    // its short-circuit semantics would leave a deferred value-side placeholder behind
                    // whenever the map key was also rewritten.
                    let domain_changed = rewrite_type(domain, replacements);
                    let range_changed = rewrite_type(range, replacements);
                    domain_changed || range_changed
                }
                ConceptualRustType::Fixed(_)
                | ConceptualRustType::Primitive(_)
                | ConceptualRustType::Alias(_, _)
                | ConceptualRustType::Any => false,
            }
        }

        match &mut rust_struct.variant {
            RustStructType::Record(record) => {
                for field in &mut record.fields {
                    rewrite_type(&mut field.rust_type, replacements);
                }
            }
            RustStructType::Table { domain, range, .. } => {
                rewrite_type(domain, replacements);
                rewrite_type(range, replacements);
            }
            RustStructType::Array { element_type, .. } => {
                rewrite_type(element_type, replacements);
            }
            RustStructType::TypeChoice { variants } | RustStructType::CStyleEnum { variants } => {
                for variant in variants {
                    if let EnumVariantData::RustType(ty) = &mut variant.data
                        && rewrite_type(ty, replacements)
                        && variant.derived_name
                    {
                        variant.name = ty.conceptual_type.for_variant();
                    }
                }
            }
            RustStructType::Wrapper { wrapped, .. } => {
                rewrite_type(wrapped, replacements);
            }
            RustStructType::GroupChoice { .. }
            | RustStructType::Extern
            | RustStructType::RawBytesType => {}
        }
    }

    /// Rewrite parser-private deferred child/inline placeholders in one type tree. Both sidecar
    /// kinds use `Rust(placeholder)` while they are private, so one exact traversal preserves the
    /// established recursive collection behavior.
    pub(super) fn rewrite_deferred_placeholders_in_type(
        ty: &mut RustType,
        replacements: &BTreeMap<RustIdent, RustIdent>,
    ) -> bool {
        match &mut ty.conceptual_type {
            ConceptualRustType::Rust(ident) => {
                if let Some(replacement) = replacements.get(ident) {
                    *ident = replacement.clone();
                    true
                } else {
                    false
                }
            }
            ConceptualRustType::Array(element) | ConceptualRustType::Optional(element) => {
                Self::rewrite_deferred_placeholders_in_type(element, replacements)
            }
            ConceptualRustType::Map(domain, range) => {
                let domain_changed =
                    Self::rewrite_deferred_placeholders_in_type(domain, replacements);
                let range_changed =
                    Self::rewrite_deferred_placeholders_in_type(range, replacements);
                domain_changed || range_changed
            }
            ConceptualRustType::Fixed(_)
            | ConceptualRustType::Primitive(_)
            | ConceptualRustType::Alias(_, _)
            | ConceptualRustType::Any => false,
        }
    }

    /// Whether a generic argument ultimately names a `_CDDL_CODEGEN_RAW_BYTES_TYPE_` struct. Follows
    /// inline conceptual aliases (`resolve_alias_shallow`) and named type aliases so an argument that
    /// reaches a raw-bytes struct through an intermediate alias still selects the flavor. The chain is
    /// bounded to guard against a pathological self-referential alias.
    fn arg_is_raw_bytes(types: &IntermediateTypes, arg: &RustType) -> bool {
        let mut ct = arg.conceptual_type.resolve_alias_shallow().clone();
        for _ in 0..16 {
            let ident = match ct {
                ConceptualRustType::Rust(ident) => ident,
                _ => return false,
            };
            if types
                .rust_struct(&ident)
                .map(|rs| matches!(rs.variant(), RustStructType::RawBytesType))
                .unwrap_or(false)
            {
                return true;
            }
            // Not a struct we recognize as raw-bytes — follow a named type alias if there is one.
            match types.resolve_alias(&AliasIdent::Rust(ident)) {
                Some(next) => ct = next.conceptual_type.resolve_alias_shallow().clone(),
                None => return false,
            }
        }
        false
    }
}

fn enum_variant_constant(variant: &EnumVariant) -> Option<FixedValue> {
    if let EnumVariantData::RustType(ty) = &variant.data
        && let ConceptualRustType::Fixed(constant) = ty.conceptual_type.resolve_alias_shallow()
    {
        return Some(constant.clone());
    }
    None
}

pub fn enum_variants_have_same_encoding_var(variants: &[EnumVariant]) -> bool {
    variants
        .iter()
        .fold(
            variants.first().and_then(enum_variant_constant),
            |acc: Option<FixedValue>, ev: &EnumVariant| -> Option<FixedValue> {
                match (&acc, enum_variant_constant(ev)) {
                    // all these share the same encoding var type (Option<Sz>)
                    (
                        Some(FixedValue::Uint(_) | FixedValue::Nint(_) | FixedValue::Float(_)),
                        Some(FixedValue::Uint(_) | FixedValue::Nint(_) | FixedValue::Float(_)),
                    ) => acc,
                    // Text and byte strings use the same StringEncoding carrier.  Fixed enum
                    // variants store no value, so their distinct decoded Rust carriers never
                    // cross this sidecar boundary; a mixed text/bytes choice can share it too.
                    (
                        Some(FixedValue::Text(_) | FixedValue::Bytes(_)),
                        Some(FixedValue::Text(_) | FixedValue::Bytes(_)),
                    ) => acc,
                    // these don't have any encoding vars
                    (
                        Some(FixedValue::Bool(_) | FixedValue::Null | FixedValue::Undefined),
                        Some(FixedValue::Bool(_) | FixedValue::Null | FixedValue::Undefined),
                    ) => acc,
                    _ => None,
                }
            },
        )
        .is_some()
}