qubit-codec 0.17.4

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Buffered input driver that decodes units into values.

use core::fmt::Debug;
use core::fmt::Formatter;
use core::fmt::Result as FormatResult;
use std::collections::TryReserveError;
use std::io::Error;
use std::io::ErrorKind;
use std::io::Read;
use std::io::Result;
use std::io::Seek;
use std::io::SeekFrom;
use std::result::Result as StdResult;

use qubit_io::Buffer;
use qubit_io::BufferedInput;
use qubit_io::ByteInput;
use qubit_io::Input;
use qubit_io::SeekableByteInput;
use qubit_utils::SliceRange;
use qubit_utils::UncheckedSlice;
use qubit_utils::allocation_error;
use qubit_utils::try_reserve_vec;

use super::internal::CodecDecodeDriver;
use super::internal::capacity_error_to_invalid_data;
use super::internal::validate_decode_progress;
use super::internal::validate_eof_decode_progress;
use crate::Codec;
use crate::DecodeLifecycleOutput;
use crate::DecodeLifecycleProgress;
use crate::TranscodeDomainError;
use crate::TranscodeFailure;
use crate::TranscodeProgress;
use crate::TranscodeStatus;
use crate::Transcoder;
use crate::codec::assert_unit_bounds;

/// Decodes an [`Input`] unit stream into an [`Input`] value stream.
///
/// This type owns only the unit-level [`qubit_io::BufferedInput`]. Callers pass
/// a streaming [`Transcoder`] and error mapper to each decode operation, which
/// lets one buffered input drive different decoders without nesting buffers or
/// storing decoder-specific state in the buffer owner.
///
/// # Type Parameters
///
/// * `I` - Wrapped unit input.
///
/// # Examples
///
/// ```
/// use core::convert::Infallible;
/// use core::num::NonZeroUsize;
/// use std::io::Cursor;
/// use qubit_codec::Codec;
/// use qubit_codec::DecodeFailure;
/// use qubit_codec::TranscodeDecodeInput;
///
/// struct Identity;
/// impl Codec for Identity {
///     type Value = u8;
///     type Unit = u8;
///     type DecodeError = Infallible;
///     type EncodeError = Infallible;
///     const MIN_UNITS_PER_VALUE: usize = 1;
///     const MAX_DECODE_UNITS_PER_VALUE: usize = 1;
///     const MAX_ENCODE_UNITS_PER_VALUE: usize = 1;
///     unsafe fn decode(&mut self, input: &[u8], index: usize)
///         -> Result<(u8, NonZeroUsize), DecodeFailure<Infallible>> {
///         Ok((input[index], NonZeroUsize::MIN))
///     }
///     unsafe fn encode(&mut self, value: &u8, output: &mut [u8], index: usize)
///         -> Result<usize, Infallible> {
///         output[index] = *value;
///         Ok(1)
///     }
/// }
///
/// let mut input = TranscodeDecodeInput::with_capacity(Cursor::new(vec![42_u8]), 8);
/// assert!(input.fill_until(1).expect("refilling the cursor input should succeed"));
/// assert_eq!(input.unread(), &[42]);
/// let value = input.read_decoded_with(&mut Identity, |error| match error {})?;
/// assert_eq!(value, 42);
/// # Ok::<(), std::io::Error>(())
/// ```
///
/// `read_decoded_with` reads one complete value and owns its strict
/// single-value lifecycle; use the step methods when the caller needs to
/// coordinate streaming input and output itself.
pub struct TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{
    /// Owns the unit source and retains unread units across decode operations.
    input: BufferedInput<I>,
    /// Tracks an EOF call that stopped for output capacity and must be resumed.
    eof_retry_pending: bool,
}

impl<I> TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{
    /// Creates a decoder input with the default unit buffer capacity.
    ///
    /// # Parameters
    ///
    /// * `inner` - Unit input read by this adapter.
    ///
    /// # Returns
    ///
    /// A new buffered decoder input.
    ///
    /// # Panics
    ///
    /// Panics if `I::Item::default()` panics or the default buffer capacity
    /// exceeds the supported allocation size.
    #[must_use]
    #[inline]
    pub fn new(inner: I) -> Self {
        Self {
            input: BufferedInput::new(inner),
            eof_retry_pending: false,
        }
    }

    /// Creates a decoder input with a unit buffer of at least `capacity`.
    ///
    /// # Parameters
    ///
    /// * `inner` - Unit input read by this adapter.
    /// * `capacity` - Requested internal unit buffer capacity.
    ///
    /// # Returns
    ///
    /// A new buffered decoder input.
    ///
    /// # Panics
    ///
    /// Panics if `I::Item::default()` panics or the requested capacity exceeds
    /// the supported allocation size.
    #[must_use]
    #[inline]
    pub fn with_capacity(inner: I, capacity: usize) -> Self {
        Self {
            input: BufferedInput::with_capacity(inner, capacity),
            eof_retry_pending: false,
        }
    }

