iso15118 0.5.0

//! The stateful EXI encoder and decoder.
//!
//! [`Encoder`] and [`Decoder`] pair a bit stream with the document-scoped state
//! a schema-informed EXI body needs — the value string table and a nesting
//! depth counter. Generated (and hand-written) message codecs are written
//! against these two types and nothing else.

use alloc::string::String;

use super::string_table::{Hit, ValueCtx, ValueTable};
use super::{BitReader, BitWriter, ExiError, ExiResult, Header, header, primitives as prim};

/// The length facets a schema puts on a string or binary value.
///
/// XML Schema has three — `minLength`, `maxLength` and `length` — and the third
/// is not the second: `genChallengeType` is `length = 16`, and a fifteen-byte
/// one is not a short challenge, it is not a challenge. Carrying only the
/// maximum is how a codec comes to accept a truncated ECDH public key, or a
/// nonce with a byte missing, and then re-encode it into a message no
/// conforming peer will take.
///
/// So the facets travel together, and every string and binary value is checked
/// against both on the way in and on the way out.
///
/// ```
/// # use iso15118::exi::Lengths;
/// assert!(Lengths::exact(16).admits(16));
/// assert!(!Lengths::exact(16).admits(15));
/// assert!(Lengths::max(800).admits(0));
/// assert!(Lengths::new(7, 37).admits(7) && !Lengths::new(7, 37).admits(6));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Lengths {
    min: usize,
    max: usize,
}

impl Lengths {
    /// `maxLength` only — any length up to `max`.
    #[must_use]
    pub const fn max(max: usize) -> Self {
        Self { min: 0, max }
    }

    /// `length` — exactly this many, no fewer and no more.
    #[must_use]
    pub const fn exact(len: usize) -> Self {
        Self { min: len, max: len }
    }

    /// `minLength` and `maxLength` together.
    #[must_use]
    pub const fn new(min: usize, max: usize) -> Self {
        Self { min, max }
    }

    /// The smallest permitted length.
    #[must_use]
    pub const fn min_len(self) -> usize {
        self.min
    }

    /// The largest permitted length.
    #[must_use]
    pub const fn max_len(self) -> usize {
        self.max
    }

    /// Whether a value of `len` units satisfies both facets.
    #[must_use]
    pub const fn admits(self, len: usize) -> bool {
        len >= self.min && len <= self.max
    }

    /// The error a value of `len` units earns, if any.
    const fn check(self, len: usize) -> ExiResult<()> {
        if len > self.max {
            Err(ExiError::ValueTooLong)
        } else if len < self.min {
            Err(ExiError::ValueTooShort)
        } else {
            Ok(())
        }
    }
}

/// Event-code width for a restricted integer whose bounds are `span` apart.
///
/// `span + 1` is the number of values in the range, and that addition is the
/// one place this arithmetic can leave `u64`: `i64::MIN..=i64::MAX` is a span of
/// exactly `u64::MAX`. No V2G schema declares such a range — EXI only codes an
/// integer this way when its range is small, and the widest in any of these
/// schemas is `12..=1024` — but a `Lengths`-style facet pair is data, and the
/// wrap would silently produce a *zero*-bit field rather than a wrong-width one.
/// Saturating at the full width is both the arithmetically correct answer and
/// the one that cannot be mistaken for "no bits at all".
const fn restricted_width(span: u64) -> u32 {
    match span.checked_add(1) {
        Some(values) => prim::bit_width(values),
        None => u64::BITS,
    }
}

/// Hard ceiling on element nesting.
///
/// The deepest ISO 15118 schema nests well under a dozen levels; a stream that
/// claims more is malformed or hostile, and refusing it keeps recursive
/// generated decoders off the edge of the stack.
pub const MAX_DEPTH: u16 = 64;

