canboat 9.1.0

// (C) 2009-2026, Kees Verruijt, Harlingen, The Netherlands.

//! Decode a `RawFrame` into a structured `DecodedPgn`.
//!
//! The decoder looks the frame's PGN up in the database, picks the
//! matching variant (manufacturer-specific PGNs disambiguated by
//! `Match` field values), and walks each field, extracting raw bits
//! and applying scaling, units, and lookup-table resolution.
//!
//! No I/O. No formatting — the result is a structured event ready for
//! the output formatter or for direct consumption by merrimac-rs.

use crate::engine::bits::{Extracted, Sentinel, classify_sentinel, extract_bits};
use crate::engine::db::PgnDatabase;
use crate::engine::frame::RawFrame;
use crate::engine::types::{FieldInfo, FieldType, PgnInfo};

/// Run the schema-2.5.0 sentinel classifier against a numeric
/// extraction using the field's own `UnknownValue` / `OutOfRangeValue`
/// / `ReservedValue` hints, and map any hit to the matching
/// [`FieldValue`] sentinel variant. Returns `None` when the extracted
/// value is a legitimate reading (no hint matched).
///
/// `raw` is read from [`Extracted::raw`] — the pre-sign-extension /
/// pre-offset unsigned bit pattern that the schema hints are stated
/// against. f64 conversion is never involved, so >53-bit fields and
/// signed-field cases round-trip bit-exactly.
fn sentinel_field_value(f: &FieldInfo, ex: Extracted) -> Option<FieldValue> {
    match classify_sentinel(ex, f.unknown_value, f.out_of_range_value, f.reserved_value) {
        Sentinel::Unknown => Some(FieldValue::NotAvailable),
        Sentinel::OutOfRange => Some(FieldValue::OutOfRange { value: ex.raw }),
        Sentinel::Reserved => Some(FieldValue::ReservedValue { value: ex.raw }),
        Sentinel::None => None,
    }
}

/// The tail of canboat's `fieldPrintLookup` for a value the
/// enumeration does not name: one in the top band of the field's width
/// is unavailable rather than a bare number —
///
/// ```text
///     *bits > 1 && value >= maxValue - (*bits > 2 ? 2 : 1)
/// ```
///
/// so a 2-bit lookup reserves its top value and anything wider its top
/// two. Shared, because the C reaches a *dynamic* LOOKUP through the
/// very same `fieldPrintLookup` as a static one; PGN 127501's
/// `Indicator11` and PGN 130845's `Auto calibration mode` are the same
/// rule seen from the two paths.
fn unnamed_lookup_value(ex: Extracted, bits: u32) -> FieldValue {
    if bits > 1 {
        let band = if bits > 2 { 2 } else { 1 };
        if ex.value >= ex.max - band {
            return FieldValue::NotAvailable;
        }
    }
    FieldValue::Lookup {
        value: ex.raw,
        name: None,
    }
}

/// The same test, for a field whose FieldType declares
/// `Sentinels: None` and so carries none of the hints above, but which
/// still has a `RangeMax` below what its bit width can hold.
///
/// The C never consults the FieldType's `Sentinels` when it works out
/// how many top-of-range values a field reserves — `reservedCount` is
/// derived from `rangeMax` against the raw bit-width maximum, capped by
/// `reservedCountForSize` (fieldtype.c). So an MMSI, whose range stops
/// at 999999999 in a 32-bit field, still reserves its top three values,
/// and `extractNumberNotEmpty` hands anything above the threshold to
/// `printEmpty`. `Sentinels: None` only stops the hints being written
/// into the document; it does not make every bit pattern valid.
fn range_max_sentinel(f: &FieldInfo, ex: Extracted, bits: u32) -> Option<FieldValue> {
    let range_max = f.range_max?;
    let resolution = f.resolution.unwrap_or(1.0);
    if bits == 0 || bits >= 64 || resolution <= 0.0 || !range_max.is_finite() {
        return None;
    }
    let raw_max = (1u64 << bits) - 1;
    // `rangeMax` is stated in DISPLAY units, so both display shifts have
    // to come off before it can be compared against the raw bit-width
    // maximum: the schema's `offset` (J1939 Excess-K: raw 0 reads
    // 233 K) and the unit conversion the Metric schema variant applies
    // on top of it (the same field's range is 485 K in SI and
    // 209.85 C in Metric — both raw 252). Dropping either term makes
    // the range look wider than the field can hold, the check bails
    // out, and the all-ones "not available" pattern decodes as a real
    // reading where the C prints Unknown.
    let display_offset = f.offset.map(|o| o as f64).unwrap_or(0.0);
    let raw_range_max_f = (range_max - display_offset - f.unit_offset) / resolution + 0.5;
    if raw_range_max_f < 0.0 {
        return None;
    }
    let raw_range_max = raw_range_max_f as u64;
    if raw_range_max >= raw_max {
        return None;
    }
    // reservedCountForSize(): 3 from 8 bits up, 2 from 4, 1 from 2.
    let by_size: u64 = match bits {
        8.. => 3,
        4..=7 => 2,
        2..=3 => 1,
        _ => 0,
    };
    let reserved = (raw_max - raw_range_max).min(by_size);
    if reserved == 0 || ex.raw <= raw_max - reserved {
        return None;
    }
    Some(match raw_max - ex.raw {
        0 => FieldValue::NotAvailable,
        1 => FieldValue::OutOfRange { value: ex.raw },
        _ => FieldValue::ReservedValue { value: ex.raw },
    })
}

/// A signed field's value below its `RangeMin` is out of range (#983):
/// a latitude of -111 degrees is not a position. A signed field's derived
/// `RangeMin` is the full negative end of its bits, so this only catches
/// a range the database states narrower than the bits (latitude,
/// longitude, angles of +/-pi, ...). The raw threshold is rounded the way
/// the encoder rounds its range check, so the two agree on the edge.
/// Mirrors the C `extractNumberNotEmpty`.
fn range_min_out_of_range(f: &FieldInfo, ex: Extracted) -> Option<FieldValue> {
    let range_min = f.range_min?;
    let resolution = f.resolution.unwrap_or(1.0);
    if resolution <= 0.0 || !range_min.is_finite() {
        return None;
    }
    let display_offset = f.offset.map(|o| o as f64).unwrap_or(0.0);
    let raw_min = ((range_min - display_offset - f.unit_offset) / resolution).round();
    (raw_min > i64::MIN as f64 && ex.value < raw_min as i64)
        .then_some(FieldValue::OutOfRange { value: ex.raw })
}

/// One decoded field.
///
/// Schema metadata (`id`, `name`, `order`, `unit`, `resolution`,
/// `precision`, `part_of_primary_key`) is read through accessor methods
/// that delegate to [`Self::info`] — the corresponding
/// [`FieldInfo`] entry in the static schema. Runtime values that the
/// decoder owns (`bit_offset`, `bit_length`, `repeat_*`, `value`) stay
/// as direct fields because they can legitimately differ from the
/// schema's declared values (repeating-set iterations shift the offset;
/// VARIABLE fields can be byte-aligned wider than the schema declares).
///
/// VARIABLE and DYNAMIC_FIELD_VALUE fields override unit / resolution /
/// precision with metadata drawn from a target FieldInfo or
/// LookupFieldTypeValue; those overrides live in a boxed
/// [`FieldOverrides`] sidecar — `None` in the common path, so the
/// 98 % of fields that don't override only carry an 8-byte null
/// pointer in the slot.
#[derive(Debug, Clone)]
pub struct DecodedField {
    /// Pointer back into the static [`FieldInfo`] this field was
    /// decoded against.
    pub info: &'static FieldInfo,
    pub value: FieldValue,
    /// Bit offset of this field within the parent payload. May differ
    /// from `info.bit_offset` for fields inside repeating sets (each
    /// iteration shifts) and for variable-length fields. `None` for
    /// synthetic fields.
    pub bit_offset: Option<u32>,
    /// Effective bit length on the wire. May differ from
    /// `info.bit_length` for STRING_LAU / VARIABLE / DYNAMIC_FIELD_VALUE
    /// fields (resolved at decode time).
    pub bit_length: Option<u32>,
    /// Zero-based iteration index for fields inside a repeating set;
    /// `None` for non-repeating fields.
    pub repeat_index: Option<u32>,
    /// Which RepeatingFieldSet this field belongs to: 1 → emitted
    /// under JSON `"list"`, 2 → under `"list2"`. `0` for non-repeating.
    pub repeat_set: u8,
    /// VARIABLE / DYNAMIC_FIELD_VALUE override metadata. `None` for
    /// the common path. Internal: the `unit()` / `resolution()` /
    /// `precision()` accessors are how a consumer sees its effect.
    pub(crate) overrides: Option<Box<FieldOverrides>>,
}

/// Resolved-at-decode-time metadata override carried by VARIABLE and
/// DYNAMIC_FIELD_VALUE fields. The accessors on [`DecodedField`]
/// consult these first, falling back to [`FieldInfo`].
///
/// `None` on a field means "no override at this level — use the value
/// from `info`".
#[derive(Debug, Clone)]
pub struct FieldOverrides {
    pub unit: Option<&'static str>,
    pub resolution: Option<f64>,
    /// `0` means "no override" (use `info.precision`); non-zero
    /// overrides.
    pub precision: u8,
}

impl DecodedField {
    /// canboat.json field `Order` (1-based schema position).
    #[inline]
    pub fn order(&self) -> u8 {
        self.info.order
    }

    /// canboat.json field `Id` (camelCase identifier).
    #[inline]
    pub fn id(&self) -> &'static str {
        self.info.id
    }

    /// canboat.json field `Name` (human label).
    #[inline]
    pub fn name(&self) -> &'static str {
        self.info.name
    }

    /// Display unit. Overridden by VARIABLE / DYNAMIC_FIELD_VALUE
    /// resolution; otherwise from [`FieldInfo::unit`].
    #[inline]
    pub fn unit(&self) -> Option<&'static str> {
        if let Some(o) = self.overrides.as_deref()
            && o.unit.is_some()
        {
            return o.unit;
        }
        self.info.unit
    }

    /// This field's numeric value expressed in `target` unit, converting
    /// from the field's own [`unit`](Self::unit) when they differ (see
    /// [`crate::engine::units::convert_unit`]). A unitless field is returned
    /// as-is; a numeric field whose unit has no known bridge to `target`
    /// yields `None`.
    ///
    /// This lets a consumer that needs a fixed unit stay correct no
    /// matter which schema ([`crate::engine::Units`]) produced the field — e.g.
    /// NMEA 0183 always asks angles for `"deg"` and temperatures for
    /// `"C"`, and gets them whether the stream was SI or Metric.
    pub fn as_f64_in(&self, target: &str) -> Option<f64> {
        let v = self.value.as_f64()?;
        match self.unit() {
            Some(from) => crate::engine::units::convert_unit(v, from, target),
            None => Some(v),
        }
    }

    /// Display resolution.
    #[inline]
    pub fn resolution(&self) -> Option<f64> {
        if let Some(o) = self.overrides.as_deref()
            && o.resolution.is_some()
        {
            return o.resolution;
        }
        self.info.resolution
    }

    /// Decimal precision override (`0` = derive from resolution).
    #[inline]
    pub fn precision(&self) -> u8 {
        if let Some(o) = self.overrides.as_deref()
            && o.precision > 0
        {
            return o.precision;
        }
        self.info.precision
    }

    /// `true` if this field participates in the PGN's primary key.
    #[inline]
    pub fn part_of_primary_key(&self) -> bool {
        self.info.part_of_primary_key.unwrap_or(false)
    }
}