    /// Creates a decoder input with a unit buffer of at least `capacity`.
    ///
    /// # Parameters
    ///
    /// * `inner` - Unit input read by this adapter.
    /// * `capacity` - Requested internal unit buffer capacity.
    ///
    /// # Returns
    ///
    /// Returns a buffered adapter owning `inner` with at least the requested
    /// capacity.
    ///
    /// # Errors
    ///
    /// Returns an allocation error when the requested buffer cannot be
    /// allocated.
    ///
    /// # Panics
    ///
    /// Panics if `I::Item::default()` panics while initializing the buffer.
    pub fn try_with_capacity(inner: I, capacity: usize) -> StdResult<Self, TryReserveError> {
        Ok(Self {
            input: BufferedInput::try_with_capacity(inner, capacity)?,
            eof_retry_pending: false,
        })
    }

    /// Returns a shared reference to the wrapped unit input.
    ///
    /// The wrapped input can be physically positioned after units that remain
    /// unread in this adapter's internal buffer.
    ///
    /// # Returns
    ///
    /// A shared reference to the wrapped unit input.
    #[must_use]
    #[inline]
    pub const fn inner(&self) -> &I {
        self.input.inner()
    }

    /// Returns the number of unread units currently buffered.
    ///
    /// # Returns
    ///
    /// The number of unread units in the internal buffer.
    #[must_use]
    #[inline]
    pub fn unread_len(&self) -> usize {
        self.input.unread_len()
    }

    /// Returns the currently buffered unread units.
    ///
    /// # Returns
    ///
    /// Returns a shared slice over the unread portion of the internal unit
    /// buffer. The slice is valid until this adapter is mutated.
    #[must_use]
    #[inline]
    pub fn unread(&self) -> &[I::Item] {
        self.input.unread()
    }

    /// Returns the internal unit buffer capacity.
    ///
    /// # Returns
    ///
    /// The maximum number of units retained in the internal buffer.
    #[must_use]
    #[inline]
    pub fn capacity(&self) -> usize {
        self.input.capacity()
    }

    /// Refills the internal buffer until at least `count` unread units are
    /// available.
    ///
    /// # Parameters
    ///
    /// * `count` - Minimum number of unread units required.
    ///
    /// # Returns
    ///
    /// Returns `true` when at least `count` units are buffered; `false` if EOF
    /// prevents reaching that count. Buffered units remain available in either
    /// case.
    ///
    /// # Errors
    ///
    /// Returns allocation errors mapped to [`ErrorKind::OutOfMemory`], or I/O
    /// errors from the wrapped input while refilling.
    pub fn fill_until(&mut self, count: usize) -> Result<bool> {
        if count > self.input.capacity() {
            self.input.try_reserve_capacity(count).map_err(allocation_error)?;
        }
        let previous_unread = self.input.unread_len();
        let result = self.input.fill_until(count);
        if self.input.unread_len() > previous_unread {
            self.eof_retry_pending = false;
        }
        result
    }

    /// Performs one decode step and preserves the transcoder stop status.
    ///
    /// `None` means that the wrapped input reached EOF with no buffered units.
    /// Consumed input is committed before this method returns. Callers can use
    /// the returned [`TranscodeProgress`] to distinguish `NeedOutput` from an
    /// incomplete input tail without guessing from the unread buffer alone.
    ///
    /// # Type Parameters
    ///
    /// - `D`: Streaming decoder accepting the source unit type.
    /// - `M`: Mapper from decoder errors to I/O errors.
    /// - `Value`: Decoded destination value type.
    ///
    /// # Parameters
    ///
    /// - `decoder`: Decoder for the current logical stream.
    /// - `map_error`: Mapper invoked for decoder errors.
    /// - `output`: Destination value storage.
    /// - `output_index`: Start of the writable range.
    /// - `count`: Maximum number of destination values available.
    ///
    /// # Returns
    ///
    /// Returns `Some` validated progress after a decode step, or `None` at EOF
    /// with no buffered units. A zero count returns `Some` zero progress.
    ///
    /// # Errors
    ///
    /// Returns invalid output-range or progress errors, input/refill errors,
    /// or decoder errors translated by `map_error`.
    /// A successful validated progress commits its `read()` count. If decoding
    /// or progress validation fails, this call does not consume the unread
    /// range. The decoder and destination may already have changed; neither is
    /// rolled back, and no complete progress report is available. A refill
    /// performed before the failure is not rolled back at the wrapped input.
    /// Do not replay the original input unless the decoder defines an explicit
    /// recovery protocol.
    pub fn transcode_step<D, M, Value>(
        &mut self,
        decoder: &mut D,
        map_error: &mut M,
        output: &mut [Value],
        output_index: usize,
        count: usize,
    ) -> Result<Option<TranscodeProgress>>
    where
        D: Transcoder<Input = I::Item, Output = Value>,
        M: FnMut(D::Error) -> Error,
    {
        let output_end = SliceRange::checked_range_end(
            output.len(),
            output_index,
            count,
            "decoded output range exceeds destination buffer",
        )?;
        if count == 0 {
            return Ok(Some(TranscodeProgress::complete(0, 0)));
        }
        if self.unread_len() == 0 && !self.fill_more()? {
            return Ok(None);
        }
        let available_input = self.unread_len();
        let progress = decoder
            .transcode(self.unread(), 0, &mut output[..output_end], output_index)
            .map_err(&mut *map_error)
            .and_then(|progress| validate_decode_progress(progress, 0, available_input, output_index, count))?;
        self.consume(progress.read());
        Ok(Some(progress))
    }

