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 now **published**: a tracked change is
75    /// ruled, so the model carries the bound and the bundle renders
76    /// `minimum`/`maximum` instead of a bare `integer`.
77    pub limit: u32,
78}
79
80/// The `view/page` request-mode anchor. Declared **open**: the protocol spec
81/// spells it "open string enum, v1 value `latestCompaction`".
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
83#[serde(rename_all = "camelCase")]
84#[non_exhaustive]
85pub enum ViewPageAnchor {
86    /// Anchor at the latest installed compaction boundary.
87    LatestCompaction,
88}
89
90/// The `view/page` paging direction. Closed: the protocol spec spells exactly
91/// two values and a third would change the paging contract.
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
93#[serde(rename_all = "camelCase")]
94pub enum ViewPageDirection {
95    /// The page starts strictly after `cursor`.
96    Forward,
97    /// The page ends strictly before `cursor`.
98    Backward,
99}
100
101/// `item/readOutput` params: byte-ranged fetch of stored full output that the
102/// view truncated — the `outputRef` fetch path the protocol's sections owe.
103/// Read-only; works on loaded and unloaded sessions; no lease.
104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
105#[serde(rename_all = "camelCase")]
106pub struct ItemReadOutputParams {
107    /// The session the item belongs to.
108    pub session_id: String,
109    /// The item whose stored output is fetched.
110    pub item_id: String,
111    /// The `outputRef.id` from the item (never the `uri`; the uri is
112    /// display/provenance).
113    pub output_ref: String,
114    /// STORED-byte offset to start from; 0 when omitted. STORED bytes are a
115    /// property of the output, not of a transport.
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub offset_bytes: Option<u64>,
118    /// STORED bytes requested; default and max 6 MiB. A value above the max is
119    /// served at the max.
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub length_bytes: Option<u64>,
122}
123
124/// The `item/readOutput` content encoding. Closed: text media is ALWAYS `utf8`
125/// and binary media `base64`; a third value would change the client's decode
126/// contract.
127#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "camelCase")]
129pub enum ItemReadOutputEncoding {
130    /// Text: `content` is the decoded string; ranges never split a UTF-8
131    /// sequence (the served end shrinks to the previous boundary).
132    Utf8,
133    /// Binary media: `content` is base64 of the stored range.
134    Base64,
135}
136
137/// `item/readOutput` result: one stored-byte page.
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "camelCase")]
140#[non_exhaustive]
141pub struct ItemReadOutputResult {
142    /// The served range, decoded per `encoding`.
143    pub content: String,
144    /// How `content` encodes the stored bytes.
145    pub encoding: ItemReadOutputEncoding,
146    /// STORED bytes served in THIS response (not the output's total; that is
147    /// `outputRef.byteLen` on the item). The next page's `offsetBytes` is
148    /// `offsetBytes + byteLen` — short-serving and advancing are separate, so
149    /// paging never skips or double-reads a byte.
150    pub byte_len: u64,
151    /// The STORED-byte offset this response actually served from.
152    pub offset_bytes: u64,
153    /// `true` when this range reached the end of the stored output.
154    pub eof: bool,
155    /// The stored output's media type (e.g. `text/plain`).
156    pub media_type: String,
157}
158
159/// One element of a `view/page` result's `events` array: an **unframed view
160/// notification** exactly as the protocol spec defines it — the nested pair
161/// `{"method", "params"}`, which is the live notification minus `jsonrpc` and
162/// `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into
163/// it. the protocol spec is the single normative definition; the protocol's
164/// sections both cite it, so the two surfaces cannot drift.
165#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
166#[serde(rename_all = "camelCase")]
167#[non_exhaustive]
168pub struct UnframedViewNotification {
169    /// The event type — the live notification's method name, retained because
170    /// the type lives only in the notification name and would otherwise be
171    /// lost.
172    pub method: String,
173    /// The notification's params object, verbatim.
174    pub params: UnframedViewNotificationParams,
175}
176
177/// The `params` of an unframed view notification.
178///
179/// Declares the base members every view notification carries, and stays
180/// **open** for the event-specific fields the protocol's sections add per event
181/// type. The v1 schema model names no method-correlated union, so the per-event
182/// arms cannot be expressed here without one; enumerating them as an
183/// uncorrelated union would additionally exclude `turn/unqueued`, whose
184/// notification row is another lane's ratified deferral — a published schema
185/// that rejects a real page element is the exact defect this PR exists to
186/// close. Recorded as a Design delta on a tracked change.
187///
188/// `sourceRange` is required here and not optional: `view/page` serves
189/// durable-sourced events only, and durable-sourced is *defined* as carrying a
190/// `sourceRange` — the ephemeral-sourced exemption applies to `item/delta`,
191/// which `view/page` never replays.
192#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
193#[serde(rename_all = "camelCase")]
194#[non_exhaustive]
195pub struct UnframedViewNotificationParams {
196    /// The owning session.
197    pub session_id: String,
198    /// The event's opaque, strictly monotonic view cursor. It stays **inside**
199    /// `params`, where every live notification already carries it — nothing is
200    /// spliced beside `method`.
201    pub view_cursor: String,
202    /// The durable records this event folded from.
203    pub source_range: SourceRange,
204}
205
206/// `view/page` result.
207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
208#[serde(rename_all = "camelCase")]
209#[non_exhaustive]
210pub struct ViewPageResult {
211    /// The page's events, always ascending by `viewCursor` in both
212    /// directions. Durable-sourced only; pages are contiguous and can never
213    /// skip a cursor.
214    pub events: Vec<UnframedViewNotification>,
215    /// The anchor for the next page in the same direction: forward, the last
216    /// event's cursor; backward, the first's. `null` at the end of the view
217    /// in that direction — never omitted.
218    pub next_cursor: Option<String>,
219    /// The resolution echo, present exactly when the request used `anchor`.
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub resolved_anchor: Option<ViewPageResolvedAnchor>,
222}
223
224/// The `resolvedAnchor` echo: subsequent pages pass ordinary cursors, so the
225/// anchor never needs re-resolving.
226#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
227#[serde(rename_all = "camelCase")]
228#[non_exhaustive]
229pub struct ViewPageResolvedAnchor {
230    /// The view cursor of the resolved boundary's `compaction` event.
231    pub boundary_cursor: String,
232}