/// How an encoder codes a string value that it has already written once.
///
/// EXI keeps every string value in a two-level table and lets a later
/// occurrence be written as a short reference into it instead of as characters
/// (`[EXI §7.3.3]`). Both forms decode to the same string, so this changes
/// nothing about *what* a message says — only about who can read it.
///
/// Decoding is unaffected: a [`Decoder`] always accepts both forms, because a
/// peer may legitimately send either.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ValueCoding {
    /// Never write a reference. Every value is written out in full.
    ///
    /// **The default, because it is the only form the field can read.**
    /// `libcbv2g` — the codec `EVerest` ships, and so the one production charge
    /// points run — implements no value table at all: its decoder subtracts the
    /// literal's offset of two and returns `EXI_ERROR__STRINGVALUES_NOT_SUPPORTED`
    /// for anything shorter. A message carrying a reference is not merely large
    /// for that peer, it is **undecodable**. `RiseV2G` writes literals too, which
    /// is why the canonical-EXI URI appears twice in full in every signature it
    /// makes.
    ///
    /// The cost is bytes, and only for a value that actually repeats.
    #[default]
    Literal,
    /// Write a reference wherever EXI allows one.
    ///
    /// What `exificient` produces and what Canonical EXI requires — *"a string
    /// value MUST be represented using a compact identifier if possible"*. This
    /// crate can produce it byte-for-byte, which is how the grammar and the
    /// table logic are checked against the reference implementation, and it is
    /// the second form signature verification tries, for a peer that
    /// canonicalises properly.
    ///
    /// It is **not** the default: the specification and the installed base
    /// disagree here, and only one of them charges cars — see
    /// [`ValueCoding::Literal`].
    Referenced,
}

/// Writes a schema-informed EXI body into a caller-owned buffer.
#[derive(Debug)]
pub struct Encoder<'a> {
    bits: BitWriter<'a>,
    values: ValueTable,
    coding: ValueCoding,
    depth: u16,
}

impl<'a> Encoder<'a> {
    /// Creates an encoder over `buf` that writes every value in full.
    ///
    /// See [`ValueCoding::Literal`] for why that is the default.
    #[must_use]
    pub fn new(buf: &'a mut [u8]) -> Self {
        Self::with_value_coding(buf, ValueCoding::Literal)
    }

    /// Creates an encoder with an explicit [`ValueCoding`].
    #[must_use]
    pub fn with_value_coding(buf: &'a mut [u8], coding: ValueCoding) -> Self {
        Self { bits: BitWriter::new(buf), values: ValueTable::new(), coding, depth: 0 }
    }

    /// The value coding this encoder was built with.
    #[must_use]
    pub const fn value_coding(&self) -> ValueCoding {
        self.coding
    }

    /// Writes the EXI header. Call once, before any event.
    pub fn write_header(&mut self, header: Header) -> ExiResult<()> {
        header::write_header(&mut self.bits, header)
    }

    /// Writes an event code of `width` bits.
    ///
    /// A width of zero writes nothing, which is the common case: a grammar
    /// state with a single possible production costs no bits at all.
    pub fn event(&mut self, code: u64, width: u32) -> ExiResult<()> {
        prim::write_nbit_uint(&mut self.bits, code, width)
    }

    /// Enters a nested element, enforcing [`MAX_DEPTH`].
    ///
    /// Saturating rather than wrapping, which matters only for a caller that
    /// ignores the error and pushes again: sixty-five thousand of those would
    /// otherwise wrap the counter back to zero and hand the ceiling away. A
    /// bound that an ignored error can lift is not one.
    pub fn enter(&mut self) -> ExiResult<()> {
        self.depth = self.depth.saturating_add(1);
        if self.depth > MAX_DEPTH {
            return Err(ExiError::DepthLimitExceeded);
        }
        Ok(())
    }

    /// Leaves a nested element.
    pub fn leave(&mut self) {
        self.depth = self.depth.saturating_sub(1);
    }

    /// Writes an Unsigned Integer.
    pub fn uint(&mut self, v: u64) -> ExiResult<()> {
        prim::write_uint(&mut self.bits, v)
    }

    /// Writes a Signed Integer.
    pub fn int(&mut self, v: i64) -> ExiResult<()> {
        prim::write_int(&mut self.bits, v)
    }

    /// Writes an `n`-bit unsigned integer (enumeration index, restricted int).
    pub fn nbit(&mut self, v: u64, n: u32) -> ExiResult<()> {
        prim::write_nbit_uint(&mut self.bits, v, n)
    }

    /// Writes a Boolean.
    pub fn boolean(&mut self, v: bool) -> ExiResult<()> {
        prim::write_bool(&mut self.bits, v)
    }