    /// Performs one decode step after the caller has established EOF.
    ///
    /// This method does not read from the wrapped input. It passes the current
    /// unread buffer to [`Transcoder::transcode_eof`], validates the returned
    /// progress, and commits consumed source units before returning.
    ///
    /// # Type Parameters
    ///
    /// - `D`: Streaming decoder accepting the source unit type.
    /// - `M`: Mapper from decoder errors to I/O errors.
    /// - `Value`: Decoded destination value type.
    ///
    /// # Parameters
    ///
    /// - `decoder`: Decoder for the current logical stream.
    /// - `map_error`: Mapper invoked for decoder errors.
    /// - `output`: Destination value storage.
    /// - `output_index`: Start of the writable range.
    /// - `count`: Maximum number of destination values available.
    ///
    /// # Returns
    ///
    /// Returns validated EOF progress. A zero output count returns zero
    /// progress without calling the decoder; an empty input is still passed to
    /// `transcode_eof` so decoders can handle EOF with retained state.
    ///
    /// # Errors
    ///
    /// Returns invalid output-range errors, decoder errors mapped by
    /// `map_error`, or `InvalidData` if the decoder requests more input after
    /// EOF. Invalid progress does not commit source consumption, but decoder
    /// state and caller-owned output are not rolled back.
    pub fn transcode_eof_step<D, M, Value>(
        &mut self,
        decoder: &mut D,
        map_error: &mut M,
        output: &mut [Value],
        output_index: usize,
        count: usize,
    ) -> Result<TranscodeProgress>
    where
        D: Transcoder<Input = I::Item, Output = Value>,
        M: FnMut(D::Error) -> Error,
    {
        let output_end = SliceRange::checked_range_end(
            output.len(),
            output_index,
            count,
            "decoded EOF output range exceeds destination buffer",
        )?;
        if count == 0 {
            return Ok(TranscodeProgress::complete(0, 0));
        }
        let available_input = self.unread_len();
        let progress = decoder
            .transcode_eof(self.unread(), 0, &mut output[..output_end], output_index)
            .map_err(&mut *map_error)
            .and_then(|progress| validate_eof_decode_progress(progress, 0, available_input, output_index, count))?;
        self.consume(progress.read());
        self.eof_retry_pending = matches!(progress.status(), TranscodeStatus::NeedOutput { .. });
        Ok(progress)
    }

    /// Consumes unread units from the current buffer window.
    ///
    /// # Parameters
    ///
    /// * `count` - Number of unread units to discard.
    ///
    /// # Panics
    ///
    /// Panics when `count` exceeds [`Self::unread_len`].
    #[inline]
    pub fn consume(&mut self, count: usize) {
        assert!(count <= self.unread_len(), "cannot consume beyond buffered input",);
        // SAFETY: The caller-provided count is within the unread window.
        unsafe {
            self.input.consume(count);
        }
    }

    /// Copies unread units into an indexed output range without consuming them.
    ///
    /// # Parameters
    ///
    /// * `output` - Destination storage that receives a copy of unread units.
    /// * `output_index` - Start index inside `output`.
    /// * `count` - Number of unread units to copy.
    ///
    /// # Safety
    ///
    /// The caller must guarantee that `output_index..output_index + count` is
    /// a valid range inside `output`, that the addition does not overflow, that
    /// `count <= self.unread_len()`, and that the destination range does not
    /// overlap with the unread units stored inside this buffer.
    pub unsafe fn copy_unread_to(&self, output: &mut [I::Item], output_index: usize, count: usize) {
        // SAFETY: The caller guarantees the destination range and non-overlap
        // requirements for the unread copy.
        let unread = self.unread();
        unsafe {
            UncheckedSlice::copy_nonoverlapping(unread, 0, output, output_index, count);
        }
    }

    /// Consumes this adapter and returns its parts.
    ///
    /// # Returns
    ///
    /// The wrapped input and the buffer holding unread units.
    #[must_use = "the returned input and unread buffer must be handled"]
    #[inline]
    pub fn into_parts(self) -> (I, Buffer<I::Item>) {
        self.input.into_parts()
    }