/// The decoded value of one field.
#[derive(Debug, Clone)]
pub enum FieldValue {
    /// Scaled numeric value (`resolution * raw + offset`).
    Number(f64),
    /// Unscaled integer (used for fields with `resolution == 1` and no
    /// unit — counts, instances, etc.).
    Integer(i64),
    /// IEEE 754 float decoded from 32 raw bits.
    Float(f64),
    /// Raw bytes (BINARY) — uninterpreted.
    Binary(Vec<u8>),
    /// LOOKUP / INDIRECT_LOOKUP result.
    Lookup {
        value: u64,
        name: Option<&'static str>,
    },
    /// BITLOOKUP result — list of set bits with the bit-flag value
    /// (1 << bit) and resolved name for each.
    BitField {
        value: u64,
        /// One entry per *set bit*, in bit order: its value (`1 << bit`)
        /// and its name, or `None` when the enumeration does not name
        /// that bit. canboat emits unnamed set bits too — as
        /// `{"value":N,"name":null}` under `-nv` and as a bare `N`
        /// otherwise — so they must not be dropped.
        bits: Vec<(u64, Option<&'static str>)>,
    },
    /// A DECIMAL field's digits. canboat renders one byte as two
    /// decimal digits (`%02u`) and simply drops a byte that is not a
    /// valid pair, so the result is a run of digit pairs rather than a
    /// number — leading zeros included. Kept as text to preserve them;
    /// JSON quotes it, text prints it bare.
    Decimal(String),
    /// Decoded text (STRING_FIX, STRING_LZ, STRING_LAU).
    String(String),
    /// 16-bit days since 1970-01-01.
    Date(u16),
    /// Seconds since midnight (post-resolution scaling) plus the raw
    /// integer the decoder extracted. The raw is needed for `-nv`
    /// output `{"value":raw,"name":"HH:MM:SS.SSSS"}`.
    Time { raw: i64, seconds: f64 },
    /// MMSI as a 9-digit identifier.
    Mmsi(u32),
    /// 24-bit PGN number. `description` is the target PGN's
    /// human-readable name from the database, if known.
    Pgn {
        value: u32,
        description: Option<&'static str>,
    },
    /// ISO_NAME — a 64-bit packed identifier that is also a valid
    /// PGN 60928 (ISO Address Claim) payload. We carry the raw value
    /// and the recursively-decoded subfields side by side so the
    /// formatter can choose either form.
    IsoName {
        value: u64,
        subfields: Vec<DecodedField>,
    },
    /// RESERVED / SPARE — value preserved but the field is meaningless.
    /// The raw bytes (in field order, no resolution) ride along so the
    /// JSON formatter can emit them as hex strings, matching canboat.
    Reserved {
        value: u64,
        bytes: Vec<u8>,
        bit_length: u32,
    },
    Spare {
        value: u64,
        bytes: Vec<u8>,
        bit_length: u32,
    },
    /// Field exists but raw value is the canboat "not-available"
    /// sentinel (`UnknownValue` for schema-2.4.0 fields; the top-of-
    /// range heuristic value for older databases).
    NotAvailable,
    /// Raw value hit the field's `OutOfRangeValue` sentinel (schema
    /// 2.4.0). The formatter renders this as `"Out Of Range"` to
    /// match canboat C `analyzer/print.c`. The raw value rides along
    /// as `u64` so callers that want the wire pattern bit-exactly —
    /// including for >53-bit fields where `f64` would lose precision
    /// — can read it without going back to `RawFrame`.
    OutOfRange { value: u64 },
    /// Raw value hit the field's `ReservedValue` sentinel (schema
    /// 2.4.0 "reserved for future use"). Distinct from the
    /// [`FieldValue::Reserved`] variant above which represents an
    /// explicit `RESERVED` FieldType field (padding / structural).
    /// Formatter renders as `"Reserved"`.
    ReservedValue { value: u64 },
    /// Field decoding not yet implemented for this `FieldType`.
    Unsupported { field_type: &'static str },
}

impl FieldValue {
    /// Extract a `f64` for numeric variants. `Integer` widens; `Time`
    /// returns the post-resolution `seconds` value (matching what
    /// formatters show). Non-numeric variants return `None`.
    #[inline]
    pub fn as_f64(&self) -> Option<f64> {
        match self {
            FieldValue::Number(v) | FieldValue::Float(v) => Some(*v),
            FieldValue::Integer(v) => Some(*v as f64),
            FieldValue::Time { seconds, .. } => Some(*seconds),
            FieldValue::Date(d) => Some(*d as f64),
            FieldValue::Mmsi(v) => Some(*v as f64),
            _ => None,
        }
    }

    /// Extract a `i64` from integer-shaped variants. `Lookup` returns
    /// the raw enum integer; `Number` truncates; `Time` returns the
    /// raw scaled-out integer the decoder kept around.
    #[inline]
    pub fn as_i64(&self) -> Option<i64> {
        match self {
            FieldValue::Integer(v) => Some(*v),
            FieldValue::Number(v) => Some(*v as i64),
            FieldValue::Lookup { value, .. } => Some(*value as i64),
            FieldValue::BitField { value, .. } => Some(*value as i64),
            FieldValue::Time { raw, .. } => Some(*raw),
            FieldValue::Date(d) => Some(*d as i64),
            FieldValue::Mmsi(v) => Some(*v as i64),
            FieldValue::Pgn { value, .. } => Some(*value as i64),
            _ => None,
        }
    }

    /// Raw `u64` for `Lookup` / `BitField`. Use when you specifically
    /// want the enum tag without worrying about sign.
    #[inline]
    pub fn lookup_value(&self) -> Option<u64> {
        match self {
            FieldValue::Lookup { value, .. } => Some(*value),
            FieldValue::BitField { value, .. } => Some(*value),
            _ => None,
        }
    }

    /// `&str` for `String` / for the resolved `Lookup`/`BitField`
    /// label when one was found. Non-text variants return `None`.
    #[inline]
    pub fn as_str(&self) -> Option<&str> {
        match self {
            FieldValue::String(s) => Some(s.as_str()),
            FieldValue::Lookup { name: Some(n), .. } => Some(*n),
            _ => None,
        }
    }

    /// `true` when the field decoded to the canboat "not-available"
    /// sentinel — useful for callers that want to fall back to a
    /// default rather than emit nothing.
    #[inline]
    pub fn is_not_available(&self) -> bool {
        matches!(self, FieldValue::NotAvailable)
    }

    /// `true` when the field decoded to ANY of the three schema-2.4.0
    /// sentinels — Unknown, Out Of Range, or Reserved-value. Callers
    /// that just want "skip this field, the wire didn't carry a real
    /// reading" can check this in one call.
    #[inline]
    pub fn is_sentinel(&self) -> bool {
        matches!(
            self,
            FieldValue::NotAvailable
                | FieldValue::OutOfRange { .. }
                | FieldValue::ReservedValue { .. }
        )
    }
}

/// A fully decoded PGN event.
#[derive(Debug, Clone)]
pub struct DecodedPgn {
    pub timestamp: Option<String>,
    pub prio: u8,
    pub pgn: u32,
    pub src: u8,
    pub dst: u8,
    pub description: &'static str,
    /// canboat.json `Id` — stable camelCase identifier.
    pub id: &'static str,
    /// Mirror of [`crate::engine::types::PgnInfo::id_is_pinned`]: `true` when
    /// the schema's canboat C source explicitly pinned this PGN's
    /// `Id`. The JSON formatter wraps such records in `{"<id>":{…}}`
    /// to flag the stability contract to consumers.
    pub id_is_pinned: bool,
    /// The raw payload bytes the fields were decoded from. Kept on
    /// the DecodedPgn so the `-debug` JSON formatter can extract
    /// per-field `bytes` / `bits` annotations without holding the
    /// original `RawFrame`.
    pub data: Vec<u8>,
    pub fields: Vec<DecodedField>,
    /// `[set1, set2]` — true when the decoder reached the start
    /// field of the corresponding repeating set during this decode.
    /// False when the payload ran out before the set's start field
    /// or the PGN doesn't define a set at that index. The JSON
    /// formatter uses these to emit canboat's empty-`"list":[{}]`
    /// placeholder when the count is zero — matching the
    /// `"list":[{` opener that analyzer/analyzer.c:1276 emits the
    /// moment it sees the start field.
    pub has_repeating_set: [bool; 2],
    /// `index_by_order[order - 1]` = position in `self.fields` of
    /// the top-level (non-repeating) field whose schema `order` is
    /// `order`, or `i8::MIN` when the field wasn't decoded into
    /// `self.fields` (e.g. truncated payload, filtered out, or part
    /// of a repeating set). Populated by `decode_fields`. Used by
    /// [`Self::field`] to deliver `O(1)` handle lookups.
    ///
    /// 32 slots is canboat's hard cap on per-PGN field count. The
    /// array sits inline so the lookup is a single bounds-checked
    /// load with no allocation.
    pub index_by_order: [i8; 32],
}

impl DecodedPgn {
    /// Look up a non-repeating field by [`crate::engine::FieldRef`] — a generated
    /// constant (`crate::engine::field::wind_data::WIND_ANGLE`) or one
    /// resolved at runtime via [`crate::engine::PgnDatabase::field`]. Returns
    /// `None` when the field wasn't decoded in this payload (truncated,
    /// NotAvailable filtered by the decoder, etc.).
    ///
    /// `O(1)`: index by the field's schema `order`, one array load plus a
    /// bounds check. The `FieldRef` carries its own PGN, so a debug-only
    /// assert catches a constant used against the wrong record; it's a
    /// `&str` compare, free in release builds — no hashing on this path.
    #[inline]
    pub fn field(&self, f: crate::engine::FieldRef) -> Option<&DecodedField> {
        debug_assert_eq!(
            f.pgn.id, self.id,
            "FieldRef/PGN mismatch: a `{}` field ref was used on a `{}` record",
            f.pgn.id, self.id,
        );
        let idx_slot = (f.field.order as usize).checked_sub(1)?;
        let idx = *self.index_by_order.get(idx_slot)?;
        if idx < 0 {
            return None;
        }
        self.fields.get(idx as usize)
    }

    /// Look up a top-level field by name. `O(n)` linear scan over
    /// the decoded fields — fine for callers that don't have a
    /// [`crate::engine::FieldRef`] constant (e.g. AIS encoders that
    /// would otherwise need dozens of handles), since records
    /// typically have well under 20 fields. Faster than the
    /// JSON-substring-search alternative by a wide margin.
    #[inline]
    pub fn field_by_name(&self, name: &str) -> Option<&DecodedField> {
        self.fields
            .iter()
            .find(|f| f.repeat_set == 0 && f.name() == name)
    }

    /// The 64-bit ISO NAME of a PGN 60928 (ISO Address Claim) record —
    /// the ISO 11783-5 bit-packing of the claim's fields, identical to
    /// `u64::from_le_bytes(payload[..8])` for a spec-compliant frame.
    /// Returns `None` for any other PGN.
    ///
    /// Packs from the decoded *fields* (LSB-first, in schema order)
    /// rather than the raw bytes, so it works both for a record decoded
    /// from a frame and one rebuilt from analyzer JSON (which carries no
    /// payload). That makes it the canonical device key for the
    /// per-NAME NMEA 0183 filter, computed identically by every daemon.
    /// The reserved `Spare` bit is taken as its spec value 0; every
    /// consumer computing the NAME the same way still gets a stable key.
    ///
    /// A field the decoder reports as not available had all its bits set
    /// on the wire (a System Instance of 15, say), so it packs as all
    /// ones, not 0. One that hit the out-of-range or reserved sentinel
    /// packs the raw value it carries (a System Instance of 14 or 13).
    pub fn iso_name(&self) -> Option<u64> {
        if self.pgn != 60928 {
            return None;
        }
        let f = |name: &str, bits: u32| -> u64 {
            let mask = (1u64 << bits) - 1;
            self.field_by_name(name)
                .and_then(|df| match df.value {
                    FieldValue::OutOfRange { value } | FieldValue::ReservedValue { value } => {
                        Some(value)
                    }
                    ref v => v.as_i64().map(|v| v as u64),
                })
                .map_or(mask, |v| v & mask)
        };
        Some(
            f("Unique Number", 21)
                | f("Manufacturer Code", 11) << 21
                | f("Device Instance Lower", 3) << 32
                | f("Device Instance Upper", 5) << 35
                | f("Device Function", 8) << 40
                // bit 48: Spare (reserved, 0)
                | f("Device Class", 7) << 49
                | f("System Instance", 4) << 56
                | f("Industry Group", 3) << 60
                | f("Arbitrary address capable", 1) << 63,
        )
    }
}

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum DecodeError {
    #[error("PGN {pgn} not found in database")]
    #[non_exhaustive]
    UnknownPgn { pgn: u32 },
    #[error("PGN {pgn} payload too short for field {field:?}")]
    #[non_exhaustive]
    ShortPayload { pgn: u32, field: String },
}

impl PgnDatabase {
    /// Decode one frame.
    ///
    /// Picks the matching PGN variant (via `Match` field values) and
    /// walks every field. For unknown PGNs returns
    /// `DecodeError::UnknownPgn`.
    pub fn decode(&self, frame: &RawFrame) -> Result<DecodedPgn, DecodeError> {
        let info = self
            .pick_variant(frame)
            .ok_or(DecodeError::UnknownPgn { pgn: frame.pgn })?;

        let (mut fields, has_repeating_set) = decode_fields(info, &frame.data, self)?;
        // Opt-in device-quirk corrections (GPS week rollover); each a
        // no-op — one relaxed atomic load — unless a quirk was switched
        // on. The quirk keys devices by ISO NAME, which is the whole
        // PGN 60928 payload, so it learns those here as they go by.
        if frame.pgn == 60928 {
            crate::engine::quirk::note_address_claim(frame.src, &frame.data);
        }
        crate::engine::quirk::apply(frame.pgn, frame.src, &mut fields);
        let index_by_order = build_index_by_order(&fields);

        Ok(DecodedPgn {
            timestamp: frame.timestamp.clone(),
            prio: frame.prio,
            pgn: frame.pgn,
            src: frame.src,
            dst: frame.dst,
            description: info.description,
            id: info.id,
            id_is_pinned: info.id_is_pinned,
            data: frame.data.to_vec(),
            fields,
            has_repeating_set,
            index_by_order,
        })
    }

    /// Choose the best PGN definition for a frame.
    ///
    /// Priority — strict canboat semantics:
    ///
    ///   1. **JSON-order scan of variants for this PGN number.** Return
    ///      the first variant whose every `Match` field equals the raw
    ///      bits at that field's offset. JSON insertion order encodes
    ///      author-defined priority; an earlier matching specific
    ///      variant always beats a later one, and a matching specific
    ///      variant always beats the per-PGN-number fallback even when
    ///      the fallback is listed first (as in PGN 126208 etc).
    ///
    ///   2. **In-PGN fallback.** If no specific variant matched, return
    ///      the `Fallback: true` variant for this PGN number, if any.
    ///      Falls back further to any no-`Match` variant — though in
    ///      canboat.json those two are the same entry.
    ///
    ///   3. **Inter-PGN fallback.** If the PGN number itself is not in
    ///      the database, return the largest `Fallback: true` entry
    ///      whose PGN number is `<= frame.pgn`. This is the catch-all
    ///      that covers the range — e.g. unknown PGNs in
    ///      `[0x1ef00, 0x1ef00]` get
    ///      `0x1ef00ManufacturerProprietaryFastPacketAddressed`.
    pub fn pick_variant(&self, frame: &RawFrame) -> Option<&'static PgnInfo> {
        // Generated by keel: a `match` jumps to a per-PGN dispatch
        // function that extracts each unique Match-field bit-range
        // exactly once and returns the right variant in JSON order
        // (or the no-Match fallback for that PGN). Falls back to the
        // sparse cross-PGN catch-all when no entry for this PGN
        // number exists at all.
        // Each schema flavor (NMEA 2000, J1939) carries its own
        // dispatch pair; the returned index is only valid against this
        // db's own PGN arrays (identical across SI and Metric), so map
        // it through `pgn_slice` for the right units.
        let idx = (self.dispatch)(frame.pgn, &frame.data).or_else(|| (self.catchall)(frame.pgn))?;
        Some(&self.pgn_slice()[idx])
    }
}

/// Walk a PGN's fields, decoding each in turn.
///
/// Handles repeating field sets (`RepeatingFieldSet1`) — when the
/// walker reaches `repeating_field_set1_start_field`, it pulls the
/// count from the already-decoded count field, then re-runs the set
/// of `size` repeating fields N times. Each iteration's fields share
/// the layout of the first iteration shifted by `iteration_bits`
/// (the sum of `BitLength` over the set).
///
/// `Condition`-gated alternative fields are skipped (full evaluation
/// is deferred to a later commit).
/// State the decoder threads through fields so VARIABLE-typed fields
/// can find their target metadata.
///
/// - `target_pgn` is updated whenever a [`FieldValue::Pgn`] is emitted
///   (PGN 126208 group functions carry the target PGN in field 2).
/// - `current_param_idx` is updated whenever a `FIELD_INDEX` field is
///   emitted, so the next VARIABLE field knows which target field's
///   metadata to use.
#[derive(Default, Debug, Clone)]
struct DecodeContext {
    target_pgn: Option<u32>,
    current_param_idx: Option<u32>,
    /// Resolved DYNAMIC_FIELD_KEY entry — set when a key field is
    /// decoded, read by the matching DYNAMIC_FIELD_VALUE, cleared
    /// after. Stored as cloned data so we don't have to thread a
    /// lifetime through every decoder.
    dynamic_field_type: Option<crate::engine::types::LookupFieldTypeValue>,
    /// Byte length from a DYNAMIC_FIELD_LENGTH field, net of the
    /// record overhead. Cleared with `dynamic_field_type` after the
    /// value is decoded. Signed, and legitimately negative when a
    /// truncated record declares a length below its own header — the
    /// C's `g_length` is `int64_t` for the same reason.
    dynamic_length_bytes: Option<i64>,
    /// Raw value of the last field that went through canboat's
    /// `extractNumberNotEmpty` — its `g_previousFieldValue`. A BINARY
    /// field with no declared width takes its *bit* length from this
    /// (`fieldPrintBinary`, print.c).
    previous_field_value: u64,
    /// Set by a decoder that wants its field omitted from the output
    /// while the walk carries on past it — canboat's `g_skip`
    /// (print.c). Read and cleared by the field walker.
    skip_field: bool,
    /// Which definition of `target_pgn` the parameters address, and
    /// whether it had to be borrowed from the catch-all. Resolved at
    /// the first VARIABLE field and reused for the rest of the record,
    /// mirroring the C's `g_refPgn` (analyzer.c).
    resolved_target: Option<(&'static PgnInfo, bool)>,
}

fn decode_fields(
    info: &'static PgnInfo,
    data: &[u8],
    db: &PgnDatabase,
) -> Result<(Vec<DecodedField>, [bool; 2]), DecodeError> {
    let mut out = Vec::with_capacity(info.fields.len());
    let mut ctx = DecodeContext::default();
    let start1 = info.repeating_field_set1_start_field;
    let size1 = info.repeating_field_set1_size;
    let count_field1 = info.repeating_field_set1_count_field;
    let start2 = info.repeating_field_set2_start_field;
    let size2 = info.repeating_field_set2_size;
    let count_field2 = info.repeating_field_set2_count_field;
    let mut entered = [false, false];

    let mut i = 0usize;
    // Running bit cursor — used both for variable-length fields that
    // lack an explicit BitOffset and as the entry point for repeating
    // sets that follow other variable-length content.
    let mut cursor_bits: u32 = 0;
    while i < info.fields.len() {
        let f = &info.fields[i];

        // Repeating set 1 starts here? `count_field1` can be absent
        // (e.g. PGN 126464 PGN List) — in that case canboat repeats
        // until the payload runs out.
        if let (Some(start), Some(size)) = (start1, size1)
            && (f.order as u32) == start
        {
            // Only mark as "entered" if the start field is
            // actually within the payload, and whole — canboat C's main
            // loop stops once `startBit >> 3 >= length`, and does not
            // open a list whose first field the payload ends inside,
            // so neither emits the list opener.
            let bit_offset = f.bit_offset.unwrap_or(cursor_bits);
            let total = data.len() as u32 * 8;
            if bit_offset < total && !is_cut_short(f, bit_offset, total) {
                entered[0] = true;
            }
            cursor_bits = decode_repeating(
                info,
                data,
                db,
                &mut out,
                &mut ctx,
                i,
                size as usize,
                count_field1,
                cursor_bits,
                1,
            );
            i += size as usize;
            continue;
        }
        // Repeating set 2?
        if let (Some(start), Some(size)) = (start2, size2)
            && (f.order as u32) == start
        {
            let bit_offset = f.bit_offset.unwrap_or(cursor_bits);
            let total = data.len() as u32 * 8;
            if bit_offset < total && !is_cut_short(f, bit_offset, total) {
                entered[1] = true;
            }
            cursor_bits = decode_repeating(
                info,
                data,
                db,
                &mut out,
                &mut ctx,
                i,
                size as usize,
                count_field2,
                cursor_bits,
                2,
            );
            i += size as usize;
            continue;
        }

        if !field_present(f.condition, ctx.target_pgn) {
            i += 1;
            continue;
        }
        // Variable-length fields (STRING_LAU and friends) after the
        // first one have no `BitOffset` in canboat.json — they sit at
        // the byte after the previous variable field ends. Use a
        // running `cursor_bits` for those; honor an explicit BitOffset
        // when one is given.
        let effective_offset = f.bit_offset.unwrap_or(cursor_bits);
        if let Some((decoded, bits_consumed)) =
            decode_one_field_at(f, info, data, db, effective_offset, &mut ctx)
        {
            cursor_bits = effective_offset + bits_consumed;
            // `skip_field` omits the field but keeps the walk going,
            // and the cursor has already advanced past it.
            if core::mem::take(&mut ctx.skip_field) {
                i += 1;
                continue;
            }
            out.push(decoded);
        }
        i += 1;
    }
    Ok((out, entered))
}

/// Compute `DecodedPgn::index_by_order` from a freshly-decoded
/// `fields` Vec. For every top-level field (`repeat_set == 0`),
/// record its `Vec` position at slot `field.order - 1`. Slots with
/// no decoded field — truncated payloads, NotAvailable filtered
/// out, or schema positions belonging to a repeating set — keep
/// the `i8::MIN` sentinel.
pub(crate) fn build_index_by_order(fields: &[DecodedField]) -> [i8; 32] {
    let mut idx = [i8::MIN; 32];
    for (pos, f) in fields.iter().enumerate() {
        if f.repeat_set != 0 {
            continue;
        }
        if let Some(slot) = (f.order() as usize).checked_sub(1)
            && slot < idx.len()
            && pos < i8::MAX as usize
        {
            idx[slot] = pos as i8;
        }
    }
    idx
}

#[allow(clippy::too_many_arguments)]
fn decode_repeating(
    info: &'static PgnInfo,
    data: &[u8],
    db: &PgnDatabase,
    out: &mut Vec<DecodedField>,
    ctx: &mut DecodeContext,
    start_idx: usize,
    set_size: usize,
    count_field_order: Option<u32>,
    base_cursor: u32,
    set_number: u8,
) -> u32 {
    // Look up the count from the already-decoded fields when a count
    // field is set; otherwise repeat until the payload runs out
    // (matches canboat's default g_variableFieldRepeat[0] = 255 path).
    // Canboat's `printFields` always enters the repeat block with
    // `repetition = 1` once it reaches the set's start field, even
    // when the count field decoded to zero (see analyzer.c:1284 vs
    // 1300). The decremented `variableFields` counter only triggers
    // *additional* loops, so count=0 yields exactly one iteration as
    // long as payload remains. Match that here: floor count at 1
    // when it's set, fall back to "iterate until payload runs out"
    // when the count field is NotAvailable or otherwise unresolved.
    let raw_count: Option<u32> = count_field_order.and_then(|cf| {
        out.iter()
            .find(|d| (d.order() as u32) == cf)
            .and_then(|d| match &d.value {
                FieldValue::Integer(n) if *n >= 0 => Some(*n as u32),
                FieldValue::Number(n) if *n >= 0.0 => Some(*n as u32),
                _ => None,
            })
    });
    // count=0 still produces exactly one (truncated) iteration — see
    // the long comment above the call site. Track this case so the text
    // formatter only labels the *first* field with " 1".
    let count_was_zero = raw_count == Some(0);
    let max_iters: u32 = match raw_count {
        Some(n) => n.max(1),
        None => u32::MAX,
    };

    let set = &info.fields[start_idx..start_idx + set_size];
    if set.is_empty() {
        return base_cursor;
    }
    let payload_bits = (data.len() as u32).saturating_mul(8);

    // Use the iteration's first field's BitOffset if available — that
    // anchors iteration 0 to the canboat.json layout. After that we
    // run on a per-iteration sub-cursor that advances by each field's
    // actual `bits_consumed` (handles variable-length VARIABLE fields).
    let mut iter_cursor = set[0].bit_offset.unwrap_or(base_cursor);

    for iter in 0..max_iters {
        if iter_cursor >= payload_bits {
            break;
        }
        let mut sub_cursor = iter_cursor;
        let mut produced_any = false;
        let mut first_field_of_iter = true;
        for sf in set {
            if !field_present(sf.condition, ctx.target_pgn) {
                continue;
            }
            // Iteration 0 honors the explicit BitOffset from JSON;
            // later iterations follow the running sub_cursor since
            // bit_offsets aren't repeated per iteration in JSON.
            let off = if iter == 0 {
                sf.bit_offset.unwrap_or(sub_cursor)
            } else {
                sub_cursor
            };
            if let Some((mut d, bits)) = decode_one_field_at(sf, info, data, db, off, ctx) {
                // Canboat's `repetition` counter is reset to 0 at the
                // top of each loop iteration when `*variableFields == 0`
                // — so a forced count=0 iteration only labels its first
                // field. Drop `repeat_index` (but keep `repeat_set` for
                // JSON list-grouping) on later fields to match.
                d.repeat_set = set_number;
                d.repeat_index = if count_was_zero && !first_field_of_iter {
                    None
                } else {
                    Some(iter)
                };
                first_field_of_iter = false;
                sub_cursor = off + bits;
                // The record is still real when a value is omitted for
                // being explicitly empty, so this iteration counts as
                // productive and the walk continues to the next record.
                if !core::mem::take(&mut ctx.skip_field) {
                    out.push(d);
                }
                produced_any = true;
            } else if let Some(bl) = sf.bit_length {
                // Field couldn't decode but has a known size; advance
                // past it so subsequent fields in this iteration still
                // line up.
                sub_cursor = off + bl;
            }
        }
        // If this iteration produced nothing decodable, stop — we ran
        // off the end of the payload.
        if !produced_any {
            break;
        }
        iter_cursor = sub_cursor;
    }
    iter_cursor
}

/// Decode one field. Returns the `DecodedField` and the number of
/// payload bits it actually consumed (which differs from `bit_length`
/// for variable-length types like STRING_LAU and VARIABLE).
fn decode_one_field_at(
    f: &'static FieldInfo,
    info: &'static PgnInfo,
    data: &[u8],
    db: &PgnDatabase,
    bit_offset: u32,
    ctx: &mut DecodeContext,
) -> Option<(DecodedField, u32)> {
    let signed = f.signed.unwrap_or(false);
    let offset_k = f.offset.unwrap_or(0);

    // STRING_LAU figures out its own length from the data byte.
    if matches!(f.field_type, Some(FieldType::StringLau)) {
        let (value, bits_consumed) = decode_string_lau(data, bit_offset, f.encoding);
        return Some((
            DecodedField {
                info: f,
                value,
                bit_offset: Some(bit_offset),
                bit_length: Some(bits_consumed),
                repeat_index: None,
                repeat_set: 0,
                overrides: None,
            },
            bits_consumed,
        ));
    }

    // VARIABLE: dynamic field type — look up the target field's
    // metadata via (ctx.target_pgn, ctx.current_param_idx), then
    // recursively decode with that metadata at the current cursor.
    if matches!(f.field_type, Some(FieldType::Variable)) {
        return decode_variable(f, data, db, bit_offset, ctx);
    }

    // DYNAMIC_FIELD_VALUE has `BitLengthVariable: true` and no
    // explicit `BitLength` in canboat.json — its width comes from
    // the matching DYNAMIC_FIELD_LENGTH (or the resolved KEY's table
    // entry). Handle it before the `bit_length?` check below would
    // bail out.
    if matches!(f.field_type, Some(FieldType::DynamicFieldValue)) {
        // Capture unit / resolution / precision from the resolved key
        // entry *before* `decode_dynamic_field_value` drains the
        // context slots. The override is stashed alongside the
        // DecodedField so `f.unit()` etc. resolve through it before
        // falling back to the FieldInfo.
        let overrides = ctx.dynamic_field_type.as_ref().map(|v| {
            Box::new(FieldOverrides {
                unit: v.unit,
                resolution: v.resolution,
                precision: v.precision,
            })
        });
        let (val, consumed_bits) = decode_dynamic_field_value(data, bit_offset, db, ctx);
        return Some((
            DecodedField {
                info: f,
                value: val,
                bit_offset: Some(bit_offset),
                bit_length: Some(consumed_bits),
                repeat_index: None,
                repeat_set: 0,
                overrides,
            },
            consumed_bits,
        ));
    }

    // STRING_LZ / BINARY with `BitLengthVariable: true` and no
    // explicit `BitLength` — read to the payload end (canboat's
    // equivalent: `if (*bits == 0)` in `fieldPrintBinary` /
    // `printString`). Falls through to the normal decode path with a
    // zero bit_length so the decoders know to consume what's left.
    if matches!(
        f.field_type,
        Some(FieldType::StringLz) | Some(FieldType::Binary)
    ) && f.bit_length.is_none()
    {
        let payload_bits = (data.len() as u32).saturating_mul(8);
        let avail = payload_bits.saturating_sub(bit_offset);
        let avail = avail - (avail & 7); // round down to whole bytes
        let value = match f.field_type {
            Some(FieldType::StringLz) => decode_string_lz(data, bit_offset, avail, f.encoding),
            // A BINARY field with no width of its own takes one, in
            // *bits*, from the value of the field before it — canboat's
            // `*bits = g_previousFieldValue` (fieldPrintBinary, print.c),
            // which its own comment calls heuristic. Fusion's 130820
            // SiriusXM Presets sizes `Values` by the preceding `Count`,
            // as do AIS 129792 / 129795 / 129797.
            _ if ctx.previous_field_value > 0 && (ctx.previous_field_value as u32) <= avail => {
                decode_binary(data, bit_offset, ctx.previous_field_value as u32)
            }
            _ => decode_binary(data, bit_offset, avail),
        };
        return Some((
            DecodedField {
                info: f,
                value,
                bit_offset: Some(bit_offset),
                bit_length: Some(avail),
                repeat_index: None,
                repeat_set: 0,
                overrides: None,
            },
            avail,
        ));
    }

    let bit_length = f.bit_length?;

    // A fixed-width field the payload ends inside, or before, has no
    // value: the bits that arrived are not the number that was sent (a
    // 32-bit longitude cut to 24 bits reads as another longitude), so it
    // is left out, as canboat C does. Binary data and fixed strings are read as far as
    // they go, as Navico's 130821 sends only the text it has.
    let total = data.len() as u32 * 8;
    if is_cut_short(f, bit_offset, total) {
        ctx.skip_field = true;
        let avail = total.saturating_sub(bit_offset);
        return Some((
            DecodedField {
                info: f,
                value: FieldValue::NotAvailable,
                bit_offset: Some(bit_offset),
                bit_length: Some(avail),
                repeat_index: None,
                repeat_set: 0,
                overrides: None,
            },
            avail,
        ));
    }

    // The high bits of an earlier field's value: already joined into that
    // field, so they are not a value of their own.
    if f.continues.is_some() {
        ctx.skip_field = true;
    }

    // A field that a later one continues: read its own bits and the high
    // bits as one value, so its scaling, sentinels and lookup name all see
    // the whole of it. The decoders below read that value from a scratch
    // buffer; the field still occupies only its own bits here.
    let joined;
    let (data, at, width) = match join_continuation(f, data, bit_offset, bit_length) {
        Some((value, width)) => {
            joined = value.to_le_bytes();
            (&joined[..], 0, width)
        }
        None => (data, bit_offset, bit_length),
    };
    let value = decode_scalar(f, info, data, db, at, width, signed, offset_k, ctx);
    finish_scalar(f, value, bit_offset, bit_length, ctx)
}

/// True when the payload (`total` bits) ends inside, or before, the
/// fixed-width field `f` at `bit_offset`, or before the high bits that
/// continue it (a J1939 DTC's SPN). Binary data and fixed strings are
/// read as far as they go, so they are never cut short.
fn is_cut_short(f: &FieldInfo, bit_offset: u32, total: u32) -> bool {
    let Some(bit_length) = f.bit_length else {
        return false;
    };
    let whole = f.continuation.map_or(bit_length, |c| {
        bit_length.max(c.bit_offset.saturating_add(c.bit_length))
    });
    bit_offset.saturating_add(whole) > total
        && !matches!(
            f.field_type,
            Some(FieldType::Binary | FieldType::StringFix | FieldType::StringLz)
        )
}

/// The value of a field with a [`FieldInfo::continuation`]: its own
/// `bit_length` bits with the continuing bits above them, and the width of
/// the two together. `None` when the field has no continuation; a field
/// whose high bits lie beyond the payload is left out before this is
/// reached, as the C analyzer does.
fn join_continuation(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
) -> Option<(u64, u32)> {
    let c = f.continuation?;
    let width = bit_length + c.bit_length;
    // extract_bits reads what it can of a range that runs off the payload;
    // a partial part would join into a wrong value, so require both whole.
    let payload_bits = data.len() as u32 * 8;
    if width > 64
        || bit_offset + bit_length > payload_bits
        || bit_offset + c.bit_offset + c.bit_length > payload_bits
    {
        return None;
    }
    let low = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0)?;
    let high = extract_bits(
        data,
        (bit_offset + c.bit_offset) as usize,
        c.bit_length as usize,
        false,
        0,
    )?;
    Some((low.raw | (high.raw << bit_length), width))
}

#[allow(clippy::too_many_arguments)]
fn decode_scalar(
    f: &'static FieldInfo,
    info: &'static PgnInfo,
    data: &[u8],
    db: &PgnDatabase,
    bit_offset: u32,
    bit_length: u32,
    signed: bool,
    offset_k: i64,
    ctx: &mut DecodeContext,
) -> FieldValue {
    match f.field_type {
        Some(FieldType::Decimal) => decode_decimal(
            data,
            bit_offset,
            bit_length,
            trailing_zero_is_digit(f, info, data),
        ),
        Some(FieldType::Number) => decode_number(f, data, bit_offset, bit_length, signed, offset_k),
        Some(FieldType::Float) => decode_float(f, data, bit_offset, bit_length),
        Some(FieldType::Lookup) => decode_lookup(f, data, bit_offset, bit_length, db),
        Some(FieldType::IndirectLookup) => {
            decode_indirect_lookup(f, info, data, bit_offset, bit_length, db)
        }
        Some(FieldType::BitLookup) => decode_bitlookup(f, data, bit_offset, bit_length, db),
        Some(FieldType::Reserved) => {
            decode_reserved(data, bit_offset, bit_length, signed, offset_k, true)
        }
        Some(FieldType::Spare) => {
            decode_reserved(data, bit_offset, bit_length, signed, offset_k, false)
        }
        Some(FieldType::Binary) => decode_binary(data, bit_offset, bit_length),
        Some(FieldType::Mmsi) => decode_mmsi(f, data, bit_offset, bit_length),
        Some(FieldType::Pgn) => decode_pgn_field(data, bit_offset, bit_length, db),
        Some(FieldType::Date) => decode_date(f, data, bit_offset, bit_length),
        Some(FieldType::Time) | Some(FieldType::Duration) => {
            decode_time(f, data, bit_offset, bit_length, signed)
        }
        Some(FieldType::StringFix) => decode_string_fix(data, bit_offset, bit_length, f.encoding),
        Some(FieldType::StringLz) => decode_string_lz(data, bit_offset, bit_length, f.encoding),
        Some(FieldType::StringLau) => unreachable!("STRING_LAU handled above"),
        Some(FieldType::Variable) => unreachable!("VARIABLE handled above"),
        Some(FieldType::IsoName) => decode_iso_name(data, bit_offset, bit_length, db),
        Some(FieldType::DynamicFieldKey) => {
            decode_dynamic_field_key(f, data, db, bit_offset, bit_length, ctx)
        }
        Some(FieldType::DynamicFieldLength) => {
            decode_dynamic_field_length(f, data, bit_offset, bit_length, ctx)
        }
        Some(FieldType::DynamicFieldValue) => unreachable!("DYNAMIC_FIELD_VALUE handled above"),
        Some(FieldType::FieldIndex) => decode_number(f, data, bit_offset, bit_length, signed, 0),
        // A bus address: every value is an address (254 null, 255 global),
        // so the type declares no sentinels and this reads as a plain number.
        Some(FieldType::Address) => decode_number(f, data, bit_offset, bit_length, signed, 0),
        None => FieldValue::Unsupported {
            field_type: "<no field type>",
        },
    }
}

fn finish_scalar(
    f: &'static FieldInfo,
    value: FieldValue,
    bit_offset: u32,
    bit_length: u32,
    ctx: &mut DecodeContext,
) -> Option<(DecodedField, u32)> {
    // Update the running context based on what we just decoded so the
    // next field can interpret VARIABLE / FIELD_INDEX correctly.
    match &value {
        FieldValue::Pgn { value: p, .. } => ctx.target_pgn = Some(*p),
        FieldValue::Integer(n) if matches!(f.field_type, Some(FieldType::FieldIndex)) => {
            ctx.current_param_idx = Some(*n as u32);
        }
        _ => {}
    }
    // `g_previousFieldValue`, which the C sets inside
    // `extractNumberNotEmpty` — so it tracks the numeric fields, and a
    // following zero-width BINARY reads its bit count from it.
    if let FieldValue::Integer(n) = &value
        && *n >= 0
    {
        ctx.previous_field_value = *n as u64;
    }
    // canboat C also picks up dynamic field lengths by FIELD NAME
    // (`analyzer/analyzer.c::fillGlobalsBasedOnFieldName`): any field
    // literally named `Length` updates `g_length`, which the next
    // DYNAMIC_FIELD_VALUE then consumes. Several PGNs use a regular
    // NUMBER field for this rather than the explicit
    // `DYNAMIC_FIELD_LENGTH` type (e.g. Simnet Parameter Set 130846).
    if f.is_dynamic_length_marker {
        let raw_len = match &value {
            FieldValue::Integer(n) if *n >= 0 => Some(*n),
            FieldValue::Number(n) if *n >= 0.0 => Some(*n as i64),
            _ => None,
        };
        if let Some(n) = raw_len {
            ctx.dynamic_length_bytes = Some(n - i64::from(f.dynamic_field_length_overhead));
        }
    }

    Some((
        DecodedField {
            info: f,
            value,
            bit_offset: Some(bit_offset),
            bit_length: Some(bit_length),
            repeat_index: None,
            repeat_set: 0,
            overrides: None,
        },
        bit_length,
    ))
}

/// Resolve a VARIABLE field by looking up the target field's metadata
/// in the database, then decoding with that metadata at the current
/// cursor.
///
/// Used by PGN 126208 group functions where a `Parameter` /
/// `FIELD_INDEX` field picks one of the target PGN's fields, and the
/// next VARIABLE field carries that field's value in its native shape.
/// True for the four proprietary PGN ranges (`IS_PGN_PROPRIETARY`,
/// common/common.h). Shared with the encoder's target-variant
/// matching, which mirrors [`match_pgn_by_parameters`].
pub(crate) fn is_pgn_proprietary(n: u32) -> bool {
    (0xEF00..=0xEFFF).contains(&n)
        || (0xFF00..=0xFFFF).contains(&n)
        || (0x1_EF00..=0x1_EFFF).contains(&n)
        || (0x1_FF00..=0x1_FFFF).contains(&n)
}

/// Whether a field with this `condition` is in the message, given the
/// PGN that the message's PGN field names. The one condition the schema
/// has, `PGNIsProprietary`, is the Manufacturer Code / Industry Code
/// header of a 126208 Read or Write Fields (and their replies): there
/// only when the commanded PGN is proprietary, as the C reads it
/// (`field->proprietary`, analyzer.c). Shared with the encoder.
pub(crate) fn field_present(condition: Option<&str>, target_pgn: Option<u32>) -> bool {
    match condition {
        None => true,
        Some("PGNIsProprietary") => target_pgn.is_some_and(is_pgn_proprietary),
        Some(_) => false,
    }
}

/// Pick the definition of `pgn_id` that a PGN 126208 parameter list
/// describes. Port of `getMatchingPgnByParameters` (analyzer/pgn.c).
///
/// `params` starts at the parameter-count byte: `[count, index, value…,
/// index, value…]`, where each `index` is a 1-based field number of the
/// target PGN and the value's width comes from that field. Walking the
/// list with a candidate's own field sizes is what makes it a test: a
/// definition whose `Match` fields all agree with the values present is
/// the answer, and a definition that disagrees (or that has no such
/// field at all) steps out.
///
/// Returns `None` when nothing matches — for a proprietary PGN whose
/// parameters name no variant, such as a Raymarine request whose
/// proprietary ID none of Raymarine's 126720 variants carries, that is
/// the normal outcome, and the caller uses the catch-all.
fn match_pgn_by_parameters(
    db: &PgnDatabase,
    pgn_id: u32,
    params: &[u8],
) -> Option<&'static PgnInfo> {
    let first = db.specific_variants(pgn_id).next()?;

