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#[derive(Clone, Copy, Debug, Eq, Error, Hash, PartialEq)]
17#[non_exhaustive]
18pub enum TranscodeContractError {
19    /// The transcoder consumed more input units than the caller supplied.
20    #[error("transcoder consumed {read} units but only {available} were available")]
21    OverRead {
22        /// Input units reported as consumed.
23        read: usize,
24        /// Input units available to the transcode call.
25        available: usize,
26    },
27
28    /// The transcoder wrote more output units than the caller supplied.
29    #[error("transcoder wrote {written} units but only {available} output slots were available")]
30    OverWritten {
31        /// Output units reported as written.
32        written: usize,
33        /// Output slots available to the transcode call.
34        available: usize,
35    },
36
37    /// Progress could not be represented as an absolute index.
38    #[error("transcoder progress overflow: index {index} plus advanced {advanced}")]
39    ProgressIndexOverflow {
40        /// Absolute index supplied to the transcode call.
41        index: usize,
42        /// Relative progress reported by the transcoder.
43        advanced: usize,
44    },
45
46    /// A status requested input or output that is already available.
47    #[error("transcoder reported required {required} with available {available}")]
48    SatisfiedNeed {
49        /// Required units reported by the status.
50        required: usize,
51        /// Available units reported by the status.
52        available: usize,
53    },
54
55    /// A `Complete` status left visible input unconsumed.
56    #[error("transcoder reported Complete after consuming {read} of {available} available input units")]
57    CompleteWithRemainingInput {
58        /// Input units reported as consumed.
59        read: usize,
60        /// Input units available to the transcode call.
61        available: usize,
62    },
63}
qubit_codec/transcode/transcode_contract_error.rs

qubit_codec/transcode/
transcode_contract_error.rs