    /// Reads buffered units into an indexed output range.
    ///
    /// # Parameters
    ///
    /// * `output` - Destination unit storage.
    /// * `output_index` - Start index inside `output`.
    /// * `count` - Maximum number of units to read.
    ///
    /// # Returns
    ///
    /// The number of units copied into `output`.
    ///
    /// # Errors
    ///
    /// Returns input or buffer validation errors from the wrapped
    /// [`qubit_io::BufferedInput`].
    ///
    /// # Panics
    ///
    /// Debug builds panic if the destination range violates the safety
    /// contract.
    ///
    /// # Safety
    ///
    /// The caller must guarantee that `output_index..output_index + count` is
    /// a valid range inside `output` and that the addition does not overflow.
    pub unsafe fn read_unchecked(
        &mut self,
        output: &mut [I::Item],
        output_index: usize,
        count: usize,
    ) -> Result<usize> {
        debug_assert!(
            SliceRange::range_fits(output.len(), output_index, count),
            "unchecked read output range exceeds destination buffer",
        );
        if count == 0 {
            return Ok(0);
        }
        self.eof_retry_pending = false;
        // SAFETY: The caller guarantees the destination range is valid.
        unsafe { self.input.read_unchecked(output, output_index, count) }
    }

    /// Decodes one codec value from the buffered unit input.
    ///
    /// This strict convenience method supports codecs whose decode reset and
    /// finish phases do not emit values. Use
    /// [`Self::read_decoded_lifecycle_with`] when those phases have output.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec accepting the wrapped input's unit type.
    /// - `M`: Mapper from codec decode errors to I/O errors.
    ///
    /// # Parameters
    ///
    /// * `codec` - Codec used for this single-value decode.
    /// * `map_error` - Mapper for codec-domain invalid-input errors.
    ///
    /// # Returns
    ///
    /// Returns one decoded codec value.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::Unsupported`] before invoking the codec or reading
    /// input when reset or finish may emit values. Otherwise, returns I/O
    /// errors from the wrapped input, `UnexpectedEof` when EOF occurs before a
    /// complete value is available, `InvalidData` when the codec reports an
    /// impossible incomplete state, or a mapped codec-domain error for reset,
    /// invalid input, or finish failures. Each mapped error owns a
    /// [`TranscodeDomainError`] identifying the phase; main decode errors use
    /// index `0`, the start of this single-value input window. The mapper's
    /// error remains the wrapper source, preserving its kind and payload.
    ///
    /// This operation is not transactional. A successful main decode consumes
    /// its source units before codec finalization. If finalization fails, the
    /// decoded value is not returned and the consumed input is not restored.
    /// A later read must not be treated as a retry of that value. Truncated
    /// input at EOF is consumed before reporting the error. Invalid-input
    /// consumption follows the codec's validated consumption hint. Codec
    /// state is not rolled back. The `Unsupported` preflight error above is
    /// returned before invoking the codec or reading input.
    ///
    /// # Panics
    ///
    /// Panics when the codec reports more reset or finish values than its
    /// declared bounds.
    pub fn read_decoded_with<C, M>(&mut self, codec: &mut C, map_error: M) -> Result<C::Value>
    where
        C: Codec<Unit = I::Item>,
        M: FnMut(C::DecodeError) -> Error,
    {
        TranscodeFailure::ensure_no_decode_lifecycle_output::<C>()
            .map_err(|error| Error::new(ErrorKind::Unsupported, error))?;
        let progress = self.read_decoded_lifecycle_with_scratch_impl(codec, &mut [], &mut [], map_error)?;
        let (value, reset_written, finish_written) = progress.into_parts();
        debug_assert_eq!(0, reset_written);
        debug_assert_eq!(0, finish_written);
        Ok(value)
    }