    /// Writes a schema-restricted integer (EXI 1.0 §7.1.9).
    ///
    /// A type whose `minInclusive`/`maxInclusive` span 4096 values or fewer
    /// travels as an index into that range rather than as a general integer, so
    /// `priorityType` (1..=20) costs five bits and not an octet.
    pub fn restricted(&mut self, value: i64, min: i64, max: i64) -> ExiResult<()> {
        debug_assert!(min <= max, "empty range {min}..={max}");
        if value < min || value > max {
            return Err(ExiError::ValueOutOfRange);
        }
        // The bounds may straddle zero, so the differences are computed in
        // i128: `max - min` can overflow i64 for a range wide enough, even
        // though EXI only codes ranges of 4096 values this way. Both are
        // non-negative here, because `min <= value <= max`.
        let span = u64::try_from(i128::from(max) - i128::from(min))
            .map_err(|_| ExiError::ValueOutOfRange)?;
        let index = u64::try_from(i128::from(value) - i128::from(min))
            .map_err(|_| ExiError::ValueOutOfRange)?;
        self.nbit(index, restricted_width(span))
    }

    /// Writes binary content, rejecting anything outside the schema's length
    /// facets.
    pub fn binary(&mut self, bytes: &[u8], lengths: Lengths) -> ExiResult<()> {
        lengths.check(bytes.len())?;
        prim::write_binary(&mut self.bits, bytes)
    }

    /// Writes a Decimal.
    pub fn decimal(&mut self, v: prim::Decimal) -> ExiResult<()> {
        prim::write_decimal(&mut self.bits, v)
    }

    /// Writes a Float.
    pub fn float(&mut self, v: prim::Float) -> ExiResult<()> {
        prim::write_float(&mut self.bits, v)
    }

    /// Writes a date-time.
    pub fn datetime(&mut self, v: prim::DateTime) -> ExiResult<()> {
        prim::write_datetime(&mut self.bits, v)
    }

    /// Writes a string value.
    ///
    /// `ctx` selects the local partition — it must identify the element or
    /// attribute the value belongs to, and must match what the decoder uses.
    /// Whether a repeat is written as a reference into that partition is
    /// [`ValueCoding`]'s decision, and the default is not to.
    ///
    /// # Interoperability: keep values ASCII
    ///
    /// EXI codes a character as a Unicode code point, which is what this writes.
    /// `libcbv2g` — `EVerest`'s codec — writes and reads one **octet** per
    /// character and rejects anything above 127 with
    /// `EXI_ERROR__UNSUPPORTED_CHARACTER_VALUE`. So for ASCII the two agree
    /// exactly and above it they do not agree at all: `"Ladesäule"` as a
    /// `ServiceName` is valid ISO 15118 and undecodable to a production charge
    /// point.
    ///
    /// Nothing here refuses it — the schema permits it, it is the caller's
    /// data, and silently transliterating a tariff description would be the
    /// worse failure. The choice belongs where the string is chosen.
    pub fn string(&mut self, ctx: ValueCtx, value: &str, lengths: Lengths) -> ExiResult<()> {
        let n = prim::char_len(value);
        lengths.check(n)?;

        if self.coding == ValueCoding::Referenced {
            match self.values.find(ctx, value) {
                Hit::Local(idx) => {
                    let width = self.values.local_index_width(ctx);
                    self.uint(0)?;
                    return self.nbit(idx, width);
                }
                Hit::Global(idx) => {
                    let width = self.values.global_index_width();
                    self.uint(1)?;
                    // Deliberately *not* added to this context's local
                    // partition. EXI populates partitions only when a value is
                    // coded literally (§7.3.3); a global hit leaves the local
                    // one empty, so the next occurrence here is another global
                    // hit. Adding it here desynchronises from any conforming
                    // peer the moment one string appears under two element
                    // names — which is most messages.
                    return self.nbit(idx, width);
                }
                Hit::Miss => {}
            }
        }

        // Literal: the length is offset by two so that 0 and 1 stay free as the
        // local- and global-hit markers.
        self.uint(n as u64 + 2)?;
        prim::write_chars(&mut self.bits, value)?;
        // Only under `Referenced`: nothing reads the partitions in the other
        // mode, and on a `thumbv7em` target a table kept for no reader is an
        // allocation per string value for nothing.
        if self.coding == ValueCoding::Referenced {
            self.values.insert(ctx, value);
        }
        Ok(())
    }

    /// Bits written so far, header included.
    #[must_use]
    pub const fn bit_len(&self) -> usize {
        self.bits.bit_len()
    }

    /// Finishes the document, padding the last byte, and returns its length.
    pub fn finish(self) -> ExiResult<usize> {
        self.bits.finish()
    }
}

