muse_code_sdk/fold/approvals.rs
1//! Approvals as the TS and Python folds hold them: a
2//! pending entry keeps its latest request and its latest update apart, and
3//! both sets list in the order their entries first arrived.
4//!
5//! Downstream code cannot build `PendingApproval` with a struct literal and
6//! must destructure it with `..`, so a later field stays additive.
7//!
8//! ```compile_fail,E0639
9//! use muse_code_sdk::fold::PendingApproval;
10//!
11//! fn rebuild(approval: PendingApproval) {
12//! let _ = PendingApproval { ..approval };
13//! }
14//! ```
15//!
16//! ```no_run
17//! use muse_code_sdk::fold::PendingApproval;
18//!
19//! fn inspect(approval: PendingApproval) {
20//! let PendingApproval { approval_id, .. } = approval;
21//! println!("{approval_id}");
22//! }
23//! ```
24
25use std::collections::{HashMap, hash_map::Entry};
26
27use serde_json::{Map, Value};
28
29/// An approval awaiting its first durable terminal.
30///
31/// Callers only receive it, so it is `#[non_exhaustive]`: a later field
32/// breaks no caller (as for the received wire structs).
33#[derive(Clone, Debug, PartialEq)]
34#[non_exhaustive]
35pub struct PendingApproval {
36 /// The `approvalId` the host minted for this approval.
37 pub approval_id: String,
38 /// The latest `approval/requested` params, verbatim.
39 pub requested: Value,
40 /// The most recent `approval/updated` refresh since that request, if any.
41 pub latest_update: Option<Value>,
42}
43
44/// Each entry keeps the sequence at which it entered its set, so pending
45/// approvals list in first-request order and resolved ones in
46/// first-resolution order.
47#[derive(Debug, Default)]
48pub(super) struct Approvals {
49 observed: u64,
50 pending: HashMap<String, (u64, PendingApproval)>,
51 resolved: HashMap<String, (u64, Value)>,
52}
53
54impl Approvals {
55 /// A request for an approval that already has its terminal never re-opens
56 /// it. A re-request replaces the entry, update included: a re-issued
57 /// request already embodies the latest refresh.
58 pub(super) fn request(&mut self, id: &str, params: &Map<String, Value>) -> bool {
59 if self.resolved.contains_key(id) {
60 return false;
61 }
62 let entry = PendingApproval {
63 approval_id: id.to_owned(),
64 requested: Value::Object(params.clone()),
65 latest_update: None,
66 };
67 match self.pending.entry(id.to_owned()) {
68 Entry::Occupied(mut slot) => slot.get_mut().1 = entry,
69 Entry::Vacant(slot) => {
70 slot.insert((self.observed, entry));
71 self.observed += 1;
72 }
73 }
74 true
75 }
76
77 /// An update refreshes a pending entry; it never opens one.
78 pub(super) fn update(&mut self, id: &str, params: &Map<String, Value>) -> bool {
79 match self.pending.get_mut(id) {
80 Some((_, entry)) => {
81 entry.latest_update = Some(Value::Object(params.clone()));
82 true
83 }
84 None => false,
85 }
86 }
87
88 /// The first durable terminal stands; a later one is an echo, never an
89 /// overwrite.
90 pub(super) fn resolve(&mut self, id: &str, params: &Map<String, Value>) -> bool {
91 self.pending.remove(id);
92 match self.resolved.entry(id.to_owned()) {
93 Entry::Vacant(slot) => {
94 slot.insert((self.observed, Value::Object(params.clone())));
95 self.observed += 1;
96 true
97 }
98 Entry::Occupied(_) => false,
99 }
100 }
101
102 /// The latest params seen for a pending approval: its update if any, else
103 /// its request.
104 pub(super) fn latest(&self, id: &str) -> Option<&Value> {
105 self.pending
106 .get(id)
107 .map(|(_, entry)| entry.latest_update.as_ref().unwrap_or(&entry.requested))
108 }
109
110 pub(super) fn resolved(&self, id: &str) -> Option<&Value> {
111 super::params_of(self.resolved.get(id))
112 }
113
114 pub(super) fn pending_in_order(&self) -> Vec<&PendingApproval> {
115 let mut ordered: Vec<_> = self.pending.values().collect();
116 ordered.sort_unstable_by_key(|(observed, _)| *observed);
117 ordered.into_iter().map(|(_, entry)| entry).collect()
118 }
119
120 pub(super) fn resolved_in_order(&self) -> Vec<&Value> {
121 super::in_observed_order(&self.resolved)
122 }
123}