    /// Decodes one complete codec lifecycle and preserves every output phase.
    ///
    /// The method allocates independent storage for values emitted by
    /// `decode_reset` and `decode_finish`, so neither phase can overwrite the
    /// other.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec accepting the wrapped input's unit type.
    /// - `M`: Mapper from codec decode errors to I/O errors.
    ///
    /// # Parameters
    ///
    /// - `codec`: Codec used to decode one complete lifecycle.
    /// - `map_error`: Maps codec decode errors to I/O errors.
    ///
    /// # Returns
    ///
    /// Returns reset output, the main decoded value, and finish output.
    ///
    /// # Errors
    ///
    /// Returns I/O errors from the wrapped input, `UnexpectedEof` when EOF
    /// occurs before a complete value is available, `InvalidData` when the
    /// codec reports an impossible incomplete state, or a mapped codec-domain
    /// error for reset, invalid input, or finish failures. Each mapped error
    /// owns a [`TranscodeDomainError`] identifying the phase; main decode
    /// errors use index `0`, the start of this input window. The mapper's error
    /// remains the wrapper source, preserving its kind and payload.
    /// Returns `OutOfMemory` when lifecycle output storage cannot be reserved.
    ///
    /// This operation is not transactional. A successful main decode consumes
    /// its source units before codec finalization. If finalization fails, the
    /// decoded value is not returned and the consumed input is not restored.
    /// A later read must not be treated as a retry of that value. Truncated
    /// input at EOF is consumed before reporting the error. Invalid-input
    /// consumption follows the codec's validated consumption hint. Codec
    /// state is not rolled back.
    ///
    /// # Panics
    ///
    /// Panics when the codec reports more reset or finish values than its
    /// declared bounds.
    pub fn read_decoded_lifecycle_with<C, M>(
        &mut self,
        codec: &mut C,
        map_error: M,
    ) -> Result<DecodeLifecycleOutput<C::Value>>
    where
        C: Codec<Unit = I::Item>,
        C::Value: Default,
        M: FnMut(C::DecodeError) -> Error,
    {
        assert_unit_bounds::<C>();
        let mut reset_output = Vec::new();
        try_reserve_vec(&mut reset_output, C::MAX_DECODE_RESET_VALUES).map_err(allocation_error)?;
        reset_output.resize_with(C::MAX_DECODE_RESET_VALUES, C::Value::default);
        let mut finish_output = Vec::new();
        try_reserve_vec(&mut finish_output, C::MAX_DECODE_FINISH_VALUES).map_err(allocation_error)?;
        finish_output.resize_with(C::MAX_DECODE_FINISH_VALUES, C::Value::default);
        let progress =
            self.read_decoded_lifecycle_with_scratch_impl(codec, &mut reset_output, &mut finish_output, map_error)?;
        let (value, reset_written, finish_written) = progress.into_parts();
        reset_output.truncate(reset_written);
        finish_output.truncate(finish_written);
        Ok(DecodeLifecycleOutput::new(reset_output, value, finish_output))
    }

    /// Decodes one complete codec lifecycle into separate caller storage.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec accepting the wrapped input's unit type.
    /// - `M`: Mapper from codec decode errors to I/O errors.
    ///
    /// # Parameters
    ///
    /// - `codec`: Codec used to decode one complete lifecycle.
    /// - `reset_output`: Reusable storage for values emitted by
    ///   [`Codec::decode_reset`].
    /// - `finish_output`: Reusable storage for values emitted by
    ///   [`Codec::decode_finish`].
    /// - `map_error`: Maps codec decode errors to I/O errors.
    ///
    /// # Returns
    ///
    /// Returns the main decoded value and the initialized lengths of both
    /// lifecycle output buffers.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::InvalidInput`] when either output buffer is shorter
    /// than the corresponding codec bound. Returns I/O errors from the wrapped
    /// input, `UnexpectedEof` when EOF occurs before a complete value is
    /// available, `InvalidData` when the codec reports an impossible
    /// incomplete state, or a mapped codec-domain error for reset, invalid
    /// input, or finish failures. Each mapped error owns a
    /// [`TranscodeDomainError`] identifying the phase; main decode errors use
    /// index `0`, the start of this input window. The mapper's error remains
    /// the wrapper source, preserving its kind and payload.
    ///
    /// This operation is not transactional. A successful main decode consumes
    /// its source units before codec finalization. If finalization fails, the
    /// decoded value is not returned and the consumed input is not restored.
    /// A later read must not be treated as a retry of that value. Truncated
    /// input at EOF is consumed before reporting the error. Invalid-input
    /// consumption follows the codec's validated consumption hint. Codec
    /// state is not rolled back. A short scratch buffer is rejected before
    /// invoking the codec or reading input. Reset and finish output buffers
    /// may already have changed when an error is returned; the error carries
    /// no valid output lengths, so their full contents must not be treated as
    /// this operation's successful output. Recovery of codec state after an
    /// error is codec-specific, and consumed input is never restored.
    ///
    /// # Panics
    ///
    /// Panics when the codec reports more reset or finish values than its
    /// declared bounds.
    pub fn read_decoded_lifecycle_with_scratch<C, M>(
        &mut self,
        codec: &mut C,
        reset_output: &mut [C::Value],
        finish_output: &mut [C::Value],
        map_error: M,
    ) -> Result<DecodeLifecycleProgress<C::Value>>
    where
        C: Codec<Unit = I::Item>,
        M: FnMut(C::DecodeError) -> Error,
    {
        self.read_decoded_lifecycle_with_scratch_impl(codec, reset_output, finish_output, map_error)
    }