    // A proprietary PGN can only be narrowed by Manufacturer (field 1)
    // and Industry Code (field 3); without both there is nothing to go
    // on and the C bails out rather than guessing.
    if is_pgn_proprietary(pgn_id)
        && (params.len() < 6 || params[0] < 2 || params[1] != 0x01 || params[4] != 3)
    {
        return None;
    }

    // `hasMatchFields` is set per *definition* (fieldtype.c), and the C
    // tests it on the first one only -- so a PGN whose leading
    // definition needs no matching is answered by that definition
    // outright.
    if !first.fields.iter().any(|fi| fi.match_value.is_some()) {
        return Some(first);
    }

    let nparams = *params.first()? as usize;
    'variant: for cand in db.specific_variants(pgn_id) {
        let mut d = 1usize;
        // Exactly `nparams` pairs — walking to the end of the data
        // instead would read trailing bytes as a bogus extra parameter.
        for _ in 0..nparams {
            if d >= params.len() {
                break; // truncated list: what was there matched
            }
            let index = params[d] as usize;
            d += 1;
            if index == 0 || index > cand.fields.len() {
                continue 'variant;
            }
            let field = &cand.fields[index - 1];
            let bits = field.bit_length.unwrap_or(0) as usize;
            if let Some(want) = field.match_value {
                let Some(ex) = extract_bits(params, d * 8, bits, field.signed.unwrap_or(false), 0)
                else {
                    continue 'variant;
                };
                if ex.value != want {
                    continue 'variant;
                }
            }
            d += bits.div_ceil(8);
        }
        return Some(cand);
    }
    None
}

