qubit_json/value/traverse/
json_tree_mutate_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// =============================================================================
8//! Defines failures produced while mutating JSON trees.
9
10use std::fmt::Debug;
11
12use qubit_budget::MeasuredBudgetError;
13use thiserror::Error;
14
15/// Identifies the phase that failed during a budget-aware JSON tree mutation.
16///
17/// Input and output budgets are deliberately separate so callers can decide
18/// which transaction, if any, remains eligible for commit after a failure.
19///
20/// # Type Parameters
21///
22/// * `R` - Resource identity attached to budget failures.
23/// * `Q` - Quantity representation attached to budget failures.
24/// * `E` - Error type returned by the mutation visitor.
25///
26/// # Examples
27///
28/// ```
29/// use qubit_json::value::traverse::JsonTreeMutateError;
30///
31/// let error: JsonTreeMutateError<(), usize, &str> =
32///     JsonTreeMutateError::Visitor("mutation rejected");
33/// assert!(matches!(error, JsonTreeMutateError::Visitor(_)));
34/// ```
35#[must_use]
36#[derive(Debug, Error)]
37pub enum JsonTreeMutateError<R, Q, E>
38where
39    Q: Copy + Debug,
40{
41    /// The complete tree before mutation exceeded its input budget.
42    #[error("JSON tree input budget rejected the original value")]
43    InputBudget(
44        /// Resource measurement for the original tree.
45        #[source]
46        MeasuredBudgetError<R, Q>,
47    ),
48    /// The caller-defined visitor failed after mutation began.
49    #[error("JSON tree mutation visitor failed")]
50    Visitor(
51        /// Domain error returned after the visitor began mutating the tree.
52        E,
53    ),
54    /// The complete tree after mutation exceeded its output budget.
55    #[error("JSON tree output budget rejected the mutated value")]
56    OutputBudget(
57        /// Resource measurement for the mutated tree.
58        #[source]
59        MeasuredBudgetError<R, Q>,
60    ),
61}
qubit_json/value/traverse/json_tree_mutate_error.rs

qubit_json/value/traverse/
json_tree_mutate_error.rs