    /// Runs decoder reset into an indexed output range.
    ///
    /// This method does not read or consume buffered input units.
    ///
    /// # Type Parameters
    ///
    /// - `D`: Streaming decoder accepting the source unit type.
    /// - `M`: Mapper from decoder errors to I/O errors.
    /// - `Value`: Decoded destination value type.
    ///
    /// # Parameters
    ///
    /// - `decoder`: Decoder for the current logical stream.
    /// - `map_error`: Mapper invoked for decoder errors.
    /// - `output`: Destination value storage.
    /// - `output_index`: Start of the writable range.
    /// - `count`: Maximum number of destination values available.
    ///
    /// # Returns
    ///
    /// Returns the number of reset values initialized in the requested range.
    ///
    /// # Errors
    ///
    /// Returns invalid output ranges, insufficient declared output capacity,
    /// capacity errors, or reset errors mapped by `map_error`.
    ///
    /// # Panics
    ///
    /// Panics when the decoder reports writing more values than its declared
    /// reset bound.
    pub fn reset<D, M, Value>(
        &self,
        decoder: &mut D,
        map_error: &mut M,
        output: &mut [Value],
        output_index: usize,
        count: usize,
    ) -> Result<usize>
    where
        D: Transcoder<Input = I::Item, Output = Value>,
        M: FnMut(D::Error) -> Error,
    {
        let required = decoder.max_reset_output_len().map_err(capacity_error_to_invalid_data)?;
        let output_end = SliceRange::checked_range_end(
            output.len(),
            output_index,
            count,
            "reset output range exceeds destination buffer",
        )?;
        if count < required {
            return Err(Error::new(
                ErrorKind::InvalidData,
                "insufficient output for decoder reset bound",
            ));
        }
        let output = &mut output[..output_end];
        let written = decoder.reset(output, output_index).map_err(&mut *map_error)?;
        assert!(written <= required, "reset wrote beyond its bound");
        Ok(written)
    }

    /// Decodes values into an indexed output range using a streaming
    /// [`Transcoder`].
    ///
    /// # Type Parameters
    ///
    /// - `D`: Streaming decoder accepting the source unit type.
    /// - `M`: Mapper from decoder errors to I/O errors.
    /// - `Value`: Decoded destination value type.
    ///
    /// # Parameters
    ///
    /// * `decoder` - Streaming decoder used for this operation.
    /// * `map_error` - Function mapping transcode errors into I/O errors.
    /// * `output` - Destination value storage.
    /// * `output_index` - Start index inside `output`.
    /// * `count` - Maximum number of values to write.
    ///
    /// # Returns
    ///
    /// The number of values written. When this method is driven through EOF
    /// with output capacity remaining, it passes the retained tail—or an empty
    /// input when no tail remains—to [`Transcoder::transcode_eof`] before
    /// returning.
    /// A short return, including zero, may mean the decoder requires a larger
    /// contiguous output range. It does not prove conversion is complete. Use
    /// [`Self::transcode_step`] and [`Self::transcode_eof_step`] when the stop
    /// reason and required capacity must remain observable.
    ///
    /// # Errors
    ///
    /// Returns input errors, invalid output ranges, capacity errors from the
    /// internal buffer, or transcode errors mapped by `map_error`.
    /// This operation is not transactional. An error may be returned after
    /// source units have been consumed and values have been written to
    /// output. Progress is not rolled back, and the error does not report
    /// the accumulated output length. Use `transcode_step` and commit each
    /// successful progress result when previously decoded values must
    /// remain observable after a later failure.
    /// The method does not refill for later values once the requested output
    /// range is full; the underlying input may still prefetch units beyond
    /// that range during an earlier read. If EOF processing stops with
    /// `NeedOutput`, the next batch call resumes EOF processing directly;
    /// a short return, including zero, does not mean conversion is complete.
    /// Use the step methods when the exact stop reason is needed. Explicitly
    /// refilling new units, seeking, or switching to raw/single-value reads
    /// changes the input context; callers remain responsible for the decoder
    /// lifecycle when continuing after such a switch.
    pub fn transcode<D, M, Value>(
        &mut self,
        decoder: &mut D,
        map_error: &mut M,
        output: &mut [Value],
        output_index: usize,
        count: usize,
    ) -> Result<usize>
    where
        D: Transcoder<Input = I::Item, Output = Value>,
        M: FnMut(D::Error) -> Error,
    {
        let output_end = SliceRange::checked_range_end(
            output.len(),
            output_index,
            count,
            "decoded output range exceeds destination buffer",
        )?;
        if count == 0 {
            return Ok(0);
        }
        if self.eof_retry_pending {
            return self
                .transcode_eof_step(decoder, map_error, output, output_index, count)
                .map(|progress| progress.written());
        }
        let output = &mut output[..output_end];
        let mut written_total = 0;
        loop {
            if self.unread_len() == 0 && !self.fill_more()? {
                let remaining_output = count - written_total;
                let eof_progress = self.transcode_eof_step(
                    decoder,
                    map_error,
                    output,
                    output_index + written_total,
                    remaining_output,
                )?;
                written_total += eof_progress.written();
                return Ok(written_total);
            }
            let units = self.unread();
            let available_input = units.len();
            let remaining_output = count - written_total;
            let progress = decoder
                .transcode(units, 0, output, output_index + written_total)
                .map_err(&mut *map_error)?;
            let progress = validate_decode_progress(
                progress,
                0,
                available_input,
                output_index + written_total,
                remaining_output,
            )?;
            let consumed = progress.read();
            let written = progress.written();
            self.consume(consumed);
            written_total += written;
            if written_total == count {
                return Ok(written_total);
            }
            match progress.status() {
                TranscodeStatus::Complete => {}
                TranscodeStatus::NeedOutput { .. } => {
                    return Ok(written_total);
                }
                TranscodeStatus::NeedInput { required, .. } => {
                    if self.fill_until(required.get())? {
                        continue;
                    }
                    let remaining_output = count - written_total;
                    let eof_progress = self.transcode_eof_step(
                        decoder,
                        map_error,
                        output,
                        output_index + written_total,
                        remaining_output,
                    )?;
                    written_total += eof_progress.written();
                    return Ok(written_total);
                }
            }
        }
    }

