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