/// Reads a schema-informed EXI body.
#[derive(Debug)]
pub struct Decoder<'a> {
    bits: BitReader<'a>,
    values: ValueTable,
    depth: u16,
}

impl<'a> Decoder<'a> {
    /// Creates a decoder over `buf`.
    ///
    /// There is no coding to choose on the way in: a decoder accepts a value
    /// written in full **and** a reference into the string table, because a
    /// conforming peer may send either and refusing one would be refusing
    /// `exificient`. [`ValueCoding`] is an encoder-side decision only.
    #[must_use]
    pub const fn new(buf: &'a [u8]) -> Self {
        Self { bits: BitReader::new(buf), values: ValueTable::new(), depth: 0 }
    }

    /// Reads and validates the EXI header.
    pub fn read_header(&mut self) -> ExiResult<Header> {
        header::read_header(&mut self.bits)
    }

    /// Reads an event code of `width` bits.
    pub fn event(&mut self, width: u32) -> ExiResult<u64> {
        prim::read_nbit_uint(&mut self.bits, width)
    }

    /// Reads an event code and requires it to be `code`.
    ///
    /// Used where the grammar leaves no choice — the `CH` and `EE` around a
    /// simple-typed element, for instance. Anything else means the stream and
    /// the grammar disagree, which must be a rejection rather than a guess.
    pub fn expect_event(&mut self, code: u64, width: u32) -> ExiResult<()> {
        if self.event(width)? == code { Ok(()) } else { Err(ExiError::UnknownEventCode) }
    }

    /// Enters a nested element, enforcing [`MAX_DEPTH`].
    ///
    /// Saturating rather than wrapping, which matters only for a caller that
    /// ignores the error and pushes again: sixty-five thousand of those would
    /// otherwise wrap the counter back to zero and hand the ceiling away. A
    /// bound that an ignored error can lift is not one.
    pub fn enter(&mut self) -> ExiResult<()> {
        self.depth = self.depth.saturating_add(1);
        if self.depth > MAX_DEPTH {
            return Err(ExiError::DepthLimitExceeded);
        }
        Ok(())
    }

    /// Leaves a nested element.
    pub fn leave(&mut self) {
        self.depth = self.depth.saturating_sub(1);
    }

    /// Reads an Unsigned Integer.
    pub fn uint(&mut self) -> ExiResult<u64> {
        prim::read_uint(&mut self.bits)
    }

    /// Reads a Signed Integer.
    pub fn int(&mut self) -> ExiResult<i64> {
        prim::read_int(&mut self.bits)
    }

    /// Reads an `n`-bit unsigned integer.
    pub fn nbit(&mut self, n: u32) -> ExiResult<u64> {
        prim::read_nbit_uint(&mut self.bits, n)
    }

    /// Reads a Boolean.
    pub fn boolean(&mut self) -> ExiResult<bool> {
        prim::read_bool(&mut self.bits)
    }

    /// Reads a schema-restricted integer (EXI 1.0 §7.1.9).
    ///
    /// The index is checked against the range before it is offset: a range of
    /// twenty values leaves twelve of the thirty-two five-bit encodings unused,
    /// and those are rejected rather than passed through as out-of-schema
    /// values that could not be re-encoded.
    pub fn restricted(&mut self, min: i64, max: i64) -> ExiResult<i64> {
        debug_assert!(min <= max, "empty range {min}..={max}");
        let span = u64::try_from(i128::from(max) - i128::from(min))
            .map_err(|_| ExiError::ValueOutOfRange)?;
        let index = self.nbit(restricted_width(span))?;
        if index > span {
            return Err(ExiError::ValueOutOfRange);
        }
        i64::try_from(i128::from(min) + i128::from(index)).map_err(|_| ExiError::ValueOutOfRange)
    }

    /// Reads binary content, rejecting anything outside the schema's length
    /// facets.
    pub fn binary(&mut self, lengths: Lengths) -> ExiResult<alloc::vec::Vec<u8>> {
        let bytes = prim::read_binary(&mut self.bits, lengths.max_len())?;
        lengths.check(bytes.len())?;
        Ok(bytes)
    }

    /// Reads a Decimal.
    pub fn decimal(&mut self) -> ExiResult<prim::Decimal> {
        prim::read_decimal(&mut self.bits)
    }

    /// Reads a Float.
    pub fn float(&mut self) -> ExiResult<prim::Float> {
        prim::read_float(&mut self.bits)
    }

