qubit_codec/transcode/
transcode_contract_error.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8use thiserror::Error;
9
10/// Error reported when a transcoder returns inconsistent progress.
11///
12/// This error represents a broken [`crate::Transcoder`] implementation rather
13/// than malformed input data. Buffered drivers call
14/// [`crate::TranscodeProgress::validate`] before trusting progress counters for
15/// unchecked buffer cursor movement.
16///
17/// # Examples
18///
19/// ```
20/// use qubit_codec::TranscodeContractError;
21///
22/// let error = TranscodeContractError::OverRead { read: 2, available: 1 };
23/// assert_eq!(error.to_string(), "transcoder consumed 2 units but only 1 were available");
24/// ```
25#[derive(Clone, Copy, Debug, Eq, Error, Hash, PartialEq)]
26#[non_exhaustive]
27#[must_use]
28pub enum TranscodeContractError {
29    /// The transcoder consumed more input units than the caller supplied.
30    #[error("transcoder consumed {read} units but only {available} were available")]
31    OverRead {
32        /// Input units reported as consumed.
33        read: usize,
34        /// Input units available to the transcode call.
35        available: usize,
36    },
37
38    /// The transcoder wrote more output units than the caller supplied.
39    #[error("transcoder wrote {written} units but only {available} output slots were available")]
40    OverWritten {
41        /// Output units reported as written.
42        written: usize,
43        /// Output slots available to the transcode call.
44        available: usize,
45    },
46
47    /// Progress could not be represented as an absolute index.
48    #[error("transcoder progress overflow: index {index} plus advanced {advanced}")]
49    ProgressIndexOverflow {
50        /// Absolute index supplied to the transcode call.
51        index: usize,
52        /// Relative progress reported by the transcoder.
53        advanced: usize,
54    },
55
56    /// A status requested input or output that is already available.
57    #[error("transcoder reported required {required} with available {available}")]
58    SatisfiedNeed {
59        /// Required units reported by the status.
60        required: usize,
61        /// Available units reported by the status.
62        available: usize,
63    },
64
65    /// A `Complete` status left visible input unconsumed.
66    #[error("transcoder reported Complete after consuming {read} of {available} available input units")]
67    CompleteWithRemainingInput {
68        /// Input units reported as consumed.
69        read: usize,
70        /// Input units available to the transcode call.
71        available: usize,
72    },
73}
qubit_codec/transcode/transcode_contract_error.rs

qubit_codec/transcode/
transcode_contract_error.rs