fn decode_variable(
    f: &'static FieldInfo,
    data: &[u8],
    db: &PgnDatabase,
    bit_offset: u32,
    ctx: &mut DecodeContext,
) -> Option<(DecodedField, u32)> {
    let target_pgn = ctx.target_pgn?;
    let target_idx = ctx.current_param_idx?;
    // Which definition of the target PGN does this parameter address?
    //
    // canboat answers this in `fieldPrintVariable` (analyzer.c): first try to
    // resolve a *variant* from the parameter list itself -- a request for
    // 130833 that sets Manufacturer=Furuno picks
    // furunoShipParametersAndAntennaPosition, and its parameter 4 is a real
    // typed field, as does an Airmar request for 126720 naming proprietary
    // ID 35 (Simulate Mode). Only when that fails -- no variant agrees with
    // the parameters, as for a Raymarine request whose proprietary ID none of
    // Raymarine's 126720 variants carries -- borrow the *catch-all*
    // definition, whose leading fields every variant shares.
    //
    // It has to be the catch-all and not merely the first specific
    // definition: 126720's is somebody's variant whose Manufacturer Code is
    // a `Match` field, so borrowing it would make every request from another
    // manufacturer decode against the wrong layout.
    //
    // Resolved once per record and cached, as the C caches `g_refPgn`.
    let (target_info, used_catch_all) = match ctx.resolved_target {
        Some(r) => r,
        None => {
            // The C hands `getMatchingPgnByParameters` the message from two
            // bytes back: [parameter count][field index][value...]. At the
            // first VARIABLE field the cursor sits on the value, so -1 is this
            // parameter's index byte and -2 the count.
            let params = (bit_offset as usize / 8)
                .checked_sub(2)
                .and_then(|s| data.get(s..))
                .unwrap_or(&[]);
            let r = match match_pgn_by_parameters(db, target_pgn, params) {
                Some(p) => (p, false),
                None => (
                    db.fallback_pgn(target_pgn)
                        .or_else(|| db.first_pgn(target_pgn))?,
                    true,
                ),
            };
            ctx.resolved_target = Some(r);
            r
        }
    };
    let target_field = target_info
        .fields
        .iter()
        .find(|tf| (tf.order as u32) == target_idx)?;
    // The catch-all's trailing `Data` field is variable-length with nothing to
    // size it, so the value is the rest of the message -- for a request or
    // command that reads as "the field starts with these bytes". Only when we
    // fell back: a *resolved* PGN's variable-length fields (126998's
    // Configuration Information strings) decode properly through the normal
    // path.
    if used_catch_all
        && (target_field.bit_length.unwrap_or(0) == 0
            || target_field.bit_length_variable == Some(true))
    {
        let start = bit_offset as usize;
        let total = data.len() * 8;
        if start >= total {
            return None;
        }
        let bits = (total - start) as u32;
        let value = decode_binary(data, bit_offset, bits);
        return Some((
            DecodedField {
                info: f,
                value,
                bit_offset: Some(bit_offset),
                bit_length: Some(bits),
                repeat_index: None,
                repeat_set: 0,
                overrides: None,
            },
            bits,
        ));
    }
    // Recurse with the target field's metadata at the current cursor.
    // The outer field's name (e.g. "Value", "Selection Value") wraps
    // the decoded result so the JSON keeps the right field label.
    let mut sub_ctx = DecodeContext::default();
    let (sub, bits) = decode_one_field_at(
        target_field,
        target_info,
        data,
        db,
        bit_offset,
        &mut sub_ctx,
    )?;
    // A target the walk leaves out (one the payload ends inside) leaves
    // out the VARIABLE field that carries it, as canboat C does.
    ctx.skip_field |= sub_ctx.skip_field;
    // canboat rounds the VARIABLE field's consumption UP to whole
    // bytes — `*bits = (*bits + 7) & ~0x07` in `fieldPrintVariable`.
    // Without this, Set2 in PGN 126208 Read Fields lands 5 bits early
    // and reads the next Parameter's bits from the wrong nibble.
    let bits_byte_aligned = bits.div_ceil(8) * 8;
    // VARIABLE override: take the target field's unit/resolution/precision
    // verbatim. The outer field's id/name (e.g. "Value", "Selection Value")
    // is still what JSON should render, so we keep `info: f`.
    let overrides = Some(Box::new(FieldOverrides {
        unit: target_field.unit,
        resolution: target_field.resolution,
        precision: target_field.precision,
    }));
    Some((
        DecodedField {
            info: f,
            // For VARIABLE fields, the `-debug` formatter wants the
            // diagnostic to reflect the sub-field's actual width when
            // it has one (so a 3-bit LOOKUP target shows
            // `bits = "010"`). When the sub-field is itself variable-
            // length (e.g. STRING_LAU), fall back to the consumed
            // byte-aligned size so we still emit the bytes annotation.
            value: sub.value,
            bit_offset: Some(bit_offset),
            bit_length: target_field.bit_length.or(Some(bits_byte_aligned)),
            repeat_index: None,
            repeat_set: 0,
            overrides,
        },
        bits_byte_aligned,
    ))
}

fn decode_number(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    signed: bool,
    _offset_k: i64,
) -> FieldValue {
    // canboat.json's `Offset` is in DISPLAY units (e.g. PEUKERT_EXPONENT
    // Offset=1 means "add 1.0 to the displayed exponent"), NOT a raw
    // J1939 Excess-K shift on the integer extraction. canboat C also
    // forces unsigned extraction when `Offset != 0` regardless of the
    // field's nominal Signed flag — see extractNumber's
    // `if (hasSign && field->offset)` path. Replicate both here.
    let display_offset = f.offset.map(|o| o as f64).unwrap_or(0.0);
    let has_display_offset = f.offset.unwrap_or(0) != 0;
    let effective_signed = if has_display_offset { false } else { signed };
    let Some(ex) = extract_bits(
        data,
        bit_offset as usize,
        bit_length as usize,
        effective_signed,
        0,
    ) else {
        return FieldValue::NotAvailable;
    };
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    // No explicit hints in the schema: fall back to the range-derived
    // check. The C resolves `reservedCount` for every number field from
    // `rangeMax` against the raw bit-width maximum
    // (`extractNumberNotEmpty`), whether or not per-field hints exist,
    // so a field carrying only a range — every J1939 definition — must
    // get the same treatment here.
    //
    // Unsigned only: for a signed field the all-ones pattern is -1, a
    // legitimate reading the C prints as such, and the comparison below
    // is against the *unsigned* raw.
    if !effective_signed && let Some(sent) = range_max_sentinel(f, ex, bit_length) {
        return sent;
    }
    // Signed only: an unsigned field starts at its offset, its RangeMin.
    if effective_signed && let Some(sent) = range_min_out_of_range(f, ex) {
        return sent;
    }
    let resolution = f.resolution.unwrap_or(1.0);
    let unit = f.unit;
    if resolution == 1.0
        && unit.is_none()
        && f.physical_quantity.is_none()
        && f.unit_offset == 0.0
        && display_offset == 0.0
    {
        FieldValue::Integer(ex.value)
    } else {
        FieldValue::Number(ex.value as f64 * resolution + display_offset + f.unit_offset)
    }
}

fn decode_float(f: &FieldInfo, data: &[u8], bit_offset: u32, bit_length: u32) -> FieldValue {
    if bit_length != 32 {
        return FieldValue::Unsupported {
            field_type: "FLOAT (non-32-bit)",
        };
    }
    let Some(ex) = extract_bits(data, bit_offset as usize, 32, false, 0) else {
        return FieldValue::NotAvailable;
    };
    let bits = ex.value as u32;
    // The wire value is in the database's unit; the schema's resolution
    // and unit offset present it in this schema's unit (rad -> deg, …).
    let v = f32::from_bits(bits) as f64;
    // NMEA 2000 sends a FLOAT that is not available as NaN.
    if v.is_nan() {
        return FieldValue::NotAvailable;
    }
    FieldValue::Float(match f.resolution {
        Some(r) if r != 0.0 => v * r + f.unit_offset,
        _ => v,
    })
}

fn decode_lookup(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    db: &PgnDatabase,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0) else {
        return FieldValue::NotAvailable;
    };
    // Name wins: when the enumeration explicitly maps the raw value,
    // emit the name even if the same raw value would have been a
    // sentinel hint on the field. This mirrors the canboat 7.1.0
    // schema-2.5.0 contract — "an enumeration name always wins, so a
    // sentinel position the lookup names is not emitted" (PR #704).
    let raw = ex.raw;
    let name = f
        .lookup_enumeration
        .and_then(|n| db.lookup(n))
        .and_then(|t| t.get(raw))
        .map(|v| v.name);
    if name.is_some() {
        return FieldValue::Lookup { value: raw, name };
    }
    // No name resolved — fall through to the per-field sentinel hints
    // (schema 2.5.0 carries them on ~35 % of LOOKUP fields). For the
    // remaining "all values valid" tables (MMSI-style identifier
    // lookups) the hints are all None and we emit the raw value.
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    // Still nothing, and the table does not name this value.
    unnamed_lookup_value(ex, bit_length)
}

/// INDIRECT_LOOKUP: resolve `(value1, value2)` where `value1` is
/// pulled from another field within the same PGN, identified by
/// `LookupIndirectEnumerationFieldOrder`.
/// Are two field orders inside the same repeating set?
fn in_same_repeating_set(info: &PgnInfo, a: u32, b: u32) -> bool {
    [
        (
            info.repeating_field_set1_start_field,
            info.repeating_field_set1_size,
        ),
        (
            info.repeating_field_set2_start_field,
            info.repeating_field_set2_size,
        ),
    ]
    .iter()
    .any(|(start, size)| match (start, size) {
        (Some(s), Some(n)) if *n > 0 => (*s..*s + *n).contains(&a) && (*s..*s + *n).contains(&b),
        _ => false,
    })
}

/// Bit offset of an `INDIRECT_LOOKUP`'s key field, given where the *value*
/// field actually sits (`self_bit`).
///
/// `FieldInfo::bit_offset` is a static offset from the start of the message,
/// so it only locates a field's FIRST occurrence. That is right when the key
/// lives outside the value's repeating set - including the forward reference
/// in PGN 60928, where `deviceFunction` (order 5) is keyed on `deviceClass`
/// (order 7) - because such a key occurs exactly once.
///
/// When key and value share a repeating set it is wrong: every record would
/// resolve against the first record's key. There the distance between the two
/// is fixed, so the key is located relative to where the value actually is.
fn indirect_key_offset(
    value_field: &FieldInfo,
    key_field: &FieldInfo,
    info: &PgnInfo,
    self_bit: u32,
) -> Option<usize> {
    let key_static = key_field.bit_offset?;
    if !in_same_repeating_set(info, value_field.order as u32, key_field.order as u32) {
        return Some(key_static as usize);
    }
    let value_static = value_field.bit_offset?;
    let delta = value_static.checked_sub(key_static)?;
    Some(self_bit.checked_sub(delta)? as usize)
}

fn decode_indirect_lookup(
    f: &FieldInfo,
    info: &PgnInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    db: &PgnDatabase,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0) else {
        return FieldValue::NotAvailable;
    };
    let raw = ex.raw;
    let name = (|| -> Option<&'static str> {
        let table_name = f.lookup_indirect_enumeration?;
        let val1_order = f.lookup_indirect_enumeration_field_order?;
        let val1_field = info.fields.iter().find(|x| x.order == val1_order)?;
        let val1_len = val1_field.bit_length?;
        let val1_off = indirect_key_offset(f, val1_field, info, bit_offset)?;
        let val1 = extract_bits(data, val1_off, val1_len as usize, false, 0)?;
        db.indirect_lookup(table_name, val1.raw, raw)
    })();
    if name.is_some() {
        return FieldValue::Lookup { value: raw, name };
    }
    // Name didn't resolve — try the per-field sentinel hints. Schema
    // 2.5.0 declares them on both INDIRECT_LOOKUP fields in the
    // database (PGN 60928 Device Function / Class).
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    FieldValue::Lookup {
        value: raw,
        name: None,
    }
}

fn decode_bitlookup(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    db: &PgnDatabase,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0) else {
        return FieldValue::NotAvailable;
    };
    let raw = ex.value as u64;
    // Keep the BitField even when no bits are set — formatters
    // handle the empty case themselves: JSON drops it, text emits
    // "None" (matches canboat).
    //
    // Walk the *bit positions*, not the enumeration's entries: canboat
    // loops `bit < *bits` and emits every set bit, naming it if the
    // table has an entry and leaving the name null if not
    // (`fieldPrintBitLookup`, print.c). Iterating the table instead
    // made a set bit that nothing names invisible — PGN 65305's `Mode`
    // sets bit 1, which SIMNET_AP_STATUS does not name, and it went
    // missing from every autopilot status record.
    let mut bits = Vec::new();
    let table = f.lookup_bit_enumeration.and_then(|n| db.bit_lookup(n));
    for bit in 0..bit_length.min(64) {
        if raw & (1u64 << bit) != 0 {
            bits.push((
                1u64 << bit,
                table.and_then(|t| t.get(bit as u8)).map(|v| v.name),
            ));
        }
    }
    FieldValue::BitField { value: raw, bits }
}

fn decode_reserved(
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    signed: bool,
    offset_k: i64,
    is_reserved: bool,
) -> FieldValue {
    let Some(ex) = extract_bits(
        data,
        bit_offset as usize,
        bit_length as usize,
        signed,
        offset_k,
    ) else {
        return FieldValue::NotAvailable;
    };
    let raw = ex.value as u64;
    // canboat skips Reserved fields whose value is all-ones (the
    // default "this is unused" state). Surface that here too — but
    // formatters do the actual omission so the `-debug` byte/bit
    // diagnostic survives in callers that care.
    if is_reserved && ex.value == ex.max {
        return FieldValue::Reserved {
            value: raw,
            bytes: Vec::new(),
            bit_length,
        };
    }
    // A RESERVED or SPARE field that does need printing is handed
    // straight to `fieldPrintBinary` by the C (`fieldPrintReserved` /
    // `fieldPrintSpare`, print.c), so every bit stays where it sat:
    // the first byte is masked to the field's width and shifted back
    // into position, and later bytes come whole off the message.
    //
    // Packing the extracted value LSB-first instead moved the bits down
    // to bit 0 — PGN 130824's 2-bit Reserved at bit 11 printed `02`
    // where canboat prints `10`, and the same shift showed up on every
    // proprietary PGN's Reserved field.
    let bytes = match decode_binary(data, bit_offset, bit_length) {
        FieldValue::Binary(b) => b,
        _ => Vec::new(),
    };
    if is_reserved {
        FieldValue::Reserved {
            value: raw,
            bytes,
            bit_length,
        }
    } else {
        FieldValue::Spare {
            value: raw,
            bytes,
            bit_length,
        }
    }
}

