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}