    /// Finishes a streaming decoder into an indexed output range.
    ///
    /// # Type Parameters
    ///
    /// - `D`: Streaming decoder accepting the source unit type.
    /// - `M`: Mapper from decoder errors to I/O errors.
    /// - `Value`: Decoded destination value type.
    ///
    /// # Parameters
    ///
    /// * `decoder` - Streaming decoder whose final output is being collected.
    /// * `map_error` - Function mapping transcode errors into I/O errors.
    /// * `output` - Destination value storage.
    /// * `output_index` - Start index inside `output`.
    /// * `count` - Maximum number of finish values to write.
    ///
    /// # Returns
    ///
    /// The number of values written by the decoder finish operation.
    ///
    /// # Errors
    ///
    /// Returns invalid output ranges, capacity errors, or transcode
    /// finalization errors mapped to I/O errors.
    ///
    /// # Panics
    ///
    /// Panics when the decoder reports writing more values than its
    /// [`Transcoder::max_finish_output_len`] bound.
    pub fn finish<D, M, Value>(
        &self,
        decoder: &mut D,
        map_error: &mut M,
        output: &mut [Value],
        output_index: usize,
        count: usize,
    ) -> Result<usize>
    where
        D: Transcoder<Input = I::Item, Output = Value>,
        M: FnMut(D::Error) -> Error,
    {
        let required = decoder
            .max_finish_output_len()
            .map_err(capacity_error_to_invalid_data)?;
        // Validate the caller-supplied count range first (InvalidInput).
        let output_end = SliceRange::checked_range_end(
            output.len(),
            output_index,
            count,
            "finish output range exceeds destination buffer",
        )?;
        // `count` is the caller's declared writable finish range.  The
        // destination slice may be larger, but passing extra capacity to the
        // decoder would allow it to write beyond the range the caller granted.
        if count < required {
            return Err(Error::new(
                ErrorKind::InvalidData,
                "insufficient output for decoder finish bound",
            ));
        }
        let output = &mut output[..output_end];
        let written = decoder.finish(output, output_index).map_err(&mut *map_error)?;
        assert!(written <= required, "finish wrote beyond its bound");
        Ok(written)
    }
}

impl<I> TranscodeDecodeInput<I>
where
    I: SeekableByteInput,
{
    /// Seeks the wrapped byte input and discards buffered bytes after success.
    ///
    /// # Parameters
    ///
    /// * `position` - Target seek position.
    ///
    /// # Returns
    ///
    /// The new stream position reported by the wrapped input.
    ///
    /// # Errors
    ///
    /// Returns seek errors from the wrapped input.
    #[inline]
    pub fn seek(&mut self, position: SeekFrom) -> Result<u64> {
        let position = self.input.seek_to(position)?;
        self.eof_retry_pending = false;
        Ok(position)
    }
}

