Skip to main content

muse_code_sdk/fold/
types.rs

1use std::collections::HashMap;
2
3use serde_json::Value;
4
5use super::ItemOutcome;
6
7/// What [`SessionFold::apply`](super::SessionFold::apply) did with one event.
8#[derive(Debug, Clone, PartialEq, Eq)]
9#[non_exhaustive]
10pub enum FoldOutcome {
11    /// The fold took the event (a redelivery may leave it unchanged).
12    Applied,
13    /// An `item/started`, `item/updated` or `item/completed`: the item was
14    /// inserted, replaced, or ignored as stale.
15    Item(ItemOutcome),
16    /// A terminal for an approval or a question.
17    Resolution {
18        /// False when an earlier terminal already stands; this one changed
19        /// nothing.
20        first: bool,
21    },
22    /// The event changed nothing: another session's, malformed, a method the
23    /// fold does not fold, a repeat or out-of-order event the fold drops, or
24    /// arriving after the fold stopped (a re-opened fold still takes question
25    /// events).
26    Ignored,
27}
28
29/// Where a turn stands in the fold.
30#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31#[non_exhaustive]
32pub enum TurnState {
33    /// No `turn/completed`, accepted `turn/retracted` or `turn/unqueued`
34    /// applied yet.
35    Running,
36    /// Ended with a `turn/completed` terminal.
37    Settled,
38    /// Ended by an accepted `turn/retracted`, in any state. A declined
39    /// retract (the submission stood) never sets it: the turn keeps its state.
40    Retracted,
41    /// Reclaimed from the queue before it launched (`turn/unqueued`, which the
42    /// fold applies in any state).
43    Unqueued,
44}
45
46/// The fold's record of one turn, built from its turn events.
47#[derive(Debug, Clone, PartialEq)]
48pub struct Turn {
49    pub(super) state: TurnState,
50    pub(super) command_id: Option<String>,
51    pub(super) terminal: Option<String>,
52    pub(super) completion: Option<Value>,
53}
54
55impl Turn {
56    /// Where the turn stands.
57    pub const fn state(&self) -> TurnState {
58        self.state
59    }
60
61    /// The `commandId` the fold took from the turn's events: set by
62    /// `turn/started` while the turn runs, by `turn/unqueued` in any state,
63    /// and by `turn/retracted` in any state (a declined one only on a turn the
64    /// fold already holds). `None` before the fold applied one of them.
65    pub fn command_id(&self) -> Option<&str> {
66        self.command_id.as_deref()
67    }
68
69    /// The `terminal` of the `turn/completed` the fold applied, verbatim, so
70    /// a newer host's value survives; `None` until then. A retract or reclaim
71    /// keeps a terminal the turn already carries, so a `Retracted` or
72    /// `Unqueued` turn has one when its completion came first. A
73    /// `turn/completed` after an accepted retract or a reclaim is dropped; a
74    /// declined retract leaves a running turn for its completion to settle.
75    pub fn terminal(&self) -> Option<&str> {
76        self.terminal.as_deref()
77    }
78
79    /// The full params of that `turn/completed`, or `None` until the fold
80    /// applied one.
81    pub const fn completion(&self) -> Option<&Value> {
82        self.completion.as_ref()
83    }
84}
85
86/// Sealed state read view: mutation is available only through `SessionFold`.
87#[derive(Debug, Default)]
88pub struct SessionState(pub(super) HashMap<String, Value>);
89
90impl SessionState {
91    /// The latest params of the session-state notification `family` (for
92    /// example `session/modelChanged`), or `None` when the fold applied none.
93    pub fn get(&self, family: &str) -> Option<&Value> {
94        self.0.get(family)
95    }
96
97    /// How many state families the fold has applied.
98    pub fn len(&self) -> usize {
99        self.0.len()
100    }
101
102    /// True until the fold applies its first state notification.
103    pub fn is_empty(&self) -> bool {
104        self.0.is_empty()
105    }
106}
107
108/// A pending hole in the session's event stream: every undelivered event lies
109/// between view cursors `after` and `next`, both exclusive. A later
110/// `view/gap` can move `next` further, so a joined gap can also span
111/// delivered cursors.
112#[derive(Debug, Clone, PartialEq, Eq)]
113pub struct DeliveryGap {
114    pub(super) after: String,
115    pub(super) next: String,
116}
117
118impl DeliveryGap {
119    /// The last cursor delivered before the hole (opaque: relay it, never
120    /// parse it).
121    pub fn after(&self) -> &str {
122        &self.after
123    }
124
125    /// The first cursor delivered after the hole, where delivery continues.
126    pub fn next(&self) -> &str {
127        &self.next
128    }
129}