    /// Reads a date-time.
    pub fn datetime(&mut self) -> ExiResult<prim::DateTime> {
        prim::read_datetime(&mut self.bits)
    }

    /// Reads a string value through the string table.
    ///
    /// The length facets are checked on the literal *and* on a table hit: a
    /// partition entry is a value this same stream coded literally, so it has
    /// already passed — but the check costs nothing and a table index is
    /// attacker-chosen.
    pub fn string(&mut self, ctx: ValueCtx, lengths: Lengths) -> ExiResult<String> {
        let value = self.string_inner(ctx, lengths)?;
        lengths.check(prim::char_len(&value))?;
        Ok(value)
    }

    fn string_inner(&mut self, ctx: ValueCtx, lengths: Lengths) -> ExiResult<String> {
        let marker = self.uint()?;
        match marker {
            0 => {
                let width = self.values.local_index_width(ctx);
                let idx = self.nbit(width)?;
                self.values.local(ctx, idx).map(String::from).ok_or(ExiError::BadStringTableIndex)
            }
            1 => {
                let width = self.values.global_index_width();
                let idx = self.nbit(width)?;
                // Mirrors the encoder: a global hit does not populate the local
                // partition.
                self.values.global(idx).map(String::from).ok_or(ExiError::BadStringTableIndex)
            }
            n => {
                let len = usize::try_from(n - 2).map_err(|_| ExiError::ValueTooLong)?;
                if len > lengths.max_len() {
                    return Err(ExiError::ValueTooLong);
                }
                let s = prim::read_chars(&mut self.bits, len)?;
                self.values.insert(ctx, &s);
                Ok(s)
            }
        }
    }

    /// Bits consumed so far.
    #[must_use]
    pub const fn bit_pos(&self) -> usize {
        self.bits.bit_pos()
    }

    /// Bits still unread.
    #[must_use]
    pub const fn bits_remaining(&self) -> usize {
        self.bits.bits_remaining()
    }

    /// Consumes the trailing pad bits and asserts the document is fully read.
    ///
    /// A stream with bytes left over after the document ended is rejected:
    /// silently ignoring them would let a peer smuggle data past the grammar.
    pub fn finish(mut self) -> ExiResult<()> {
        self.bits.skip_padding()?;
        if self.bits.bits_remaining() != 0 {
            return Err(ExiError::TrailingData);
        }
        Ok(())
    }
}

/// A message that forms a complete EXI document: header, one root element, end.
pub trait ExiDocument: Sized {
    /// Writes header, body and padding into `buf` under `coding`; returns the
    /// byte length.
    ///
    /// The generated implementation of this is the only encoder entry point
    /// each type carries; everything else here is a wrapper that picks a
    /// [`ValueCoding`].
    fn to_slice_with(&self, buf: &mut [u8], coding: ValueCoding) -> ExiResult<usize>;

    /// Parses a complete EXI document, rejecting trailing bytes.
    fn from_bytes(bytes: &[u8]) -> ExiResult<Self>;

    /// Writes header, body and padding into `buf`, every value in full.
    ///
    /// The interoperable coding — see [`ValueCoding::Literal`].
    fn to_slice(&self, buf: &mut [u8]) -> ExiResult<usize> {
        self.to_slice_with(buf, ValueCoding::Literal)
    }

    /// Encodes into a fresh vector, every value in full.
    fn to_vec(&self) -> ExiResult<alloc::vec::Vec<u8>> {
        encode_growing(|buf| self.to_slice(buf))
    }

    /// Encodes into a fresh vector under an explicit [`ValueCoding`].
    fn to_vec_with(&self, coding: ValueCoding) -> ExiResult<alloc::vec::Vec<u8>> {
        encode_growing(|buf| self.to_slice_with(buf, coding))
    }
}