/// ISO_NAME: 64-bit packed identifier. The same 8 bytes also form a
/// valid PGN 60928 (ISO Address Claim) payload, so the structured form
/// is built by re-running the decoder against PGN 60928's field list
/// on those 8 bytes — matching `fieldPrintName` in `analyzer/print.c`.
fn decode_iso_name(data: &[u8], bit_offset: u32, bit_length: u32, db: &PgnDatabase) -> FieldValue {
    if bit_length != 64 || (bit_offset & 7) != 0 {
        return FieldValue::Unsupported {
            field_type: "ISO_NAME (unaligned or non-64-bit)",
        };
    }
    let byte_off = (bit_offset / 8) as usize;
    if byte_off + 8 > data.len() {
        return FieldValue::NotAvailable;
    }
    let mut value: u64 = 0;
    for i in 0..8 {
        value |= (data[byte_off + i] as u64) << (i * 8);
    }
    // An ISO NAME reserves its top *two* values rather than going
    // through the usual per-field sentinel machinery, which is
    // suppressed at 64 bits anyway (QUIRKS Q18): `fieldPrintName`
    // (print.c) hands anything above `maxValue - 2` to `printEmpty`.
    // Expanding one of those into subfields would invent a device —
    // an all-ones NAME reads as Device Instance 31, "Arbitrary address
    // capable: Yes" and so on, none of which is on the wire.
    match value {
        u64::MAX => return FieldValue::NotAvailable,
        v if v == u64::MAX - 1 => return FieldValue::OutOfRange { value },
        _ => {}
    }
    let sub = &data[byte_off..byte_off + 8];
    let subfields = match db.first_pgn(60928) {
        Some(pgn) => decode_fields(pgn, sub, db).map(|x| x.0).unwrap_or_default(),
        None => Vec::new(),
    };
    FieldValue::IsoName { value, subfields }
}

/// DECIMAL: each group of 8 bits is one decimal *pair*, printed as two
/// digits — canboat's `fieldPrintDecimal` (print.c). A DSC address of
/// `33 14 00 5F 1E` reads 5120009530, not the 40-bit integer those
/// bytes spell, and that is MMSI 512000953 with the 0 that pads it.
///
/// A byte that is not a valid pair (>= 100) is dropped, as the C drops
/// it. All bits set is "not available": that is the universal canboat
/// convention, and reading it as digits would otherwise emit nothing at
/// all, which in the C takes the whole record down with it.
fn decode_decimal(data: &[u8], bit_offset: u32, bit_length: u32, keep_last: bool) -> FieldValue {
    let start_byte = (bit_offset / 8) as usize;
    if start_byte >= data.len() {
        return FieldValue::NotAvailable;
    }
    let avail = (data.len() as u32 * 8).saturating_sub(bit_offset);
    // A field the packet ends inside is not available: the digits that are
    // present are not the number (#962).
    if bit_length > avail {
        return FieldValue::NotAvailable;
    }
    let bits = bit_length;
    let nbytes = bits.div_ceil(8) as usize;
    let end = (start_byte + nbytes).min(data.len());
    if data[start_byte..end].iter().all(|&b| b == 0xff) {
        return FieldValue::NotAvailable;
    }

    let mut out = String::with_capacity(nbytes * 2);
    let mut value: u32 = 0;
    let mut magnitude: u32 = 1;
    let mut mask: u8 = 1 << (bit_offset % 8);
    let mut idx = start_byte;
    for bit in 0..bits {
        let Some(&byte) = data.get(idx) else { break };
        if byte & mask != 0 {
            value |= magnitude;
        }
        if mask == 128 {
            mask = 1;
            idx += 1;
        } else {
            mask <<= 1;
        }
        magnitude <<= 1;
        if bit % 8 == 7 {
            // A byte that is not a digit pair (0..99) makes the whole number
            // unknown: dropping just that byte would give a different,
            // valid-looking number (#962).
            if value >= 100 {
                return FieldValue::NotAvailable;
            }
            out.push((b'0' + (value / 10) as u8) as char);
            out.push((b'0' + (value % 10) as u8) as char);
            value = 0;
            magnitude = 1;
        }
    }
    if out.is_empty() {
        return FieldValue::NotAvailable;
    }
    // A value with an odd number of digits is sent with a 0 added at the
    // end: a DSC call sends a 9-digit MMSI as ten digits (ITU-R M.585).
    // Drop it, so the MMSI reads as it does in an MMSI field -- unless
    // `keep_last`: the ten digits of a geographical area all count.
    if out.ends_with('0') && !keep_last {
        out.pop();
    }
    FieldValue::Decimal(out)
}

/// Whether the field `f.trailing_zero_is_digit` names holds its value, so
/// a DECIMAL's last digit is a digit, not padding. That field sits at a
/// fixed position (keel R44), so its schema bit offset is where it is.
fn trailing_zero_is_digit(f: &FieldInfo, info: &PgnInfo, data: &[u8]) -> bool {
    (|| {
        let (order, value) = f.trailing_zero_is_digit?;
        let key = info.fields.iter().find(|x| x.order == order)?;
        let raw = extract_bits(
            data,
            key.bit_offset? as usize,
            key.bit_length? as usize,
            false,
            0,
        )?
        .raw;
        Some(raw as i64 == value)
    })()
    .unwrap_or(false)
}

fn decode_binary(data: &[u8], bit_offset: u32, bit_length: u32) -> FieldValue {
    let bit_offset = bit_offset as usize;
    let bit_length = bit_length as usize;
    // Whole-byte aligned: take a clean slice. Fallback PGNs like the
    // proprietary catch-alls declare BINARY widths well past the
    // actual payload (e.g. 1768 bits for `Data` in PGN 126720) —
    // canboat just renders whatever bytes are present, so clamp to
    // the available range rather than emitting NotAvailable.
    if bit_offset & 7 == 0 && bit_length & 7 == 0 {
        let start = bit_offset / 8;
        if start >= data.len() {
            return FieldValue::NotAvailable;
        }
        let declared_end = start + bit_length / 8;
        let end = declared_end.min(data.len());
        return FieldValue::Binary(data[start..end].to_vec());
    }
    // Not byte-aligned. This is NOT a clean bit-extraction, and must not
    // become one: `fieldPrintBinary` masks the *first* byte to the field's
    // width but then shifts it back to where it sat in the byte, and takes
    // every later byte whole. So PGN 130829's two 4-bit nibbles render as
    // "0F" (low) and "F0" (high) — the high nibble keeps its position rather
    // than being normalised down. Packing LSB-first instead reported both as
    // "0F", losing which nibble the bits came from.
    let start_byte = bit_offset / 8;
    let start_bit = bit_offset % 8;
    // canboat clamps the width to what the payload actually holds.
    let avail = data.len().saturating_mul(8).saturating_sub(bit_offset);
    let bit_length = bit_length.min(avail);
    if bit_length == 0 {
        return FieldValue::NotAvailable;
    }
    let nbytes = bit_length.div_ceil(8);
    let mut out = Vec::with_capacity(nbytes);
    let mut remaining = bit_length as isize;
    for i in 0..nbytes {
        let Some(&raw) = data.get(start_byte + i) else {
            break;
        };
        let mut byte = raw;
        if i == 0 && start_bit != 0 {
            byte >>= start_bit;
            if (remaining as usize) + start_bit < 8 {
                byte &= (1u8 << remaining) - 1;
            }
            byte <<= start_bit;
            remaining -= (8 - start_bit) as isize;
        } else {
            if remaining < 8 {
                byte &= (1u8 << remaining) - 1;
            }
            remaining -= 8;
        }
        out.push(byte);
    }
    FieldValue::Binary(out)
}

fn decode_mmsi(f: &FieldInfo, data: &[u8], bit_offset: u32, bit_length: u32) -> FieldValue {
    if bit_length != 32 {
        return FieldValue::Unsupported {
            field_type: "MMSI (non-32-bit)",
        };
    }
    let Some(ex) = extract_bits(data, bit_offset as usize, 32, false, 0) else {
        return FieldValue::NotAvailable;
    };
    // The MMSI FieldType declares `Sentinels: None`, so the schema
    // carries no per-field hints and `sentinel_field_value` finds
    // nothing. That is not the whole rule: an MMSI field's RangeMax is
    // 999999999, well inside 32 bits, and the C reserves its top three
    // values on that basis alone (`fieldPrintMMSI` goes through
    // `extractNumberNotEmpty`). PGN 130842's `Mothership User ID` reads
    // 0xFFFFFFFF whenever the Class B unit has no mothership, and
    // canboat omits it rather than printing 4294967295.
    if let Some(sent) = range_max_sentinel(f, ex, 32) {
        return sent;
    }
    // No station holds MMSI 0 -- its MID, 000, is not assigned -- and
    // devices send 0 for "none": every 129810 Mothership User ID from a
    // Class B unit without one, in all the captures. Not available, like
    // the reserved top values.
    if ex.value == 0 {
        return FieldValue::NotAvailable;
    }
    FieldValue::Mmsi(ex.value as u32)
}

fn decode_pgn_field(data: &[u8], bit_offset: u32, bit_length: u32, db: &PgnDatabase) -> FieldValue {
    if bit_length != 24 {
        return FieldValue::Unsupported {
            field_type: "PGN (non-24-bit)",
        };
    }
    let Some(ex) = extract_bits(data, bit_offset as usize, 24, false, 0) else {
        return FieldValue::NotAvailable;
    };
    // The PGN as the sender wrote it, as canboat C prints it. A PDU1 PGN
    // has its destination in the low byte of the CAN ID, not here, so a
    // nonzero low byte is what was sent and is kept rather than hidden.
    let pgn = ex.value as u32;
    // canboat only emits a name for the PGN field when there's
    // unambiguously one variant *without* `Match` constraints — that
    // is, the PGN number alone is enough to identify the message. PGN
    // 130820 (42 manufacturer variants, all match-gated) and PGN 65410
    // (one Airmar-only variant gated on Manufacturer Code) both fall
    // back to "value only" because we can't tell which variant applies
    // without actually decoding payload data.
    let variants: Vec<&'static PgnInfo> = db.pgn_variants(pgn).collect();
    let description =
        if variants.len() == 1 && !variants[0].fields.iter().any(|f| f.match_value.is_some()) {
            Some(variants[0].description)
        } else {
            None
        };
    FieldValue::Pgn {
        value: pgn,
        description,
    }
}

fn decode_date(f: &FieldInfo, data: &[u8], bit_offset: u32, bit_length: u32) -> FieldValue {
    if bit_length != 16 {
        return FieldValue::Unsupported {
            field_type: "DATE (non-16-bit)",
        };
    }
    let Some(ex) = extract_bits(data, bit_offset as usize, 16, false, 0) else {
        return FieldValue::NotAvailable;
    };
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    FieldValue::Date(ex.value as u16)
}

fn decode_time(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    signed: bool,
) -> FieldValue {
    let Some(ex) = extract_bits(
        data,
        bit_offset as usize,
        bit_length as usize,
        signed,
        f.offset.unwrap_or(0),
    ) else {
        return FieldValue::NotAvailable;
    };
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    let resolution = f.resolution.unwrap_or(1.0);
    FieldValue::Time {
        raw: ex.value,
        seconds: ex.value as f64 * resolution,
    }
}

fn decode_string_fix(
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    encoding: Option<&str>,
) -> FieldValue {
    let bo = bit_offset as usize;
    let bl = bit_length as usize;
    if bo & 7 != 0 || bl & 7 != 0 {
        return FieldValue::Unsupported {
            field_type: "STRING_FIX (unaligned)",
        };
    }
    let start = bo / 8;
    if start >= data.len() {
        return FieldValue::NotAvailable;
    }
    // Cap to what is actually in the message rather than dropping the
    // field — `len = CB_MIN(len, dataLen)` in `fieldPrintStringFix`
    // (print.c). Navico's 130821 ASCII Data declares a 230-byte
    // Message and sends however much text it has, so the declared
    // width is a maximum, not a promise.
    let end = (start + bl / 8).min(data.len());
    // Canboat's `printString` first finds an embedded NUL and shortens
    // the string at that point (matches the C-string convention some
    // devices use to terminate inside a fixed-width buffer — e.g. a
    // Mastervolt Product Information field that has two records
    // separated by NULs), then trims the trailing padding run. Apply both passes here so STRING_FIX renders the leading
    // C-string portion only.
    let raw = &data[start..end];
    let mut len = raw.iter().position(|&b| b == 0).unwrap_or(raw.len());
    while len > 0 && is_string_padding(raw[len - 1]) {
        len -= 1;
    }
    if len == 0 {
        return FieldValue::NotAvailable;
    }
    let s = decode_text(&raw[..len], encoding);
    FieldValue::String(s)
}

/// STRING_LAU — length + encoding + payload, where the first byte is the
/// total size of the field (`len` including the header), the second byte
/// is an encoding control (`0` = UTF-16LE, `1` = ASCII / UTF-8), and the
/// remaining `len - 2` bytes are the payload.
///
/// Returns the decoded value plus the number of bits this field
/// consumed — variable, so callers must use this to advance the cursor.
fn decode_string_lau(data: &[u8], bit_offset: u32, charset: Option<&str>) -> (FieldValue, u32) {
    let bo = bit_offset as usize;
    if bo & 7 != 0 {
        return (
            FieldValue::Unsupported {
                field_type: "STRING_LAU (unaligned)",
            },
            8,
        );
    }
    let start = bo / 8;
    if start + 2 > data.len() {
        return (FieldValue::NotAvailable, 16);
    }
    let total_len = data[start] as usize;
    let encoding = data[start + 1];
    if total_len < 2 {
        return (FieldValue::NotAvailable, (total_len.max(2) * 8) as u32);
    }
    let body_len = total_len - 2;
    let body_end = (start + 2 + body_len).min(data.len());
    let body = &data[start + 2..body_end];

    let bits_consumed = (total_len * 8) as u32;
    let s = match encoding {
        0 => {
            // UTF-16LE: pairs of bytes are LE u16 code units.
            let mut code_units = Vec::with_capacity(body.len() / 2);
            let mut i = 0;
            while i + 1 < body.len() {
                code_units.push(u16::from_le_bytes([body[i], body[i + 1]]));
                i += 2;
            }
            String::from_utf16_lossy(&code_units)
        }
        _ => {
            // 1 = ASCII / UTF-8 (canboat doesn't differentiate). An
            // encoding byte of 0xff marks an *unset* field: the length
            // byte is present but the encoding and content are 0xff
            // filler (seen on the H5000 pilot in PGN 126998). Trim the
            // trailing 0xff / NUL / '@' / space run off the raw bytes
            // *before* decoding, so an all-filler body collapses to an
            // empty (omitted) field instead of a run of U+FFFD
            // replacement chars — canboat's printString trims the same
            // bytes, and its C analyzer would otherwise abort the whole
            // PGN on "Unhandled string type 255".
            let end = body
                .iter()
                .rposition(|&b| !is_string_padding(b))
                .map_or(0, |i| i + 1);
            decode_text(&body[..end], charset)
        }
    };
    // Canboat's `printString` trims trailing 0xff / NUL / '@' / spaces
    // *after* the UTF-16→UTF-8 conversion. If nothing's left, the field
    // is rendered as Unknown via `printEmpty`. Match that — and don't
    // trim raw UTF-16 bytes (the trailing NUL of a single ASCII glyph
    // would lose the char).
    let trimmed = trim_string_padding(&s);
    if trimmed.is_empty() {
        return (FieldValue::NotAvailable, bits_consumed);
    }
    (FieldValue::String(trimmed.to_string()), bits_consumed)
}

/// Decode a run of 8-bit string bytes into text.
///
/// NMEA 2000 leaves the meaning of a byte >= 0x80 undefined in an 8-bit string
/// field, and devices disagree. Captured on one bus: a Fusion sends UTF-8
/// (`c5 ab` = U+016B in `samples/fusion-126998-utf8.raw`) while a B&G sends
/// Latin-1 (`e6` = 'æ' in `samples/bandg-129285-latin1.raw`) — in the same
/// field type, under the same STRING_LAU control byte. So the encoding is a
/// property of neither the field type nor the control byte and has to be
/// decided from the bytes: valid UTF-8 is taken as UTF-8, anything else as
/// Latin-1, which maps every byte to a codepoint and so cannot fail.
///
/// Note this never yields U+FFFD, and never loses a byte value: a consumer
/// that knows better can recover the original bytes from the Latin-1 branch.
/// See canboat#864.
/// Read an 8-bit string field.
///
/// UTF-8 wins when the bytes are well-formed; otherwise they are read in the
/// field's declared `encoding:`, defaulting to Latin-1 (#864 / #866). The
/// UTF-8 attempt runs first even for a field that declares a charset, so a
/// device that starts sending UTF-8 — RDS2 does — keeps decoding correctly
/// with no database change.
///
/// Mirrors `decode_text` in keel/src/decode.rs; the EBU Latin table below is
/// generated from keel/src/charset.rs, which cites its source.
fn decode_text(v: &[u8], encoding: Option<&str>) -> String {
    match std::str::from_utf8(v) {
        Ok(s) => s.to_string(),
        Err(_) => match encoding {
            Some("RDS_G0") => v.iter().map(|&b| crate::engine::rds_g0_char(b)).collect(),
            // `b as char` IS Latin-1 in Rust: U+0000..U+00FF map one to one.
            _ => v.iter().map(|&b| b as char).collect(),
        },
    }
}

/// Strip trailing canboat-padding bytes (`\0`, `'@'`, space, `\xff`)
/// from a string. Matches the trailing-byte loop in `printString` in
/// analyzer/print.c.
/// The trailing bytes canboat's `printString` strips off a decoded
/// string: `0xff` (the NMEA 2000 filler), any `isspace()` character,
/// NUL, and `'@'` (badly converted AIS data).
///
/// `isspace()` is the whole C set, not just a space — Navico's 130847
/// ASCII Identifier ends its text with a newline, and trimming only
/// `' '` left it on the value.
fn is_string_padding(b: u8) -> bool {
    matches!(b, 0xff | 0x00 | b'@') || b.is_ascii_whitespace() || b == 0x0b
}

fn trim_string_padding(s: &str) -> &str {
    s.trim_end_matches(|c: char| match c {
        // 0xff survives as U+00FF when the bytes came through a
        // latin-1-ish path rather than as a UTF-8 replacement char.
        '\u{ff}' => true,
        c if c.is_ascii() => is_string_padding(c as u8),
        _ => false,
    })
}

