Skip to main content

muse_code_sdk/msp/method/
view.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::view::SourceRange;
4use serde::Deserialize;
5use serde::Serialize;
6
7/// `view/subscribe` params: attach this connection's live view subscription for
8/// a session at an explicit cursor — the fine-grained counterpart of the
9/// auto-subscribe, and the gap-free re-attachment path after
10/// `view/unsubscribe`. It never loads a session, takes no lease, writes
11/// nothing.
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(rename_all = "camelCase")]
14pub struct ViewSubscribeParams {
15    /// The session to follow.
16    pub session_id: String,
17    /// Resume cursor. When present, the server replays `(after, head]` as
18    /// ordinary view notifications before any live event — one gapless cursor
19    /// sequence. Omitted means "from now": no historical replay.
20    #[serde(skip_serializing_if = "Option::is_none")]
21    pub after: Option<String>,
22}
23
24/// `view/subscribe` result.
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(rename_all = "camelCase")]
27#[non_exhaustive]
28pub struct ViewSubscribeResult {
29    /// The view head at subscribe time; the client knows it is live once
30    /// cursors pass it.
31    pub view_cursor: String,
32}
33
34/// `view/unsubscribe` params: remove this connection from the session's view
35/// subscription set — the protocol's single unsubscribe operation, at the
36/// altitude that owns subscriptions. It does not unload the session; unloading
37/// is the idle policy.
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
39#[serde(rename_all = "camelCase")]
40pub struct ViewUnsubscribeParams {
41    /// The session to stop following.
42    pub session_id: String,
43}
44
45/// `view/unsubscribe` result: the empty object. Idempotent — unsubscribing
46/// while not subscribed returns `{}`.
47#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
48#[serde(rename_all = "camelCase")]
49#[non_exhaustive]
50pub struct ViewUnsubscribeResult {}
51
52/// `view/page` params: cursor-paged reads of the session view.
53#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
54#[serde(rename_all = "camelCase")]
55pub struct ViewPageParams {
56    /// The session to page.
57    pub session_id: String,
58    /// The exclusive anchor. Forward: the page starts strictly after it;
59    /// omitted means from the beginning of the view. Backward: the page ends
60    /// strictly before it; omitted means from the head. Mutually exclusive with
61    /// `anchor`.
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub cursor: Option<String>,
64    /// The cold-client request mode, resolved at call time to the latest
65    /// installed compaction boundary. The one named exception to the
66    /// observed-only rule.
67    #[serde(skip_serializing_if = "Option::is_none")]
68    pub anchor: Option<ViewPageAnchor>,
69    /// Paging direction; `forward` when omitted.
70    #[serde(skip_serializing_if = "Option::is_none")]
71    pub direction: Option<ViewPageDirection>,
72    /// Maximum events to return, 1–1000. The server MAY return fewer.
73    ///
74    /// The 1–1000 range is ratified and **published**: the model carries the
75    /// bound and the bundle renders `minimum`/`maximum` instead of a bare
76    /// `integer`.
77    pub limit: u32,
78    /// The caller's page byte cap (kt-dvw5, additive-optional). The page
79    /// serves under `min(server budget, maxBytes)`, so a Console page stays
80    /// under its own budget without the server's frame cap alone deciding.
81    /// Absent means the server budget governs. `0` is refused typed
82    /// (`invalid_params`): a 0 cap admits no progress. A single event over
83    /// the cap is truncated (marked) instead of erroring, except verbatim
84    /// and fetch-key content (`item.args`, `structuredData`, `outputRef`/
85    /// `patchRef`), which is never cut and still answers typed
86    /// `PageEventTooLarge`.
87    #[serde(skip_serializing_if = "Option::is_none")]
88    pub max_bytes: Option<u64>,
89}
90
91/// The `view/page` request-mode anchor. Declared **open**: the protocol spells
92/// it "open string enum, v1 value `latestCompaction`".
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(rename_all = "camelCase")]
95#[non_exhaustive]
96pub enum ViewPageAnchor {
97    /// Anchor at the latest installed compaction boundary.
98    LatestCompaction,
99}
100
101/// The `view/page` paging direction. Closed: the protocol spells exactly two
102/// values and a third would change the paging contract.
103#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
104#[serde(rename_all = "camelCase")]
105pub enum ViewPageDirection {
106    /// The page starts strictly after `cursor`.
107    Forward,
108    /// The page ends strictly before `cursor`.
109    Backward,
110}
111
112/// `item/readOutput` params: byte-ranged fetch of stored full output that the
113/// view truncated, via the item's `outputRef`. Read-only; works on loaded and
114/// unloaded sessions; no lease.
115#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
116#[serde(rename_all = "camelCase")]
117pub struct ItemReadOutputParams {
118    /// The session the item belongs to.
119    pub session_id: String,
120    /// The item whose stored output is fetched.
121    pub item_id: String,
122    /// The `outputRef.id` from the item (never the `uri`; the uri is
123    /// display/provenance).
124    pub output_ref: String,
125    /// STORED-byte offset to start from; 0 when omitted. STORED bytes are a
126    /// property of the output, not of a transport.
127    #[serde(skip_serializing_if = "Option::is_none")]
128    pub offset_bytes: Option<u64>,
129    /// STORED bytes requested; default and max 6 MiB. A value above the max is
130    /// served at the max.
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub length_bytes: Option<u64>,
133}
134
135/// The `item/readOutput` content encoding. Closed: text media is ALWAYS `utf8`
136/// and binary media `base64`; a third value would change the client's decode
137/// contract.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "camelCase")]
140pub enum ItemReadOutputEncoding {
141    /// Text: `content` is the decoded string; ranges never split a UTF-8
142    /// sequence (the served end shrinks to the previous boundary).
143    Utf8,
144    /// Binary media: `content` is base64 of the stored range.
145    Base64,
146}
147
148/// `item/readOutput` result: one stored-byte page.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150#[serde(rename_all = "camelCase")]
151#[non_exhaustive]
152pub struct ItemReadOutputResult {
153    /// The served range, decoded per `encoding`.
154    pub content: String,
155    /// How `content` encodes the stored bytes.
156    pub encoding: ItemReadOutputEncoding,
157    /// STORED bytes served in THIS response (not the output's total; that is
158    /// `outputRef.byteLen` on the item). The next page's `offsetBytes` is
159    /// `offsetBytes + byteLen` — short-serving and advancing are separate, so
160    /// paging never skips or double-reads a byte.
161    pub byte_len: u64,
162    /// The STORED-byte offset this response actually served from.
163    pub offset_bytes: u64,
164    /// `true` when this range reached the end of the stored output.
165    pub eof: bool,
166    /// The stored output's media type (e.g. `text/plain`).
167    pub media_type: String,
168}
169
170/// One element of a `view/page` result's `events` array: an **unframed view
171/// notification** — the nested pair `{"method", "params"}`, which is the live
172/// notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of
173/// `params` and nothing spliced into it. `view/page` and `muse exec --json`
174/// share this one definition, so the two surfaces cannot drift.
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176#[serde(rename_all = "camelCase")]
177#[non_exhaustive]
178pub struct UnframedViewNotification {
179    /// The event type — the live notification's method name, retained because
180    /// the type lives only in the notification name and would otherwise be
181    /// lost.
182    pub method: String,
183    /// The notification's params object, verbatim.
184    pub params: UnframedViewNotificationParams,
185}
186
187/// The `params` of an unframed view notification.
188///
189/// Declares the base members every view notification carries, and stays
190/// **open** for the event-specific fields each event type adds. The v1 schema
191/// model names no method-correlated union (the `events` element's `params` arm
192/// is selected by its sibling `method`), so the per-event arms cannot be
193/// expressed here without one, and an uncorrelated union of them could reject a
194/// real page element, which a published schema must not do.
195///
196/// `sourceRange` is required here and not optional: `view/page` serves
197/// durable-sourced events only, and durable-sourced is *defined* as carrying a
198/// `sourceRange` — the ephemeral-sourced exemption applies to `item/delta`,
199/// which `view/page` never replays.
200#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
201#[serde(rename_all = "camelCase")]
202#[non_exhaustive]
203pub struct UnframedViewNotificationParams {
204    /// The owning session.
205    pub session_id: String,
206    /// The event's opaque, strictly monotonic view cursor. It stays **inside**
207    /// `params`, where every live notification already carries it — nothing is
208    /// spliced beside `method`.
209    pub view_cursor: String,
210    /// The durable records this event folded from.
211    pub source_range: SourceRange,
212}
213
214/// `view/page` result.
215#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
216#[serde(rename_all = "camelCase")]
217#[non_exhaustive]
218pub struct ViewPageResult {
219    /// The page's events, always ascending by `viewCursor` in both
220    /// directions. Durable-sourced only; pages are contiguous and can never
221    /// skip a cursor.
222    pub events: Vec<UnframedViewNotification>,
223    /// The anchor for the next page in the same direction: forward, the last
224    /// event's cursor; backward, the first's. `null` at the end of the view
225    /// in that direction — never omitted.
226    pub next_cursor: Option<String>,
227    /// The resolution echo, present exactly when the request used `anchor`.
228    #[serde(skip_serializing_if = "Option::is_none")]
229    pub resolved_anchor: Option<ViewPageResolvedAnchor>,
230}
231
232/// The `resolvedAnchor` echo: subsequent pages pass ordinary cursors, so the
233/// anchor never needs re-resolving.
234#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
235#[serde(rename_all = "camelCase")]
236#[non_exhaustive]
237pub struct ViewPageResolvedAnchor {
238    /// The view cursor of the resolved boundary's `compaction` event.
239    pub boundary_cursor: String,
240}