/// Runs a slice encoder against a buffer that doubles until the output fits.
///
/// The EXI encoders write into caller-owned slices so that a `no_std` target
/// can size its own buffer; this is the convenience wrapper for callers that
/// would rather have a `Vec`. It stops at [`MAX_EXI_PAYLOAD_LEN`], which is
/// far above any real V2G message.
///
/// [`MAX_EXI_PAYLOAD_LEN`]: crate::MAX_EXI_PAYLOAD_LEN
pub fn encode_growing(
    mut encode: impl FnMut(&mut [u8]) -> ExiResult<usize>,
) -> ExiResult<alloc::vec::Vec<u8>> {
    // ISO 15118 caps a V2GTP payload at 4 GiB but real messages are far
    // smaller; grow from a realistic size rather than guessing big.
    let mut buf = alloc::vec![0u8; 4096];
    loop {
        match encode(&mut buf) {
            Ok(n) => {
                buf.truncate(n);
                return Ok(buf);
            }
            Err(ExiError::OutputFull) if buf.len() < crate::MAX_EXI_PAYLOAD_LEN => {
                buf.resize((buf.len() * 2).min(crate::MAX_EXI_PAYLOAD_LEN), 0);
            }
            Err(e) => return Err(e),
        }
    }
}

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

    const CTX_A: ValueCtx = ValueCtx(1);
    const CTX_B: ValueCtx = ValueCtx(2);

    /// Exercises the referenced coding, which is the one with table state to
    /// get wrong. The literal coding has none.
    fn roundtrip_strings(values: &[(ValueCtx, &str)]) {
        let mut buf = [0u8; 1024];
        let mut e = Encoder::with_value_coding(&mut buf, ValueCoding::Referenced);
        e.write_header(Header::ISO15118).unwrap();
        for &(ctx, s) in values {
            e.string(ctx, s, Lengths::max(4096)).unwrap();
        }
        let len = e.finish().unwrap();

        let mut d = Decoder::new(&buf[..len]);
        d.read_header().unwrap();
        for &(ctx, s) in values {
            assert_eq!(d.string(ctx, Lengths::max(4096)).unwrap(), s);
        }
        d.finish().unwrap();
    }

    #[test]
    fn repeated_strings_roundtrip_through_the_table() {
        roundtrip_strings(&[
            (CTX_A, "urn:iso:15118:2:2013:MsgDef"),
            (CTX_A, "urn:iso:15118:2:2013:MsgDef"), // local hit
            (CTX_B, "urn:iso:15118:2:2013:MsgDef"), // global hit
            (CTX_B, "urn:iso:15118:2:2013:MsgDef"), // still a global hit
            (CTX_A, "something else"),
        ]);
    }

    /// A global hit must not populate the local partition.
    ///
    /// Found by round-tripping ISO 15118-2 `ServiceDiscoveryRes` against the
    /// reference implementation: `ServiceName` and `ServiceScope` both carry
    /// the same text, and treating the second element's global hit as a local
    /// insertion made every later occurrence code differently.
    #[test]
    fn a_global_hit_leaves_the_local_partition_empty() {
        let mut buf = [0u8; 256];
        let mut e = Encoder::with_value_coding(&mut buf, ValueCoding::Referenced);
        e.string(CTX_A, "Sample", Lengths::max(64)).unwrap(); // literal, populates both
        let before = e.bit_len();
        e.string(CTX_B, "Sample", Lengths::max(64)).unwrap(); // global hit
        let first_global = e.bit_len() - before;
        let before = e.bit_len();
        e.string(CTX_B, "Sample", Lengths::max(64)).unwrap(); // must be another global hit
        assert_eq!(e.bit_len() - before, first_global, "the second must cost the same");
    }

    #[test]
    fn the_referenced_coding_actually_saves_bits() {
        let long = "urn:iso:std:iso:15118:-20:CommonMessages";
        let mut single_buf = [0u8; 512];
        let mut e = Encoder::with_value_coding(&mut single_buf, ValueCoding::Referenced);
        e.string(CTX_A, long, Lengths::max(4096)).unwrap();
        let one = e.bit_len();

        let mut repeat_buf = [0u8; 512];
        let mut e = Encoder::with_value_coding(&mut repeat_buf, ValueCoding::Referenced);
        e.string(CTX_A, long, Lengths::max(4096)).unwrap();
        e.string(CTX_A, long, Lengths::max(4096)).unwrap();
        let two = e.bit_len();

        assert!(two < one + 16, "a repeat should cost a handful of bits, not {} ", two - one);
    }

    /// The default coding writes a repeat out in full, because the codec
    /// `EVerest` ships cannot read a reference at all — it returns
    /// `EXI_ERROR__STRINGVALUES_NOT_SUPPORTED`. Asserted on the *bits*: a
    /// weaker test on the decoded value would pass for the coding that does
    /// not interoperate, which is exactly the bug this guards.
    #[test]
    fn the_default_coding_never_writes_a_reference() {
        let mut buf = [0u8; 512];
        let mut e = Encoder::new(&mut buf);
        e.string(CTX_A, "abc", Lengths::max(64)).unwrap();
        let one = e.bit_len();
        e.string(CTX_A, "abc", Lengths::max(64)).unwrap();
        let two = e.bit_len();
        let len = e.finish().unwrap();

        assert_eq!(two - one, one, "the repeat must cost exactly what the first one did");

        // …and a decoder reads it back without ever consulting the table.
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, Lengths::max(64)).unwrap(), "abc");
        assert_eq!(d.string(CTX_A, Lengths::max(64)).unwrap(), "abc");
        d.finish().unwrap();
    }

    /// And a decoder still accepts the referenced form, because `exificient`
    /// and any Canonical EXI signer emit it.
    #[test]
    fn a_decoder_accepts_what_the_encoder_declines_to_write() {
        let mut buf = [0u8; 512];
        let mut e = Encoder::with_value_coding(&mut buf, ValueCoding::Referenced);
        e.string(CTX_A, "abc", Lengths::max(64)).unwrap();
        e.string(CTX_A, "abc", Lengths::max(64)).unwrap();
        let len = e.finish().unwrap();

        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, Lengths::max(64)).unwrap(), "abc");
        assert_eq!(d.string(CTX_A, Lengths::max(64)).unwrap(), "abc");
        d.finish().unwrap();
    }

    /// `xs:length` is not `xs:maxLength`, and the types that have one are the
    /// ones where a short value is a broken value rather than a small one.
    #[test]
    fn an_exact_length_refuses_a_short_value_both_ways() {
        const CHALLENGE: Lengths = Lengths::exact(16);
        let mut buf = [0u8; 128];

        let mut e = Encoder::new(&mut buf);
        assert_eq!(e.binary(&[0xA5; 15], CHALLENGE), Err(ExiError::ValueTooShort));
        assert_eq!(e.binary(&[0xA5; 17], CHALLENGE), Err(ExiError::ValueTooLong));
        e.binary(&[0xA5; 16], CHALLENGE).unwrap();

        // ...and a peer that puts a short one on the wire is refused too, which
        // is the direction that matters: the alternative is decoding it and
        // re-encoding a message no conforming implementation will take.
        let mut e = Encoder::new(&mut buf);
        e.binary(&[0xA5; 15], Lengths::max(16)).unwrap();
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.binary(CHALLENGE), Err(ExiError::ValueTooShort));
    }

    #[test]
    fn a_minimum_length_applies_to_strings_as_well() {
        const EMAID: Lengths = Lengths::new(14, 15);
        let mut buf = [0u8; 128];

        let mut e = Encoder::new(&mut buf);
        assert_eq!(e.string(CTX_A, "DE123", EMAID), Err(ExiError::ValueTooShort));
        e.string(CTX_A, "DE8ACME123456A", EMAID).unwrap();
        let len = e.finish().unwrap();

        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, EMAID).unwrap(), "DE8ACME123456A");

        // A shorter one on the wire is refused, table hit or not.
        let mut e = Encoder::new(&mut buf);
        e.string(CTX_A, "short", Lengths::max(64)).unwrap();
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, EMAID), Err(ExiError::ValueTooShort));
    }

    #[test]
    fn over_long_strings_are_refused_both_ways() {
        let mut buf = [0u8; 128];
        let mut e = Encoder::new(&mut buf);
        assert_eq!(e.string(CTX_A, "abcdef", Lengths::max(3)), Err(ExiError::ValueTooLong));

        let mut e = Encoder::new(&mut buf);
        e.string(CTX_A, "abcdef", Lengths::max(64)).unwrap();
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, Lengths::max(3)), Err(ExiError::ValueTooLong));
    }

    #[test]
    fn a_forged_table_index_is_rejected() {
        // Marker 0 (local hit) with an empty partition: width is 0 bits, so the
        // index is 0 and there is nothing at 0.
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        e.uint(0).unwrap();
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.string(CTX_A, Lengths::max(64)), Err(ExiError::BadStringTableIndex));
    }

    #[test]
    fn trailing_bytes_are_rejected() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        e.write_header(Header::ISO15118).unwrap();
        e.uint(7).unwrap();
        let len = e.finish().unwrap();

        let mut with_junk = alloc::vec::Vec::from(&buf[..len]);
        with_junk.push(0xAA);
        let mut d = Decoder::new(&with_junk);
        d.read_header().unwrap();
        assert_eq!(d.uint().unwrap(), 7);
        assert_eq!(d.finish(), Err(ExiError::TrailingData));
    }

    #[test]
    fn restricted_integers_use_the_range_not_the_type_width() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        // 1..=20 is twenty values, so five bits regardless of it being a byte.
        e.restricted(20, 1, 20).unwrap();
        assert_eq!(e.bit_len(), 5);
    }

    #[test]
    fn restricted_integers_roundtrip_across_their_whole_range() {
        // Ranges may straddle zero: ISO 15118-20 has `minInclusive="-3"`.
        for (min, max) in [(0i64, 255i64), (1, 20), (0, 0), (7, 9), (0, 4095), (-3, 3), (-128, 127)]
        {
            for v in [min, max, i64::midpoint(min, max)] {
                let mut buf = [0u8; 32];
                let mut e = Encoder::new(&mut buf);
                e.restricted(v, min, max).unwrap();
                let len = e.finish().unwrap();
                let mut d = Decoder::new(&buf[..len]);
                assert_eq!(d.restricted(min, max).unwrap(), v, "range {min}..={max}");
            }
        }
    }

    #[test]
    fn encoding_out_of_range_is_refused() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        assert_eq!(e.restricted(21, 1, 20), Err(ExiError::ValueOutOfRange));
        assert_eq!(e.restricted(0, 1, 20), Err(ExiError::ValueOutOfRange));
    }

    #[test]
    fn a_range_straddling_zero_roundtrips() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        e.restricted(-3, -3, 3).unwrap();
        assert_eq!(e.bit_len(), 3, "seven values need three bits");
        e.restricted(3, -3, 3).unwrap();
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.restricted(-3, 3).unwrap(), -3);
        assert_eq!(d.restricted(-3, 3).unwrap(), 3);
    }

    #[test]
    fn decoding_an_unused_index_is_refused() {
        // 1..=20 needs five bits; indices 20..=31 have no schema value.
        for index in 20u64..32 {
            let mut buf = [0u8; 16];
            let mut e = Encoder::new(&mut buf);
            e.nbit(index, 5).unwrap();
            let len = e.finish().unwrap();
            let mut d = Decoder::new(&buf[..len]);
            assert_eq!(d.restricted(1, 20), Err(ExiError::ValueOutOfRange), "index {index}");
        }
    }

    /// `i64::MIN..=i64::MAX` is a span of `u64::MAX`, so the "+1 for the count
    /// of values" that every other range needs is the one that wraps. Wrapping
    /// would code the value in *zero* bits — silently dropping it — rather than
    /// in the sixty-four it needs.
    #[test]
    fn a_full_width_range_does_not_wrap_to_zero_bits() {
        let mut buf = [0u8; 32];
        let mut e = Encoder::new(&mut buf);
        e.restricted(0, i64::MIN, i64::MAX).unwrap();
        assert_eq!(e.bit_len(), 64, "2^64 values need 64 bits, not none");
        let len = e.finish().unwrap();
        let mut d = Decoder::new(&buf[..len]);
        assert_eq!(d.restricted(i64::MIN, i64::MAX).unwrap(), 0);
    }

    #[test]
    fn a_single_valued_range_costs_no_bits() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        e.restricted(5, 5, 5).unwrap();
        assert_eq!(e.bit_len(), 0);
        let mut d = Decoder::new(&[]);
        assert_eq!(d.restricted(5, 5).unwrap(), 5);
    }

    #[test]
    fn depth_is_bounded() {
        let mut buf = [0u8; 16];
        let mut e = Encoder::new(&mut buf);
        for _ in 0..MAX_DEPTH {
            e.enter().unwrap();
        }
        assert_eq!(e.enter(), Err(ExiError::DepthLimitExceeded));
    }

    /// A bound an ignored error can lift is not a bound. The counter saturates,
    /// so a caller that keeps pushing past the ceiling stays past it rather
    /// than wrapping back to zero sixty-five thousand pushes later.
    #[test]
    fn the_depth_ceiling_survives_a_caller_that_ignores_it() {
        let mut d = Decoder::new(&[]);
        for _ in 0..MAX_DEPTH {
            d.enter().unwrap();
        }
        for _ in 0..70_000 {
            assert_eq!(d.enter(), Err(ExiError::DepthLimitExceeded));
        }
    }
}