Skip to main content

muse_code_sdk/msp/
error.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::capability::CapabilityName;
4use crate::msp::envelope::JsonObject;
5pub use kind::ErrorKind;
6pub use registry::ErrorCode;
7use serde::Deserialize;
8use serde::Serialize;
9
10pub(crate) mod kind;
11pub(crate) mod registry;
12
13/// Approval-stage token carried in the protocol spec params and
14/// stale-requirement errors.
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
16#[serde(rename_all = "camelCase")]
17pub struct ApprovalRequirementRef {
18    pub approval_id: String,
19    pub source_index: usize,
20}
21
22/// Winning terminal returned to a losing `approval/decide` command.
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "camelCase")]
25#[non_exhaustive]
26pub struct ApprovalResolutionSummary {
27    pub decision: String,
28    pub resolved_by: String,
29    pub view_cursor: String,
30}
31
32/// Winning terminal returned to a late user-input command.
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "camelCase")]
35#[non_exhaustive]
36pub struct UserInputSettlementSummary {
37    pub outcome: String,
38    pub view_cursor: String,
39}
40
41/// Winning terminal returned to a losing `admission/decide` command:
42/// `resolvedBy` is omitted on timeout.
43#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
44#[serde(rename_all = "camelCase")]
45#[non_exhaustive]
46pub struct AdmissionResolutionSummary {
47    pub decision: String,
48    #[serde(default, skip_serializing_if = "Option::is_none")]
49    pub resolved_by: Option<String>,
50    pub view_cursor: String,
51}
52
53/// Deserialize a PRESENT member into the presence-tracking double-`Option`:
54/// serde only calls this when the key exists, so an explicit JSON null becomes
55/// `Some(None)` while an absent key stays `None` via `#[serde(default)]`.
56/// Serialization is symmetric — `Some(None)` emits the explicit null, `None`
57/// skips the key.
58fn present_member<'de, D, T>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
59where
60    D: serde::Deserializer<'de>,
61    T: Deserialize<'de>,
62{
63    Option::<T>::deserialize(deserializer).map(Some)
64}
65
66/// The optional `error.data` object. All members additive-optional; `kind` is
67/// always present when `data` is.
68#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
69#[serde(rename_all = "camelCase")]
70#[non_exhaustive]
71pub struct ErrorData {
72    /// The stable camelCase category clients branch on.
73    pub kind: ErrorKind,
74    /// Whether retrying can succeed (e.g. `overloaded`). When present,
75    /// overrides the error table row's `retryable` default for this code.
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub retryable: Option<bool>,
78    /// the protocol spec descriptor, on `experimentalRequired` errors.
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub descriptor: Option<String>,
81    /// The missing capability, on `capabilityRequired` errors. Typed on the
82    /// grantable registry, so `rawLog` is outside the v1 domain and joins it as
83    /// an additive open-enum extension when the protocol spec un-defers.
84    #[serde(skip_serializing_if = "Option::is_none")]
85    pub capability: Option<CapabilityName>,
86    /// The rejected command's identifier, on `commandRejected` errors. The
87    /// ratified v1 contract pairs it with `reason`, so a client can settle the
88    /// exact command it sent without parsing the message string.
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub command_id: Option<String>,
91    /// Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a
92    /// missing view-cursor anchor).
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub reason: Option<String>,
95    /// The exceeded byte limit, on `inputTooLarge` errors.
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub limit_bytes: Option<u64>,
98    /// The blocked view position on `pageEventTooLarge` errors.
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub view_cursor: Option<String>,
101    /// The item whose stored output was requested, on the `item/readOutput`
102    /// arms (`notFound`, `outputUnavailable`, and the misaligned-offset
103    /// `invalidParams`).
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub item_id: Option<String>,
106    /// The requested `outputRef.id`, on the same `item/readOutput` arms.
107    #[serde(skip_serializing_if = "Option::is_none")]
108    pub output_ref: Option<String>,
109    /// The stored output's availability on `outputUnavailable` — the durable
110    /// `ToolOutputAvailability` value, read-time-derived when the durable
111    /// record still says `available`.
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub availability: Option<String>,
114    /// The next provable UTF-8 boundary on a misaligned text-media
115    /// `item/readOutput` read: absent when no boundary is provable from the
116    /// stored bytes ahead.
117    #[serde(skip_serializing_if = "Option::is_none")]
118    pub aligned_next_offset: Option<u64>,
119    /// The configured command-admission bound, on `backpressured` errors.
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub capacity: Option<u64>,
122    /// Free-form additive detail.
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub details: Option<JsonObject>,
125    /// Session identity on errors whose lookup is session-scoped.
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub session_id: Option<String>,
128    /// The original recovery-dependent construction's coherent observation.
129    /// An absent or unusable observation establishes no supported recovery.
130    #[serde(
131        default,
132        deserialize_with = "crate::msp::method::lifecycle::deserialize_optional_recovery_observation",
133        skip_serializing_if = "Option::is_none"
134    )]
135    pub recovery_observation: Option<crate::msp::method::lifecycle::RecoveryObservation>,
136    /// The rejected skill selector on `skillNotFound`.
137    #[serde(skip_serializing_if = "Option::is_none")]
138    pub selector: Option<String>,
139    /// The rejected marketplace name on `marketplaceNotFound` and
140    /// `marketplaceAlreadyExists`; the rejected plugin name on
141    /// `pluginNotFound`.
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub name: Option<String>,
144    /// The store on `pluginNotFound`.
145    #[serde(skip_serializing_if = "Option::is_none")]
146    pub marketplace: Option<String>,
147    /// The rejected upload id on `uploadNotFound`.
148    #[serde(skip_serializing_if = "Option::is_none")]
149    pub upload_id: Option<String>,
150    /// The oldest servable view position on `viewTruncated`; served as an
151    /// explicit `null` when nothing before the head is servable — the null is
152    /// present on the wire, never a dropped key.
153    #[serde(
154        default,
155        skip_serializing_if = "Option::is_none",
156        deserialize_with = "present_member"
157    )]
158    pub earliest_cursor: Option<Option<String>>,
159    /// The rejected anchor value on `notFound`/`missingAnchor` and the `-32042`
160    /// boundary arms; on `-32042` it is served as an explicit `null` when the
161    /// request named no concrete anchor.
162    #[serde(
163        default,
164        skip_serializing_if = "Option::is_none",
165        deserialize_with = "present_member"
166    )]
167    pub anchor: Option<Option<String>>,
168    /// The latest installed boundary's view cursor on the `-32042` arms —
169    /// always present in the `-32042` JSON and explicitly `null` when no
170    /// boundary exists.
171    #[serde(
172        default,
173        skip_serializing_if = "Option::is_none",
174        deserialize_with = "present_member"
175    )]
176    pub latest_boundary_cursor: Option<Option<String>>,
177    /// Rejected inclusive fork boundary on `forkBoundaryInvalid`.
178    #[serde(skip_serializing_if = "Option::is_none")]
179    pub last_turn_id: Option<String>,
180    /// The branch-seed path the host read before rejecting, on
181    /// branch-validation rejections: one of `runtime_checkpoint_tail`,
182    /// `runtime_full_replay`, `legacy_session_data` — the durable branch-seed
183    /// vocabulary, so the client cites the real seed decision instead of
184    /// guessing at a stale binary.
185    #[serde(skip_serializing_if = "Option::is_none")]
186    pub seed_path: Option<String>,
187    /// Why the branch seed did not use a checkpoint, on the same arms:
188    /// one of `no_usable_checkpoint`, `unsupported_checkpoint_shape`,
189    /// `checkpoint_has_model_visible_tail`, `checkpoint_missing_suffix`;
190    /// absent when the seed used a checkpoint or no fallback was recorded.
191    #[serde(skip_serializing_if = "Option::is_none")]
192    pub seed_fallback_reason: Option<String>,
193    /// Candidate retained paths on `sessionAmbiguous`.
194    #[serde(skip_serializing_if = "Option::is_none")]
195    pub paths: Option<Vec<String>>,
196    /// Approval identity on the protocol spec errors.
197    #[serde(skip_serializing_if = "Option::is_none")]
198    pub approval_id: Option<String>,
199    /// Winning resolution on `approvalAlreadyResolved`.
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub resolution: Option<ApprovalResolutionSummary>,
202    /// Current stage token on `approvalRequirementStale`.
203    #[serde(skip_serializing_if = "Option::is_none")]
204    pub current_requirement_id: Option<ApprovalRequirementRef>,
205    /// Rejected server-minted choice on `approvalChoiceInvalid`.
206    #[serde(skip_serializing_if = "Option::is_none")]
207    pub choice_id: Option<String>,
208    /// User-input prompt identity on the protocol spec errors.
209    #[serde(skip_serializing_if = "Option::is_none")]
210    pub user_input_id: Option<String>,
211    /// Winning settlement on `userInputAlreadySettled`.
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub settlement: Option<UserInputSettlementSummary>,
214    /// Admission identity on admission errors.
215    #[serde(skip_serializing_if = "Option::is_none")]
216    pub admission_id: Option<String>,
217    /// Winning resolution on `admissionAlreadyResolved`.
218    #[serde(skip_serializing_if = "Option::is_none")]
219    pub admission_resolution: Option<AdmissionResolutionSummary>,
220    /// The rejected raw-log stream, on the anchor arms (`missingAnchor`,
221    /// `prunedPrefix`, `unknownStream`).
222    #[serde(skip_serializing_if = "Option::is_none")]
223    pub stream: Option<crate::msp::view::StreamRef>,
224    /// The rejected raw-log anchor, on `missingAnchor`, `prunedPrefix`,
225    /// and `wrongStream`.
226    #[serde(skip_serializing_if = "Option::is_none")]
227    pub after: Option<crate::msp::view::RecordPosition>,
228    /// The earliest readable position, on `prunedPrefix`.
229    #[serde(skip_serializing_if = "Option::is_none")]
230    pub next_available: Option<crate::msp::view::RecordPosition>,
231    /// The requested stream, on `wrongStream`.
232    #[serde(skip_serializing_if = "Option::is_none")]
233    pub requested_stream: Option<crate::msp::view::StreamRef>,
234    /// The stream the anchor's id actually belongs to, on `wrongStream`.
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub cursor_stream: Option<crate::msp::view::StreamRef>,
237    /// The unregistered projection name, on `unknownProjection`.
238    #[serde(skip_serializing_if = "Option::is_none")]
239    pub projection: Option<String>,
240    /// The subject repository path, on `workspaceNotTrusted`.
241    #[serde(skip_serializing_if = "Option::is_none")]
242    pub path: Option<String>,
243    /// The rejected settings key path, on the `settings/writeValue` and
244    /// `settings/writeMany` arms: the structural `-32602 invalidParams` shape
245    /// and the `-32030` managed-denial block. File spelling verbatim, like the
246    /// request's `keyPath`.
247    #[serde(skip_serializing_if = "Option::is_none")]
248    pub key_path: Option<String>,
249    /// The rejected edit's index into the `settings/writeMany` `edits`
250    /// array, on the same arms; absent on `settings/writeValue`, which
251    /// carries no edit list.
252    #[serde(skip_serializing_if = "Option::is_none")]
253    pub index: Option<u64>,
254}
255
256impl ErrorData {
257    /// A `kind`-only payload with every optional field `None` — the one
258    /// constructor call sites extend with struct-update syntax, so an
259    /// additive SS field touches this file alone, never every literal.
260    #[must_use]
261    pub const fn new(kind: ErrorKind) -> Self {
262        Self {
263            kind,
264            retryable: None,
265            descriptor: None,
266            capability: None,
267            command_id: None,
268            reason: None,
269            limit_bytes: None,
270            view_cursor: None,
271            item_id: None,
272            output_ref: None,
273            availability: None,
274            aligned_next_offset: None,
275            capacity: None,
276            details: None,
277            session_id: None,
278            recovery_observation: None,
279            selector: None,
280            name: None,
281            marketplace: None,
282            upload_id: None,
283            earliest_cursor: None,
284            anchor: None,
285            latest_boundary_cursor: None,
286            last_turn_id: None,
287            seed_path: None,
288            seed_fallback_reason: None,
289            paths: None,
290            approval_id: None,
291            resolution: None,
292            current_requirement_id: None,
293            choice_id: None,
294            user_input_id: None,
295            settlement: None,
296            admission_id: None,
297            admission_resolution: None,
298            stream: None,
299            after: None,
300            next_available: None,
301            requested_stream: None,
302            cursor_stream: None,
303            projection: None,
304            path: None,
305            key_path: None,
306            index: None,
307        }
308    }
309}
310
311/// The `error` member of an error response.
312#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
313#[serde(rename_all = "camelCase")]
314#[non_exhaustive]
315pub struct ErrorObject {
316    /// Registry code. Typed as a plain integer on the wire; the value domain is
317    /// the registry below.
318    pub code: i64,
319    /// Human-readable message. Never a branch point.
320    pub message: String,
321    /// Structured detail; carries `kind` when present.
322    #[serde(skip_serializing_if = "Option::is_none")]
323    pub data: Option<Box<ErrorData>>,
324}