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}