impl<I> TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{
    /// Reads and decodes reset, body, and finish output using caller scratch
    /// buffers.
    ///
    /// This internal path keeps lifecycle allocation and error mapping in one
    /// place for the public convenience methods.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec accepting the wrapped input's unit type.
    /// - `M`: Mapper from codec decode errors to I/O errors.
    ///
    /// # Parameters
    ///
    /// - `codec`: Codec whose reset, decode, and finish phases are executed.
    /// - `reset_output`: Separate storage for reset values.
    /// - `finish_output`: Separate storage for finish values.
    /// - `map_error`: Mapper for codec decode errors.
    ///
    /// # Returns
    ///
    /// Returns the decoded value and initialized lengths of both output
    /// buffers.
    ///
    /// # Errors
    ///
    /// Returns InvalidInput for insufficient scratch capacity, input I/O
    /// errors, UnexpectedEof for a truncated value, InvalidData for invalid
    /// codec progress, or mapped codec reset, decode, and finish errors. Each
    /// mapped codec-domain error owns a [`TranscodeDomainError`] identifying
    /// the phase; main decode errors use index `0`, the start of this input
    /// window. The mapper's error remains the wrapper source.
    ///
    /// # Panics
    ///
    /// Panics if reset or finish reports output beyond its declared bound.
    fn read_decoded_lifecycle_with_scratch_impl<C, M>(
        &mut self,
        codec: &mut C,
        reset_output: &mut [C::Value],
        finish_output: &mut [C::Value],
        mut map_error: M,
    ) -> Result<DecodeLifecycleProgress<C::Value>>
    where
        C: Codec<Unit = I::Item>,
        M: FnMut(C::DecodeError) -> Error,
    {
        assert_unit_bounds::<C>();
        if reset_output.len() < C::MAX_DECODE_RESET_VALUES {
            return Err(Error::new(
                ErrorKind::InvalidInput,
                "decode reset output is shorter than the codec reset bound",
            ));
        }
        if finish_output.len() < C::MAX_DECODE_FINISH_VALUES {
            return Err(Error::new(
                ErrorKind::InvalidInput,
                "decode finish output is shorter than the codec finish bound",
            ));
        }
        self.eof_retry_pending = false;
        let mut map_domain_error = |error: TranscodeDomainError<C::DecodeError>| {
            let contextual = error.map_source(&mut map_error);
            Error::new(contextual.source().kind(), contextual)
        };
        let reset_written = unsafe {
            // SAFETY: The reset output length check above reserves the codec's
            // declared decode-reset output bound.
            codec.decode_reset(reset_output, 0)
        }
        .map_err(|source| map_domain_error(TranscodeDomainError::reset(source)))?;
        assert!(
            reset_written <= C::MAX_DECODE_RESET_VALUES,
            "Codec::decode_reset wrote beyond its reset bound",
        );

        let value = CodecDecodeDriver::new(&mut self.input).read_one(codec, &mut |source| {
            map_domain_error(TranscodeDomainError::main(source, 0))
        })?;

        let finish_written = unsafe {
            // SAFETY: The finish output length check above reserves the
            // codec's declared decode-finish output bound.
            codec.decode_finish(finish_output, 0)
        }
        .map_err(|source| map_domain_error(TranscodeDomainError::finish(source)))?;
        assert!(
            finish_written <= C::MAX_DECODE_FINISH_VALUES,
            "Codec::decode_finish wrote beyond its finish bound",
        );
        Ok(DecodeLifecycleProgress::new(value, reset_written, finish_written))
    }

    /// Refills the underlying buffer.
    ///
    /// # Returns
    ///
    /// Returns `true` if unread input is available after refill, or `false` at
    /// EOF.
    ///
    /// # Errors
    ///
    /// Propagates errors from the wrapped input while refilling.
    #[inline]
    fn fill_more(&mut self) -> Result<bool> {
        let result = self.input.fill_more();
        if matches!(result, Ok(true)) {
            self.eof_retry_pending = false;
        }
        result
    }
}

impl<I> Read for TranscodeDecodeInput<I>
where
    I: ByteInput,
{
    /// Reads raw bytes through the internal buffer.
    ///
    /// # Parameters
    ///
    /// - `output`: Destination for raw buffered bytes.
    ///
    /// # Returns
    ///
    /// Returns the number of bytes read; zero indicates EOF or an empty
    /// destination.
    ///
    /// # Errors
    ///
    /// Propagates wrapped input or buffer errors.
    #[inline]
    fn read(&mut self, output: &mut [u8]) -> Result<usize> {
        // SAFETY: The full output slice is a valid destination range.
        unsafe { self.read_unchecked(output, 0, output.len()) }
    }
}

impl<I> Seek for TranscodeDecodeInput<I>
where
    I: SeekableByteInput,
{
    /// Seeks the wrapped byte input and discards buffered bytes after success.
    ///
    /// # Parameters
    ///
    /// - `position`: Target byte-stream position.
    ///
    /// # Returns
    ///
    /// Returns the new byte offset after clearing buffered data.
    ///
    /// # Errors
    ///
    /// Propagates wrapped seek errors, preserving the buffer when seeking
    /// fails.
    #[inline]
    fn seek(&mut self, position: SeekFrom) -> Result<u64> {
        self.seek(position)
    }
}

impl<I> Debug for TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
    BufferedInput<I>: Debug,
{
    /// Formats this buffered decode input for debugging.
    ///
    /// # Parameters
    ///
    /// - `formatter`: Formatting sink receiving the struct and owned input.
    ///
    /// # Returns
    ///
    /// Returns success after writing the debug representation.
    ///
    /// # Errors
    ///
    /// Propagates a formatting error from the sink or wrapped input.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FormatResult {
        formatter
            .debug_struct("TranscodeDecodeInput")
            .field("input", &self.input)
            .finish()
    }
}