Skip to main content

muse_code_sdk/msp/method/lifecycle/session_resume/
history.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::method::snapshot::ViewSnapshot;
4use crate::msp::view::item::Item;
5use serde::Deserialize;
6use serde::Serialize;
7
8/// The `history` request preference of `session/resume`. The forced values
9/// downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full
10/// rung order is anchoredSnapshot → anchored pending cut → inline → snapshot →
11/// pending cut → elided snapshot → elided pending cut → none, a pending cut
12/// being the snapshot with its `monitorInbox` cut to the entries still awaiting
13/// delivery.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
15#[serde(rename_all = "camelCase")]
16pub enum HistoryPreference {
17    /// Serve the best rung that fits, anchored first.
18    Auto,
19    /// Prefer the full folded item array.
20    Inline,
21    /// Prefer a folded view state plus suffix.
22    Snapshot,
23    /// Prefer a snapshot anchored at the latest installed compaction boundary.
24    Anchored,
25}
26
27/// The `history` envelope shared by `session/resume`, `session/fork`, and
28/// `session/read`.
29#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
30#[serde(rename_all = "camelCase")]
31#[non_exhaustive]
32pub struct SessionHistory {
33    /// What was actually served — never what was asked for.
34    pub mode: HistoryMode,
35    /// The full folded item array when `mode` is `inline`; `null` otherwise.
36    pub items: Option<Vec<Item>>,
37    /// The folded view state when `mode` is `snapshot` or `anchoredSnapshot`;
38    /// `null` otherwise.
39    pub snapshot: Option<ViewSnapshot>,
40    /// Why no history was served — sent exactly when `mode` is `"none"`.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub none_reason: Option<HistoryNoneReason>,
43    /// The checkpoint-prune boundary: rows for served items at-or-before
44    /// `through_item_id` in served order predate the selected checkpoint.
45    /// Additive-optional; absence is a non-assertion.
46    #[serde(default, skip_serializing_if = "Option::is_none")]
47    pub checkpoint_boundary: Option<CheckpointBoundary>,
48}
49
50/// A served checkpoint-prune boundary: `through_item_id` names the last
51/// first-opened item that opened strictly before the boundary checkpoint event.
52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53#[serde(rename_all = "camelCase")]
54#[non_exhaustive]
55pub struct CheckpointBoundary {
56    /// The last pre-boundary item's id, in served (first-opened) order.
57    pub through_item_id: String,
58}
59
60/// Why a result served `history.mode: "none"` — the server's typed reason for
61/// serving no history, with one push-only exception: `projectionRebuildFailed`
62/// rides only a `session/viewHealthChanged` notification; no resume or read
63/// result carries it (see its variant doc). Open on the client side: an
64/// absent (older server) or unknown (newer server) value decodes
65/// conservatively as an unknown reason, and `viewCursor` text never
66/// substitutes for it.
67#[derive(Debug, Clone, PartialEq, Eq)]
68#[non_exhaustive]
69pub enum HistoryNoneReason {
70    /// The request's effective `excludeItems` was `true` (the
71    /// `session/read` default; explicit on resume/fork).
72    Excluded,
73    /// A retained cursor was supplied; the streamed suffix carries the
74    /// history.
75    CursorSuffix,
76    /// Every rung through the elided pending cut exceeded the history budget;
77    /// page via `view/page` from the result's `viewCursor`.
78    HistoryBudget,
79    /// No trustworthy materialized projection exists; paging cannot recover it.
80    ProjectionUnavailable,
81    /// The projection exists but the aggregate materialized read exceeded
82    /// its bounded read cap; page in bounded chunks.
83    ProjectionReadLimit,
84    /// One value is push-only: `projectionRebuildFailed` rides only a
85    /// `session/viewHealthChanged` notification, after the host's one re-load
86    /// of a failed live view fails or right after a fork child's live
87    /// fail-close; no resume or read result carries it. The view stays
88    /// unavailable for this load; never followed by `healthy`.
89    ProjectionRebuildFailed,
90    /// A value from a newer host, kept verbatim so an older client decodes the
91    /// rest of the message. Excluded from the generated schema while the enum
92    /// stays declared open; never construct it with a known word.
93    Unknown(String),
94}
95
96/// What history a lifecycle result actually served. Open on the client side:
97/// report-what-was-served means a client treats an unknown mode as "page it
98/// yourself".
99#[derive(Debug, Clone, PartialEq, Eq)]
100#[non_exhaustive]
101pub enum HistoryMode {
102    /// `snapshot` holds a folded view state anchored at the latest installed
103    /// compaction boundary; `snapshot.anchor` names it.
104    AnchoredSnapshot,
105    /// `items` is the full folded item array.
106    Inline,
107    /// `snapshot` holds a folded view state at `snapshot.viewCursor`.
108    Snapshot,
109    /// No history was served — page it via `view/page` from the result's
110    /// `viewCursor`.
111    None,
112    /// A value from a newer host, kept verbatim so an older client decodes the
113    /// rest of the message. Excluded from the generated schema while the enum
114    /// stays declared open; never construct it with a known word.
115    Unknown(String),
116}