fn decode_string_lz(
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    encoding: Option<&str>,
) -> FieldValue {
    let bo = bit_offset as usize;
    let bl = bit_length as usize;
    if bo & 7 != 0 {
        return FieldValue::Unsupported {
            field_type: "STRING_LZ (unaligned)",
        };
    }
    let start = bo / 8;
    if start >= data.len() {
        return FieldValue::NotAvailable;
    }
    // STRING_LZ format (canboat `fieldPrintStringLZ`): first byte is
    // the byte length of the content, then `len` bytes of payload,
    // then a NUL terminator. `bl` here is either the field's
    // declared bit width or 0 (BitLengthVariable → read to payload
    // end). Cap the embedded length to whatever's actually present.
    let region_end = if bl == 0 {
        data.len()
    } else {
        (start + bl / 8).min(data.len())
    };
    let len_byte = data[start] as usize;
    let content_start = start + 1;
    let max_avail = region_end.saturating_sub(content_start);
    let content_end = content_start + len_byte.min(max_avail);
    let raw = decode_text(&data[content_start..content_end], encoding);
    let trimmed = trim_string_padding(&raw);
    if trimmed.is_empty() {
        FieldValue::NotAvailable
    } else {
        FieldValue::String(trimmed.to_string())
    }
}

/// DYNAMIC_FIELD_KEY: decode the integer raw value and resolve it
/// through the field's `LookupFieldTypeEnumeration`. The resolved
/// entry is parked on the [`DecodeContext`] so the matching
/// DYNAMIC_FIELD_VALUE can read its type / bits / resolution / unit.
/// The output value mirrors a normal Lookup (number + resolved name).
fn decode_dynamic_field_key(
    f: &FieldInfo,
    data: &[u8],
    db: &PgnDatabase,
    bit_offset: u32,
    bit_length: u32,
    ctx: &mut DecodeContext,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0) else {
        return FieldValue::NotAvailable;
    };
    let raw = ex.raw;
    let entry = f
        .lookup_field_type_enumeration
        .and_then(|n| db.field_type_lookup(n, raw));
    let name = entry.map(|e| e.name);
    ctx.dynamic_field_type = entry.copied();
    if name.is_some() {
        return FieldValue::Lookup { value: raw, name };
    }
    // Schema 2.5.0 declares all three hints on every DYNAMIC_FIELD_KEY
    // field in the database — fall through to the field-aware check.
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    FieldValue::Lookup {
        value: raw,
        name: None,
    }
}

/// DYNAMIC_FIELD_LENGTH: decode as a plain integer count of bytes
/// that the next DYNAMIC_FIELD_VALUE consumes.
fn decode_dynamic_field_length(
    f: &FieldInfo,
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    ctx: &mut DecodeContext,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, false, 0) else {
        return FieldValue::NotAvailable;
    };
    // A sentinel-length value can't be used to drive the next
    // DYNAMIC_FIELD_VALUE decode, so don't update the context.
    if let Some(sent) = sentinel_field_value(f, ex) {
        return sent;
    }
    // The reported length may cover a per-record header sitting between
    // this field and the value — Navico's 130822/130823 dumps count the
    // class byte and the 16-bit data-type id — so take that off to get
    // the value's own width (`g_length = value - overhead`,
    // analyzer.c::fillGlobalsBasedOnFieldName).
    let len = ex.raw as i64 - i64::from(f.dynamic_field_length_overhead);
    ctx.dynamic_length_bytes = Some(len);
    FieldValue::Integer(ex.value)
}

/// DYNAMIC_FIELD_VALUE: read the resolved field-type metadata from
/// the context and decode the value using it. Falls back to a BINARY
/// dump (mirroring `fieldPrintKeyValue`'s `g_ftf == NULL` branch)
/// when the key wasn't resolved. Returns the value plus how many bits
/// it consumed so the iteration walker can advance correctly. Always
/// clears the dynamic-* slots in the context.
///
/// A NUMBER or a DURATION / TIME value reserves the top-of-range
/// sentinels of the width it is read at, as any field of that width does
/// ([`dynamic_sentinel`]): an unstarted B&G `Trip 2 Time`, 0xFFFFFFFF, is
/// not available rather than `1193:02:47.295`. The C gets there by giving
/// the pseudo-field it builds from the key's fieldtype entry a
/// `reservedCount` (fieldPrintKeyValue, print.c); the pass in fieldtype.c
/// that resolves it for every other field never reaches that one.
///
/// ISO_NAME is the exception, and not via this mechanism:
/// `fieldPrintName` tests `value > maxValue - 2` itself, so it applies
/// on this path as much as on any other.
fn decode_dynamic_field_value(
    data: &[u8],
    bit_offset: u32,
    db: &PgnDatabase,
    ctx: &mut DecodeContext,
) -> (FieldValue, u32) {
    let entry = ctx.dynamic_field_type.take();
    let explicit_len = ctx.dynamic_length_bytes.take();
    let length_bits: Option<i64> = explicit_len
        .map(|n| n * 8)
        .or_else(|| entry.as_ref().and_then(|e| e.bit_length()).map(i64::from));
    // An explicit length of zero means the value is present but empty
    // — PGN 130823 directory entries that declare only a data type.
    // canboat omits the field rather than printing `""`
    // (`g_lengthValid && *bits == 0` → `g_skip`, print.c). Note this
    // is checked before the resolved-key branch below, so a known
    // field type with a zero length is dropped too.
    if explicit_len == Some(0) {
        ctx.skip_field = true;
        return (FieldValue::NotAvailable, 0);
    }
    let bits_signed = length_bits.unwrap_or(0);
    let remaining = (data.len() as u32 * 8).saturating_sub(bit_offset);
    if bits_signed < 0 {
        // A record declaring a length below its own header width. The
        // C subtracts the overhead into a signed `g_length` and then
        // casts to `size_t` for the bounds test below, so the negative
        // width wraps to something enormous, sails past that test and
        // reaches `fieldPrintBinary`, which clamps it to what is left
        // of the packet. Accidental, but the resulting reading — dump
        // the rest of the frame — is the useful one, so match it
        // deliberately rather than by arithmetic.
        return (decode_binary(data, bit_offset, remaining), remaining);
    }
    // The declared value runs past the end of the packet: the frame
    // ended mid-record. That is how a repeating key/value group
    // normally terminates — the device packs as many records as fit
    // and the last one is cut off — so canboat drops the partial value
    // and stops there rather than failing the whole PGN (print.c).
    if (data.len() as i64) < (bit_offset as i64 + bits_signed) >> 3 {
        ctx.skip_field = true;
        return (FieldValue::NotAvailable, remaining);
    }
    let bits = bits_signed as u32;
    let Some(entry) = entry else {
        // The key resolved to no field type, so there is no width to
        // decode against. When there was no explicit length either, the
        // value is simply the rest of the frame, and canboat dumps it
        // as raw bytes — `*bits = dataLen * 8 - startBit` before
        // `fieldPrintBinary` (fieldPrintKeyValue, print.c).
        //
        // PGN 130845 is the case that needs it: its `Value` has no
        // preceding DYNAMIC_FIELD_LENGTH at all, so an unrecognised
        // SIMNET_KEY_VALUE key leaves nothing to size the field with,
        // and taking the declared zero would print `""` over bytes that
        // are plainly on the bus.
        let bits = if bits == 0 && explicit_len.is_none() {
            remaining
        } else {
            bits
        };
        return (decode_binary(data, bit_offset, bits), bits);
    };
    let signed = entry.signed || matches!(entry.field_type, Some(ft) if ft.starts_with("FIX"));
    let val = match entry.field_type {
        Some(ft) if ft.starts_with("NUMBER") || ft.starts_with("FIX") || ft.starts_with("UFIX") => {
            decode_dynamic_number(data, bit_offset, bits, signed, &entry)
        }
        Some("LOOKUP") => match entry.lookup_enumeration {
            Some(name) => {
                let Some(ex) = extract_bits(data, bit_offset as usize, bits as usize, false, 0)
                else {
                    return (FieldValue::NotAvailable, bits);
                };
                match db.lookup(name).and_then(|t| t.get(ex.raw)).map(|v| v.name) {
                    Some(nm) => FieldValue::Lookup {
                        value: ex.raw,
                        name: Some(nm),
                    },
                    // PGN 130845's `Auto calibration mode` reads 0xFF on a
                    // Read request, which SIMNET_COMPASS_AUTOCAL_MODE does
                    // not name, and canboat omits the field rather than
                    // reporting `{"value":255}`.
                    None => unnamed_lookup_value(ex, bits),
                }
            }
            None => decode_binary(data, bit_offset, bits),
        },
        Some("DURATION") | Some("TIME") => {
            // canboat C's lookup-generated-data.h is what really decides DURATION
            // signedness: most entries are `DURATION_UFIX*` (unsigned,
            // e.g. Layline Time, Sailing Time to Waypoint, Sailing
            // ETA, Trip Time), with `DURATION_FIX*` (signed) reserved
            // for fields that genuinely carry negative values like
            // Race Timer / Timezone offset. The canboat.json
            // simplifies all of these to `"FieldType":"DURATION"`,
            // so we default to UNSIGNED and only flip to signed when
            // the lookup carries an explicit `Signed:true` or the
            // name is in the small set known to be signed in
            // canboat's pgn.h.
            let known_signed_duration = matches!(entry.name, "Race Timer" | "Timezone offset");
            let want_signed = signed || known_signed_duration;
            let Some(ex_unsigned) =
                extract_bits(data, bit_offset as usize, bits as usize, false, 0)
            else {
                return (FieldValue::NotAvailable, bits);
            };
            let ex = if want_signed {
                match extract_bits(data, bit_offset as usize, bits as usize, true, 0) {
                    Some(e) => e,
                    None => return (FieldValue::NotAvailable, bits),
                }
            } else {
                ex_unsigned
            };
            if let Some(sent) = dynamic_sentinel(ex, bits) {
                return (sent, bits);
            }
            let res = entry.resolution.unwrap_or(1.0);
            FieldValue::Time {
                raw: ex.value,
                seconds: ex.value as f64 * res,
            }
        }
        Some("DATE") => {
            let Some(ex) = extract_bits(data, bit_offset as usize, bits as usize, false, 0) else {
                return (FieldValue::NotAvailable, bits);
            };
            FieldValue::Date(ex.value as u16)
        }
        // The 130822 source-setting entries (Depth/Speed Source N,
        // Port/Stbd Boat Speed Source, …) carry a device's 8-byte
        // NMEA 2000 NAME; canboat C's fieldPrintKeyValue routes this
        // through the same printer as PGN 60928.
        Some("ISO_NAME") => decode_iso_name(data, bit_offset, bits, db),
        _ => decode_binary(data, bit_offset, bits),
    };
    (val, bits)
}

/// The top-of-range sentinels of a dynamic NUMBER / DURATION / TIME read
/// at `bits`: reservedCountForSize() values below the width's maximum,
/// signed or not, as `extractNumberNotEmpty` tests them.
fn dynamic_sentinel(ex: Extracted, bits: u32) -> Option<FieldValue> {
    let reserved: i64 = match bits {
        8.. => 3,
        4..=7 => 2,
        2..=3 => 1,
        _ => 0,
    };
    if ex.value <= ex.max - reserved {
        return None;
    }
    Some(match ex.max - ex.value {
        0 => FieldValue::NotAvailable,
        1 => FieldValue::OutOfRange { value: ex.raw },
        _ => FieldValue::ReservedValue { value: ex.raw },
    })
}

fn decode_dynamic_number(
    data: &[u8],
    bit_offset: u32,
    bit_length: u32,
    signed: bool,
    entry: &crate::engine::types::LookupFieldTypeValue,
) -> FieldValue {
    let Some(ex) = extract_bits(data, bit_offset as usize, bit_length as usize, signed, 0) else {
        return FieldValue::NotAvailable;
    };
    if let Some(sent) = dynamic_sentinel(ex, bit_length) {
        return sent;
    }
    let raw = ex.value as f64;
    let res = entry.resolution.unwrap_or(1.0);
    if res == 1.0 && entry.unit.is_none() {
        FieldValue::Integer(ex.value)
    } else {
        FieldValue::Number(raw * res + entry.unit_offset)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::PgnDatabase;

    fn db() -> &'static PgnDatabase {
        PgnDatabase::embedded(crate::engine::Units::Metric)
    }

    /// J1939 gears (SPN 523, 524) are raw - 125: neutral is raw 125, reverse
    /// below it, and raw 251 is Park (126 here). Not a signed byte.
    #[test]
    fn j1939_gears_are_offset_by_125() {
        let db = PgnDatabase::embedded_j1939(crate::engine::Units::Metric);
        let gears = |selected: u8, current: u8| {
            let frame = RawFrame {
                timestamp: None,
                prio: 6,
                pgn: 61445,
                src: 3,
                dst: 255,
                data: smallvec::smallvec![selected, 0xe8, 0x03, current, 0x44, 0x20, 0x52, 0x20],
            };
            let d = db.decode(&frame).expect("decode");
            let gear = |name: &str| d.field_by_name(name).map(|f| f.value.clone());
            (
                gear("Transmission Selected Gear"),
                gear("Transmission Current Gear"),
            )
        };
        let number = |v: &Option<FieldValue>| match v {
            Some(FieldValue::Number(x)) => Some(*x),
            _ => None,
        };
        let (selected, current) = gears(125, 124);
        assert_eq!(number(&selected), Some(0.0), "neutral");
        assert_eq!(number(&current), Some(-1.0), "reverse");
        let (park, unknown) = gears(251, 0xff);
        assert_eq!(number(&park), Some(126.0), "Park");
        assert!(
            matches!(unknown, Some(FieldValue::NotAvailable)),
            "{unknown:?}"
        );
    }

    /// Below RangeMin is out of range (#983); at it, or at an int16's full
    /// negative end, is a reading.
    #[test]
    fn a_value_below_range_min_is_out_of_range() {
        let decode = |pgn: u32, hex: &str| {
            let data: smallvec::SmallVec<[u8; 8]> = hex
                .split(',')
                .map(|h| u8::from_str_radix(h, 16).unwrap())
                .collect();
            let frame = RawFrame {
                timestamp: None,
                prio: 3,
                pgn,
                src: 1,
                dst: 255,
                data,
            };
            db().decode(&frame).expect("decode")
        };
        let value = |d: &DecodedPgn, name: &str| d.field_by_name(name).map(|f| f.value.clone());
        // An AtoN at raw 0xbd555556: latitude -111.8 deg, below -90.
        let aton = decode(
            129041,
            "ff,30,86,27,3b,56,55,55,bd,56,55,55,bd,ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,fe,ff,ff,02,01",
        );
        assert!(matches!(
            value(&aton, "Latitude"),
            Some(FieldValue::OutOfRange { value: 0xbd55_5556 })
        ));
        assert!(matches!(
            value(&aton, "Longitude"),
            Some(FieldValue::Number(_))
        ));
        // Yaw 0x8000 and pitch one step below -pi; roll at -pi.
        let attitude = decode(127257, "01,00,80,47,85,48,85,ff");
        assert!(matches!(
            value(&attitude, "Yaw"),
            Some(FieldValue::OutOfRange { .. })
        ));
        assert!(matches!(
            value(&attitude, "Pitch"),
            Some(FieldValue::OutOfRange { .. })
        ));
        assert!(matches!(
            value(&attitude, "Roll"),
            Some(FieldValue::Number(_))
        ));
        // -3276.8 A: an int16's full negative end is a reading.
        let battery = decode(127508, "00,e2,04,00,80,ff,ff,ff");
        match value(&battery, "Current") {
            Some(FieldValue::Number(a)) => assert!((a + 3276.8).abs() < 1e-9, "{a}"),
            other => panic!("expected a current, got {other:?}"),
        }
    }

    #[test]
    fn mmsi_zero_is_not_available() {
        // A Class B unit with no mothership (samples/ikonvert.log): its
        // 129810 Mothership User ID is 0, which is no station's MMSI.
        let data: smallvec::SmallVec<[u8; 8]> = "18,8e,96,03,0e,24,4e,56,43,47,4a,57,37,32,4a,\
             49,4b,39,40,40,78,00,28,00,28,00,3c,00,00,00,00,00,00,00,ff"
            .split(',')
            .map(|h| u8::from_str_radix(h.trim(), 16).unwrap())
            .collect();
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 129810,
            src: 43,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let value = |id: &str| {
            dec.fields
                .iter()
                .find(|f| f.id() == id)
                .map(|f| f.value.clone())
        };
        assert!(
            matches!(value("mothershipUserId"), Some(FieldValue::NotAvailable)),
            "{:?}",
            value("mothershipUserId")
        );
        assert!(matches!(value("userId"), Some(FieldValue::Mmsi(_))));
    }

    #[test]
    fn string_lau_ff_encoding_is_unset_field() {
        // An unset STRING_LAU: length byte present, but the encoding byte
        // and all content are 0xff filler (H5000 pilot, PGN 126998).
        // canboat's C analyzer used to abort the whole PGN with
        // "Unhandled string type 255"; here it must decode as an empty
        // (NotAvailable) field, not a run of U+FFFD replacement chars.
        let data = [0x05u8, 0xff, 0xff, 0xff, 0xff]; // len=5, enc=0xff, body=3×0xff
        let (value, bits) = decode_string_lau(&data, 0, None);
        assert!(matches!(value, FieldValue::NotAvailable), "{value:?}");
        assert_eq!(bits, 40);
    }

    #[test]
    fn string_lau_ascii_still_decodes() {
        // 1 = ASCII, "Hi" with a trailing 0xff pad byte → "Hi".
        let data = [0x05u8, 0x01, b'H', b'i', 0xff];
        let (value, bits) = decode_string_lau(&data, 0, None);
        assert!(
            matches!(value, FieldValue::String(ref s) if s == "Hi"),
            "{value:?}"
        );
        assert_eq!(bits, 40);
    }

    #[test]
    fn decodes_iso_address_claim() {
        // From canboat/analyzer/tests/pgn-test.in:
        //   2022-09-10T12:10:16.614Z,6,60928,5,255,8,fb,9b,70,22,00,9b,50,c0
        // Expected (per pgn-test.out): Unique Number=1088507,
        // Manufacturer Code=Navico (275), Device Function=Rudder (155).
        let data = smallvec::smallvec![0xfb, 0x9b, 0x70, 0x22, 0x00, 0x9b, 0x50, 0xc0];
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 60928,
            src: 5,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        assert_eq!(dec.id, "isoAddressClaim");
        assert_eq!(dec.fields.len(), 10);

        // Field 1: Unique Number (21-bit unsigned) = 1088507.
        match dec.fields[0].value {
            FieldValue::Integer(v) => assert_eq!(v, 1_088_507),
            ref other => panic!("expected integer, got {other:?}"),
        }
        // Field 2: Manufacturer Code (11-bit LOOKUP) = 275 / Navico.
        match &dec.fields[1].value {
            FieldValue::Lookup { value, name } => {
                assert_eq!(*value, 275);
                assert_eq!(name.as_deref(), Some("Navico"));
            }
            other => panic!("expected lookup, got {other:?}"),
        }
        // Field 5: Device Function (8-bit LOOKUP→INDIRECT) = 155 / Rudder.
        match &dec.fields[4].value {
            FieldValue::Lookup { value, .. } => assert_eq!(*value, 155),
            other => panic!("expected lookup, got {other:?}"),
        }

        // iso_name() re-packs the fields to the exact wire NAME, i.e.
        // the little-endian payload — the key the per-NAME 0183 filter
        // uses. Reproducing it from fields (not bytes) is what lets the
        // JSON-in daemon derive the same NAME.
        let wire_name = u64::from_le_bytes([0xfb, 0x9b, 0x70, 0x22, 0x00, 0x9b, 0x50, 0xc0]);
        assert_eq!(dec.iso_name(), Some(wire_name));
    }

    #[test]
    fn iso_name_keeps_fields_that_decode_as_not_available() {
        // System Instance 15 and Device Instance 0xFF are all ones on the
        // wire, which the decoder reports as not available. A Furuno
        // MCU-006 claims with exactly these.
        let wire = [0xef, 0xfe, 0xe0, 0xe7, 0xff, 0x82, 0xdc, 0xcf];
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 60928,
            src: 110,
            dst: 255,
            data: smallvec::SmallVec::from_slice(&wire),
        };
        let dec = db().decode(&frame).expect("decode");
        assert_eq!(dec.iso_name(), Some(u64::from_le_bytes(wire)));
    }

    #[test]
    fn iso_name_keeps_out_of_range_and_reserved_fields() {
        // System Instance 14 and 13 (byte 7's low nibble) decode as the
        // out-of-range and reserved sentinels, not as numbers.
        for system_instance in [0x0e, 0x0d] {
            let wire = [
                0xef,
                0xfe,
                0xe0,
                0xe7,
                0xff,
                0x82,
                0xdc,
                0xc0 | system_instance,
            ];
            let frame = RawFrame {
                timestamp: None,
                prio: 6,
                pgn: 60928,
                src: 110,
                dst: 255,
                data: smallvec::SmallVec::from_slice(&wire),
            };
            let dec = db().decode(&frame).expect("decode");
            assert_eq!(dec.iso_name(), Some(u64::from_le_bytes(wire)));
        }
    }

    #[test]
    fn iso_name_is_none_for_non_claim_pgn() {
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 127251,
            src: 5,
            dst: 255,
            data: smallvec::smallvec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00],
        };
        let dec = db().decode(&frame).expect("decode");
        assert_eq!(dec.iso_name(), None);
    }

    #[test]
    fn unknown_pgn_below_any_fallback_returns_error() {
        // PGN 1 is below the lowest Fallback (59392) so no catchall
        // applies — decode must report UnknownPgn.
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 1,
            src: 1,
            dst: 255,
            data: smallvec::smallvec![0u8; 8],
        };
        assert!(matches!(
            db().decode(&frame),
            Err(DecodeError::UnknownPgn { pgn: 1 })
        ));
    }

    #[test]
    fn string_fix_is_capped_to_the_message_not_dropped() {
        // Navico's 130821 ASCII Data declares a 230-byte `Message` and
        // sends however much text it has, so the declared width is a
        // maximum. canboat caps to what arrived
        // (`len = CB_MIN(len, dataLen)`, fieldPrintStringFix); dropping
        // the field instead loses the whole payload.
        let mut data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![0x13, 0x99, 0x00];
        data.extend_from_slice(b"HELLO");
        let frame = RawFrame {
            timestamp: None,
            prio: 7,
            pgn: 130821,
            src: 19,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let msg = dec
            .fields
            .iter()
            .find(|f| f.info.name == "Message")
            .expect("a Message field");
        match &msg.value {
            FieldValue::String(s) => assert_eq!(s, "HELLO"),
            other => panic!("expected the truncated text, got {other:?}"),
        }
    }

    #[test]
    fn a_geographical_area_keeps_its_last_zero() {
        // A DSC address drops the 0 that pads a 9-digit MMSI, except in a
        // call to a geographical area (DSC Format 102), whose ten digits
        // all count: 1520040510 is the NW quadrant from 52N 004W, 5 degrees
        // by 10. That holds in the distress definition too (Category 112).
        let address = |format: u8, category: u8| {
            let mut data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![format, category];
            data.extend_from_slice(&[0x0f, 0x14, 0x04, 0x05, 0x0a, 0x27, 0xff, 0xff]);
            let frame = RawFrame {
                timestamp: None,
                prio: 3,
                pgn: 129808,
                src: 1,
                dst: 255,
                data,
            };
            let dec = db().decode(&frame).expect("decode");
            dec.fields
                .iter()
                .find(|f| f.info.name == "DSC Message Address")
                .map(|f| f.value.clone())
                .expect("a DSC Message Address")
        };
        for category in [108, 112] {
            match address(102, category) {
                FieldValue::Decimal(d) => assert_eq!(d, "1520040510"),
                other => panic!("expected ten digits, got {other:?}"),
            }
        }
        // The same digits in a call to a station are an MMSI and a 0.
        match address(120, 108) {
            FieldValue::Decimal(d) => assert_eq!(d, "152004051"),
            other => panic!("expected nine digits, got {other:?}"),
        }
    }

    #[test]
    fn a_pgn_field_is_the_pgn_as_sent() {
        // A Request group function for 0x010013: PF 0x00 makes it PDU1,
        // but a PGN in the payload carries no destination, so its low byte
        // is what the sender wrote and stays, as canboat C prints it.
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 126208,
            src: 29,
            dst: 255,
            data: smallvec::smallvec![0x00, 0x13, 0x00, 0x01, 0xff, 0x01, 0xff, 0xff],
        };
        let dec = db().decode(&frame).expect("decode");
        let pgn = dec
            .fields
            .iter()
            .find(|f| f.info.name == "PGN")
            .expect("a PGN field");
        match &pgn.value {
            FieldValue::Pgn { value, .. } => assert_eq!(*value, 65555),
            other => panic!("expected a PGN, got {other:?}"),
        }
    }

    #[test]
    fn a_variable_value_the_payload_ends_inside_is_left_out() {
        // A Command for 129026's parameter 4, the 16-bit COG, with one byte
        // of it: the parameter stays, its value is left out, as in C.
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 126208,
            src: 1,
            dst: 2,
            data: smallvec::smallvec![0x01, 0x02, 0xf8, 0x01, 0xf8, 0x01, 0x04, 0x10],
        };
        let dec = db().decode(&frame).expect("decode");
        assert!(dec.fields.iter().any(|f| f.info.name == "Parameter"));
        assert!(
            dec.fields.iter().all(|f| f.info.name != "Value"),
            "a cut-off value is left out"
        );
    }

    #[test]
    fn a_split_value_without_its_high_bits_is_left_out() {
        // A DM1 whose second DTC ends after the SPN's low 16 bits: its 3
        // high bits are missing, so that SPN is left out, as in C.
        let db = PgnDatabase::embedded_j1939(crate::engine::Units::Si);
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 65226,
            src: 0,
            dst: 255,
            data: smallvec::smallvec![0x00, 0xff, 0x64, 0x00, 0x03, 0x01, 0xc8, 0x00],
        };
        let dec = db.decode(&frame).expect("decode");
        let spns: Vec<_> = dec.fields.iter().filter(|f| f.info.name == "SPN").collect();
        assert_eq!(spns.len(), 1, "only the whole DTC's SPN");
        assert_eq!(spns[0].repeat_index, Some(0), "the first DTC's");

        // With the first DTC cut the same way there is no list at all.
        let frame = RawFrame {
            data: smallvec::smallvec![0x00, 0xff, 0x64, 0x00],
            ..frame
        };
        let dec = db.decode(&frame).expect("decode");
        assert!(dec.fields.iter().all(|f| f.info.name != "SPN"));
        assert_eq!(dec.has_repeating_set, [false, false], "no list");
    }

    #[test]
    fn decimal_is_digit_pairs_and_all_ones_is_absent() {
        // samples/pgn129808.raw. A DSC address is five bytes, each one
        // a *decimal pair*: 0x33 0x14 0x00 0x5F 0x1E reads 5120009530,
        // not the 40-bit integer 130442859571 those bytes spell, and that
        // is MMSI 512000953 with the 0 DSC adds (ITU-R M.585). And
        // this call's `MMSI of Ship In Distress` is all ones — absent.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x70, 0x70, 0x33, 0x14, 0x00, 0x5f, 0x1e, 0x6e, 0x64, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x12, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 4,
            pgn: 129808,
            src: 3,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");

        let addr = dec
            .fields
            .iter()
            .find(|f| f.info.name == "DSC Message Address")
            .expect("a DSC Message Address");
        match &addr.value {
            FieldValue::Decimal(d) => assert_eq!(d, "512000953"),
            other => panic!("expected decimal digits, got {other:?}"),
        }

        // All ones is "not available" — every other field type says so,
        // and reading it as digits yields nothing at all, which is what
        // used to take the entire record down in the C.
        for f in &dec.fields {
            if f.info.name == "MMSI of Ship In Distress" {
                assert!(
                    f.value.is_not_available(),
                    "an all-ones DECIMAL must be absent, got {:?}",
                    f.value
                );
            }
        }
    }

    #[test]
    fn string_padding_covers_all_of_isspace() {
        // canboat's `printString` rtrims with `isspace()`, not just a
        // space. Navico's 130847 ASCII Identifier ends its text with a
        // newline, which was being kept.
        assert_eq!(trim_string_padding("107473373\n"), "107473373");
        assert_eq!(trim_string_padding("abc\r\n"), "abc");
        assert_eq!(trim_string_padding("abc\t \u{0}@\u{ff}"), "abc");
        // Interior whitespace is untouched.
        assert_eq!(trim_string_padding("a b"), "a b");
    }

    #[test]
    fn dynamic_field_signedness_comes_from_the_field_type() {
        // Victron's VE.Can Register 8220 (DC Current) resolves to
        // CURRENT_FIX32_MA — signed. The generated table used to derive
        // signedness from the *unit* alone (angles only), so a negative
        // current read as 4294964.496 instead of -2.8.
        let entry = db()
            .field_type_lookup("VICTRON_VREG", 8220)
            .expect("VICTRON_VREG 8220");
        assert!(entry.signed, "DC Current must be signed");
    }

    #[test]
    fn dynamic_field_units_follow_the_database() {
        // canboat C runs `fixupUnit` over field-type lookup entries as
        // over fields, so each unit system has its own table.
        use crate::engine::Units;
        let entry = |units, key| {
            *PgnDatabase::embedded(units)
                .field_type_lookup("VICTRON_VREG", key)
                .expect("VICTRON_VREG entry")
        };
        let energy = entry(Units::Si, 784);
        assert_eq!(
            (energy.unit, energy.resolution),
            (Some("J"), Some(36_000.0))
        );
        let energy = entry(Units::Metric, 784);
        assert_eq!((energy.unit, energy.resolution), (Some("kWh"), Some(0.01)));
        let temp = entry(Units::Si, 60908);
        assert_eq!((temp.unit, temp.unit_offset), (Some("K"), 0.0));
        let temp = entry(Units::Metric, 60908);
        assert_eq!((temp.unit, temp.unit_offset), (Some("C"), -273.15));
    }

    #[test]
    fn zero_width_binary_is_sized_by_the_previous_field() {
        // Fusion 130820 SiriusXM Presets: `Values` is a BINARY with no
        // declared width, and canboat takes its *bit* count from the
        // preceding `Count` (`*bits = g_previousFieldValue`,
        // fieldPrintBinary). Count = 4 here, so one byte masked to its
        // low nibble.
        let data: smallvec::SmallVec<[u8; 8]> =
            smallvec::smallvec![0xa3, 0x99, 0x1e, 0x80, 0x00, 0x04, 0x64, 0x00, 0x00, 0x00];
        let frame = RawFrame {
            timestamp: None,
            prio: 7,
            pgn: 130820,
            src: 10,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        if let Some(v) = dec.fields.iter().find(|f| f.info.name == "Values") {
            match &v.value {
                FieldValue::Binary(b) => assert_eq!(b.as_slice(), &[0x04]),
                other => panic!("expected one masked byte, got {other:?}"),
            }
        }
    }

    #[test]
    fn bitlookup_keeps_set_bits_the_enumeration_does_not_name() {
        // PGN 65305 Simnet: Pilot Mode, from
        // samples/ac42-commissioning.raw. Its `Mode` bitmap reads 0x0a
        // — bits 1 and 3. SIMNET_AP_STATUS names bit 3 ("Standby") but
        // has no entry for bit 1, and canboat still emits it as
        // `{"value":2,"name":null}`.
        //
        // Walking the enumeration's entries instead of the bit
        // positions makes an unnamed set bit invisible, which lost a
        // real bit from every autopilot status record on the bus.
        let data: smallvec::SmallVec<[u8; 8]> =
            smallvec::smallvec![0x41, 0x9f, 0x00, 0x0a, 0x0a, 0x00, 0x80, 0x00];
        let frame = RawFrame {
            timestamp: None,
            prio: 7,
            pgn: 65305,
            src: 13,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let mode = dec
            .fields
            .iter()
            .find(|f| f.info.name == "Mode")
            .expect("a Mode field");
        match &mode.value {
            FieldValue::BitField { bits, .. } => {
                assert_eq!(bits.as_slice(), &[(2, None), (8, Some("Standby"))]);
            }
            other => panic!("expected a BitField, got {other:?}"),
        }

        // …and it reaches JSON as a null-named entry, not as a gap.
        let mut json = String::new();
        crate::engine::output::write_json(
            &mut json,
            &dec,
            &crate::engine::output::JsonOptions {
                name_value: true,
                ..Default::default()
            },
        )
        .unwrap();
        assert!(
            json.contains(r#""mode":[{"value":2,"name":null},{"value":8,"name":"Standby"}]"#),
            "got: {json}"
        );
    }

    #[test]
    fn reserved_bytes_keep_their_bit_position() {
        // PGN 130824's field 2 is a 2-bit Reserved at bit 11, i.e. bits
        // 3..4 of byte 1. canboat prints it through `fieldPrintBinary`,
        // which masks the first byte and shifts it back where it was,
        // so a value of 0b10 renders `10` — not `02`.
        let data: smallvec::SmallVec<[u8; 8]> =
            smallvec::smallvec![0x7d, 0x91, 0x64, 0x20, 0x2d, 0x00];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 130824,
            src: 26,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let r = dec
            .fields
            .iter()
            .find(|f| f.info.name == "Reserved")
            .expect("a Reserved field");
        match &r.value {
            FieldValue::Reserved { bytes, .. } => assert_eq!(bytes.as_slice(), &[0x10]),
            other => panic!("expected Reserved bytes, got {other:?}"),
        }
    }

    #[test]
    fn all_ones_mmsi_is_suppressed() {
        // A real PGN 130842 Part B frame
        // (samples/merrimac-actisense-serial-2011.raw) whose
        // `Mothership User ID` is 0xFFFFFFFF — this Class B unit has no
        // mothership.
        //
        // The MMSI FieldType declares `Sentinels: None`, so no
        // per-field hint catches it. The field's RangeMax is 999999999
        // though, and the C reserves the top three values on that basis
        // alone, so canboat omits it rather than printing 4294967295.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x41, 0x9f, 0x81, 0xff, 0x18, 0x88, 0x87, 0x94, 0x0e, 0x24, 0x00, 0x00, 0x00, 0x00,
            0x00, 0x00, 0x00, 0x50, 0x49, 0x36, 0x34, 0x34, 0x36, 0x00, 0x6e, 0x00, 0x28, 0x00,
            0x1e, 0x00, 0x3c, 0x00, 0xff, 0xff, 0xff, 0xff, 0xc0,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 130842,
            src: 8,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");

        let mothership = dec
            .fields
            .iter()
            .find(|f| f.info.name == "Mothership User ID")
            .expect("a Mothership User ID field");
        assert!(
            mothership.value.is_sentinel(),
            "an all-ones MMSI must read as a sentinel, got {:?}",
            mothership.value
        );

        // The ordinary MMSI in the same frame still decodes.
        let user_id = dec
            .fields
            .iter()
            .find(|f| f.info.name == "User ID")
            .expect("a User ID field");
        assert!(matches!(user_id.value, FieldValue::Mmsi(244_615_048)));
    }

    #[test]
    fn truncated_trailing_reserved_is_omitted() {
        // A 26-byte AIS Class B position report (PGN 129039 declares
        // 27). Its trailing 15-bit `Reserved` starts at bit 201, so
        // only 7 bits survive — and those read all-ones, which canboat
        // skips. The all-ones test has to be made against the width
        // actually read: 0x7F is not 0x7FFF.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x12, 0x10, 0xad, 0x8c, 0x0e, 0xb2, 0x33, 0x2c, 0x03, 0xe6, 0x96, 0x6d, 0x1f, 0x3e,
            0xb8, 0x65, 0x71, 0x00, 0xc0, 0x00, 0xc1, 0xff, 0x7f, 0x00, 0xe2, 0xff,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 4,
            pgn: 129039,
            src: 8,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let mut json = String::new();
        crate::engine::output::write_json(
            &mut json,
            &dec,
            &crate::engine::output::JsonOptions::default(),
        )
        .unwrap();
        // Default output is camelCase, so match the key case-insensitively
        // — `"Reserved"` alone would pass even if the field were emitted.
        assert!(
            !json.to_ascii_lowercase().contains("reserved"),
            "got: {json}"
        );
    }

    #[test]
    fn unresolved_key_takes_the_rest_of_the_frame_as_its_value() {
        // PGN 130845 Simnet: Key Value, from
        // samples/ac42-commissioning.raw. Key 17671 is not in
        // SIMNET_KEY_VALUE, so no field type resolves — and this PGN
        // has no DYNAMIC_FIELD_LENGTH either, so nothing declares a
        // width. canboat falls back to the rest of the frame and prints
        // the bytes; the alternative is `""` over data that is plainly
        // there.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x41, 0x9f, 0xff, 0xff, 0x01, 0xff, 0x07, 0x45, 0x00, 0x01, 0x2d, 0x7d, 0x10, 0x14,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 2,
            pgn: 130845,
            src: 13,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let value = dec
            .fields
            .iter()
            .find(|f| f.info.name == "Value")
            .expect("a Value field");
        match &value.value {
            FieldValue::Binary(b) => assert_eq!(b.as_slice(), &[0x2d, 0x7d, 0x10, 0x14]),
            other => panic!("expected the trailing bytes, got {other:?}"),
        }
    }

    #[test]
    fn all_ones_dynamic_value_is_not_available() {
        // A B&G key-value frame (samples/pgn130824.raw line 2) whose
        // `Trip Time` and `Trip 2 Time` both read 0xFFFFFFFF, the trips
        // never having been started. A dynamic value reserves the
        // top-of-range sentinels of its width like any other field, so
        // both are not available, not `1193:02:47.295`; the record is
        // still consumed, so the Race Timer before them and the keys
        // after them decode as before.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x7d, 0x99, 0x64, 0x20, 0x2d, 0x00, 0x0d, 0x21, 0x43, 0x00, 0x0e, 0x41, 0xc0, 0xa1,
            0xb2, 0x1f, 0x0f, 0x41, 0xce, 0x50, 0x3c, 0x03, 0x69, 0x20, 0x43, 0x7d, 0xd3, 0x20,
            0x2a, 0x74, 0x81, 0x40, 0x70, 0xd3, 0x02, 0x00, 0x9a, 0x20, 0x35, 0xf0, 0x82, 0x20,
            0x00, 0x00, 0x0a, 0x21, 0x98, 0x02, 0x0c, 0x21, 0xb8, 0x02, 0x75, 0x40, 0x20, 0x6c,
            0xfb, 0xff, 0x09, 0x41, 0xff, 0xff, 0xff, 0xff, 0x0b, 0x41, 0xff, 0xff, 0xff, 0xff,
            0xd0, 0x40, 0xe0, 0xaa, 0x8c, 0x0e, 0x7f, 0x20, 0x00, 0x00, 0x9d, 0x20, 0x54, 0xad,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 130824,
            src: 26,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");

        // Each `Key` of 265 / 267 must be followed by a Value that is
        // not available.
        let mut expecting_value_for: Option<u64> = None;
        let mut seen = 0;
        for f in &dec.fields {
            match (f.info.name, &f.value) {
                ("Key", FieldValue::Lookup { value, .. }) => {
                    assert!(
                        expecting_value_for.is_none(),
                        "key {} got no Value at all",
                        expecting_value_for.unwrap()
                    );
                    if matches!(value, 265 | 267) {
                        expecting_value_for = Some(*value);
                    }
                }
                ("Value", v) => {
                    if let Some(key) = expecting_value_for.take() {
                        match v {
                            FieldValue::NotAvailable => seen += 1,
                            other => panic!("key {key}: expected not available, got {other:?}"),
                        }
                    }
                }
                _ => {}
            }
        }
        assert!(expecting_value_for.is_none(), "trailing key had no Value");
        assert_eq!(seen, 2, "expected both trip-time records");
    }

    #[test]
    fn dynamic_length_overhead_sizes_130823_records() {
        // A reassembled PGN 130823 directory report (the first record
        // of samples/navico-130823.raw). Each entry is
        // [Length][Type][Data Type:16][Value…] and `Length` counts the
        // three header bytes as well, so the value is `Length - 3`.
        // Without the overhead the walk reads three bytes too many per
        // record and every entry after the first is garbage.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x13, 0x99, 0xff, 0x00, 0x05, 0x01, 0x00, 0x0a, 0x00, 0x55, 0x02, 0xbc, 0x2f, 0x00,
            0x96, 0x50, 0xc0, 0xff, 0x04, 0x02, 0x26, 0x00, 0x00, 0x04, 0x02, 0x27, 0x00, 0x00,
            0x04, 0x02, 0x7d, 0x00, 0x00, 0x04, 0x02, 0xa5, 0x00, 0x00, 0x04, 0x02, 0x99, 0x01,
            0x00, 0x04, 0x02, 0xf9, 0x01, 0x00,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 130823,
            src: 19,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");

        // Walk the repeating set and check every value against the
        // length that introduced it.
        let mut pending: Option<i64> = None;
        let mut records = 0;
        for f in &dec.fields {
            match f.info.name {
                "Length" => {
                    if let FieldValue::Integer(n) = f.value {
                        // A record that got its Value dropped for being
                        // empty must have declared exactly the header.
                        if let Some(prev) = pending.take() {
                            assert_eq!(prev, 3, "record with no Value declared Length {prev}");
                        }
                        pending = Some(n);
                        records += 1;
                    }
                }
                "Value" => {
                    let len = pending.take().expect("Value without a preceding Length");
                    let bytes = match &f.value {
                        FieldValue::Binary(b) => b.len() as i64,
                        other => panic!("expected binary Value, got {other:?}"),
                    };
                    assert_eq!(bytes, len - 3, "Length {len} should give {} bytes", len - 3);
                }
                _ => {}
            }
        }
        if let Some(last) = pending {
            assert_eq!(
                last, 3,
                "trailing record with no Value declared Length {last}"
            );
        }
        assert!(records >= 6, "expected several records, got {records}");
    }

    #[test]
    fn parameters_resolve_a_proprietary_variant() {
        // A 126208 request against PGN 130833 naming Manufacturer =
        // Furuno (1855) and Industry = Marine (4) picks Furuno's
        // definition out of the three, so parameter 4 decodes against a
        // real typed field instead of the catch-all's raw `Data`. This
        // is the half a "several variants → use the catch-all" shortcut
        // gets wrong.
        //   [count][1][mfg lo,hi][3][industry][4]
        let params = [4u8, 0x01, 0x3f, 0x07, 0x03, 0x04, 0x04];
        let picked = match_pgn_by_parameters(db(), 130833, &params).expect("a variant");
        assert_eq!(picked.id, "furunoShipParametersAndAntennaPosition");
    }

    #[test]
    fn parameters_naming_no_126720_variant_fall_back_to_the_catch_all() {
        // From samples/raymarine-ev1.raw: Manufacturer = Raymarine
        // (1851), Industry = Marine, then parameter 4's value, which no
        // Raymarine 126720 variant carries as its proprietary ID. The C
        // matches no definition and decodes the value against the
        // catch-all, as the rest of the message: "5C 05 0F".
        let params = [4u8, 0x01, 0x3b, 0x07, 0x03, 0x04, 0x04, 0x5c, 0x05, 0x0f];
        assert!(match_pgn_by_parameters(db(), 126720, &params).is_none());

        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            0x00, 0x00, 0xef, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x04, 0x01, 0x3b, 0x07,
            0x03, 0x04, 0x04, 0x5c, 0x05, 0x0f,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 126208,
            src: 204,
            dst: 172,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let value = dec
            .fields
            .iter()
            .rfind(|f| f.repeat_set == 1)
            .expect("parameter 4's value");
        match &value.value {
            FieldValue::Binary(b) => assert_eq!(b.as_slice(), &[0x5c, 0x05, 0x0f]),
            other => panic!("expected the catch-all's raw Data, got {other:?}"),
        }
    }

    #[test]
    fn parameters_resolve_a_126720_variant_behind_the_catch_all() {
        // 126720's catch-all is listed first. The C steps past it
        // (`searchForPgn`), so Manufacturer = Airmar (135), Industry =
        // Marine and Proprietary ID 35 pick Airmar's Simulate Mode.
        //   [count][1][mfg lo,hi][3][industry][4][proprietary id]
        let params = [3u8, 0x01, 0x87, 0x00, 0x03, 0x04, 0x04, 0x23];
        let picked = match_pgn_by_parameters(db(), 126720, &params).expect("a variant");
        assert_eq!(picked.id, "airmarSimulateMode");
    }

    #[test]
    fn proprietary_target_without_manufacturer_does_not_resolve() {
        // Without a Manufacturer/Industry pair in the first two
        // parameters there is nothing to narrow a proprietary PGN with,
        // so the caller has to fall back rather than pick a layout.
        let params = [1u8, 0x04, 0x00];
        assert!(match_pgn_by_parameters(db(), 126720, &params).is_none());
    }

    #[test]
    fn match_variant_beats_fallback_listed_first() {
        // PGN 126208 has the FALLBACK variant first in JSON, then 7
        // specific variants distinguished by Function Code (field 1,
        // 8 bits at offset 0). Function Code = 3 must select
        // nmeaReadFieldsGroupFunction, NOT the leading fallback.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![
            3, // Function Code = 3 → Read Fields
            0, 0, 0, 0, 0, 0, 0,
        ];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 126208,
            src: 0,
            dst: 0,
            data,
        };
        let picked = db().pick_variant(&frame).expect("variant");
        assert_eq!(picked.id, "nmeaReadFieldsGroupFunction");
    }

    #[test]
    fn fallback_when_no_specific_variant_matches() {
        // PGN 126208 with Function Code = 99 (none of the 0..6
        // specific variants match) → return the listed fallback.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![99, 0, 0, 0, 0, 0, 0, 0];
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 126208,
            src: 0,
            dst: 0,
            data,
        };
        let picked = db().pick_variant(&frame).expect("variant");
        assert!(
            picked.fallback.unwrap_or(false),
            "expected Fallback variant, got id={}",
            picked.id
        );
    }

    #[test]
    fn pgn_59392_picks_iso_acknowledgement_over_range_catchall() {
        // Both PGN 59392 variants in canboat.json are no-Match,
        // 8-byte single-frame:
        //   * `0xE800-0xEE00: Standardized single-frame addressed`
        //     — Fallback: true, listed first
        //   * `ISO Acknowledgement` — Fallback: null, listed second
        //
        // The dispatch must pick `isoAcknowledgement` here — the
        // catch-all is only a tie-breaker when no specific variant
        // exists. Real-world bug: NAC3 autopilot ACK records used to
        // surface as the range catch-all.
        //
        // Payload bytes are a real PGN 59392 NAK observed on the bus:
        // control=1 (NAK), reserved, then PGN 126998 (0x01F016) LE.
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 59392,
            src: 17,
            dst: 200,
            data: smallvec::smallvec![0x01, 0xff, 0xff, 0xff, 0xff, 0x16, 0xf0, 0x01],
        };
        let picked = db().pick_variant(&frame).expect("variant");
        assert_eq!(picked.id, "isoAcknowledgement", "got id={}", picked.id);
        assert_eq!(picked.fallback, None);
    }

    #[test]
    fn j1939_flavor_resolves_ecu1_where_main_falls_back() {
        // PGN 61444 (EEC1, engine speed) is a J1939 definition: the
        // J1939 database must resolve it by id, while the main NMEA
        // 2000 database only has the 0xF000-0xFEFF range catch-all for
        // that number.
        let frame = RawFrame {
            timestamp: None,
            prio: 3,
            pgn: 61444,
            src: 0,
            dst: 255,
            data: smallvec::smallvec![0xff, 0xff, 0xff, 0xe0, 0x2e, 0xff, 0xff, 0xff],
        };
        let j1939 = crate::engine::db::PgnDatabase::embedded_j1939(crate::engine::db::Units::Si);
        let picked = j1939.pick_variant(&frame).expect("j1939 variant");
        assert_eq!(picked.id, "ecu1", "got id={}", picked.id);

        let main = db().pick_variant(&frame).expect("main variant");
        assert!(
            main.fallback.unwrap_or(false),
            "main db must fall back for 61444, got id={}",
            main.id
        );
    }

    #[test]
    fn j1939_flavor_keeps_shared_iso_pgns() {
        // The ISO PGNs both buses share must resolve in the J1939
        // flavor too — address claim is the canary.
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 60928,
            src: 0,
            dst: 255,
            data: smallvec::smallvec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00],
        };
        let j1939 = crate::engine::db::PgnDatabase::embedded_j1939(crate::engine::db::Units::Si);
        let picked = j1939.pick_variant(&frame).expect("j1939 variant");
        assert_eq!(picked.id, "isoAddressClaim", "got id={}", picked.id);
    }

    #[test]
    fn j1939_flavor_does_not_know_nmea2000_pgns() {
        // Exclusive-table semantics (matches keel decode and the C
        // analyzer / analyzer-j1939 pair): an NMEA-2000-only PGN must
        // not resolve to a specific definition in the J1939 flavor.
        let frame = RawFrame {
            timestamp: None,
            prio: 2,
            pgn: 129025, // Position, Rapid Update — pure NMEA 2000
            src: 0,
            dst: 255,
            data: smallvec::smallvec![0x00; 8],
        };
        let j1939 = crate::engine::db::PgnDatabase::embedded_j1939(crate::engine::db::Units::Si);
        let picked = j1939.pick_variant(&frame);
        assert!(
            picked.is_none_or(|p| p.fallback.unwrap_or(false)),
            "129025 must not resolve specifically in the J1939 flavor, got {:?}",
            picked.map(|p| p.id)
        );
    }

    #[test]
    fn cross_pgn_catchall_for_unknown_proprietary() {
        // PGN 65500 is not defined in canboat.json. The latest
        // Fallback:true PGN with pgn <= 65500 covers it — that's
        // 65280 / "0xff000xffffManufacturerProprietarySingleFrameNonAddressed".
        let frame = RawFrame {
            timestamp: None,
            prio: 6,
            pgn: 65500,
            src: 0,
            dst: 255,
            data: smallvec::smallvec![0u8; 8],
        };
        let picked = db().pick_variant(&frame).expect("catchall");
        assert!(picked.fallback.unwrap_or(false));
        assert_eq!(picked.pgn, 65280);
    }

    #[test]
    fn not_available_sentinel_on_all_ones() {
        // PGN 127245 Rudder: first field is Instance (8 bits). 0xFF is
        // the unavailable sentinel.
        let data: smallvec::SmallVec<[u8; 8]> = smallvec::smallvec![0xff; 8];
        let frame = RawFrame {
            timestamp: None,
            prio: 2,
            pgn: 127245,
            src: 0,
            dst: 255,
            data,
        };
        let dec = db().decode(&frame).expect("decode");
        let instance = &dec.fields[0];
        assert!(matches!(instance.value, FieldValue::NotAvailable));
    }

    #[test]
    fn group_function_header_is_read_only_for_a_proprietary_pgn() {
        // A Write Fields for Furuno's proprietary PGN 130845 carries the
        // Manufacturer Code (1855) / Industry Code (Marine) header after
        // the commanded PGN, as the C reads it:
        //   05 [1d ff 01] [3f 9f] 00 00 00
        let frame = RawFrame::new(
            None,
            3,
            126208,
            7,
            80,
            [0x05, 0x1d, 0xff, 0x01, 0x3f, 0x9f, 0x00, 0x00, 0x00],
        );
        let dec = db().decode(&frame).expect("decode");
        let value = |name: &str| dec.field_by_name(name).map(|f| f.value.clone());
        assert!(matches!(
            value("Manufacturer Code"),
            Some(FieldValue::Lookup { value: 1855, .. })
        ));
        assert!(matches!(
            value("Industry Code"),
            Some(FieldValue::Lookup { value: 4, .. })
        ));
        assert!(matches!(value("Unique ID"), Some(FieldValue::Integer(0))));
        assert!(matches!(
            value("Number of Selection Pairs"),
            Some(FieldValue::Integer(0))
        ));

        // For a standard PGN (127508) there is no header.
        let frame = RawFrame::new(
            None,
            3,
            126208,
            7,
            80,
            [
                0x05, 0x14, 0xf2, 0x01, 0x00, 0x01, 0x01, 0x01, 0x66, 0x01, 0x05,
            ],
        );
        let dec = db().decode(&frame).expect("decode");
        assert!(dec.field_by_name("Manufacturer Code").is_none());
        assert!(matches!(
            dec.field_by_name("Unique ID").map(|f| &f.value),
            Some(FieldValue::Integer(0))
        ));
        assert!(matches!(
            dec.field_by_name("Number of Selection Pairs")
                .map(|f| &f.value),
            Some(FieldValue::Integer(1))
        ));
    }
}