Skip to main content

khive_runtime/event_plane_read/
recent.rs

1use khive_storage::event::EventFilter;
2use khive_storage::types::PageRequest;
3use serde::Deserialize;
4use serde_json::{json, Value};
5
6use crate::{micros_to_iso, KhiveRuntime, NamespaceToken, RuntimeError};
7
8use super::parsing::parse_handler_params;
9
10impl KhiveRuntime {
11    /// Read the brain debug event projection through the authorized token.
12    pub async fn read_brain_events(
13        &self,
14        token: &NamespaceToken,
15        params: Value,
16    ) -> Result<Value, RuntimeError> {
17        #[derive(Deserialize)]
18        #[serde(deny_unknown_fields)]
19        struct EventsParams {
20            limit: Option<u32>,
21        }
22        let p: EventsParams = parse_handler_params(params).map_err(RuntimeError::InvalidInput)?;
23
24        let limit = p.limit.unwrap_or(20).min(100);
25        let ns = token.namespace().as_str().to_string();
26
27        let store = self.events(token)?;
28        let filter = EventFilter {
29            verbs: vec![
30                "recall".into(),
31                "search".into(),
32                "brain.feedback".into(),
33                "brain.emit".into(), // retained for backward-compat queries
34                "get".into(),
35                "remember".into(),
36            ],
37            ..EventFilter::default()
38        };
39        let _ = ns;
40        let page = store
41            .query_events(filter, PageRequest { offset: 0, limit })
42            .await
43            .map_err(|e| RuntimeError::InvalidInput(e.to_string()))?;
44
45        let events: Vec<Value> = page
46            .items
47            .iter()
48            .map(|e| {
49                json!({
50                    "id": e.id.to_string(),
51                    "verb": e.verb,
52                    "outcome": e.outcome,
53                    "target_id": e.target_id.map(|t| t.to_string()),
54                    "duration_us": e.duration_us,
55                    "created_at": micros_to_iso(e.created_at),
56                    "payload": e.payload,
57                })
58            })
59            .collect();
60
61        Ok(json!({
62            "count": events.len(),
63            "events": events,
64        }))
65    }
66}
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71    use crate::Namespace;
72    use khive_storage::Event;
73    use khive_types::{EventKind, EventOutcome, SubstrateKind};
74    use uuid::Uuid;
75
76    fn event(id: u128, verb: &str, kind: EventKind) -> Event {
77        let mut event = Event::new("local", verb, kind, SubstrateKind::Note, "fixture");
78        event.id = Uuid::from_u128(id);
79        event.created_at = id as i64;
80        event
81    }
82
83    fn ids(result: &Value) -> Vec<String> {
84        result["events"]
85            .as_array()
86            .unwrap()
87            .iter()
88            .map(|row| row["id"].as_str().unwrap().to_owned())
89            .collect()
90    }
91
92    #[tokio::test]
93    async fn recent_events_keep_closed_verbs_limits_namespace_and_all_kinds() {
94        let runtime = KhiveRuntime::memory().unwrap();
95        let token = runtime.authorize(Namespace::local()).unwrap();
96        let other = runtime
97            .authorize(Namespace::parse("other").unwrap())
98            .unwrap();
99        let store = runtime.events(&token).unwrap();
100        let verbs = [
101            "recall",
102            "search",
103            "brain.feedback",
104            "brain.emit",
105            "get",
106            "remember",
107        ];
108        let mut rows: Vec<_> = (1..=101)
109            .map(|id| {
110                event(
111                    id,
112                    verbs[(id as usize - 1) % verbs.len()],
113                    if id % 2 == 0 {
114                        EventKind::Audit
115                    } else {
116                        EventKind::FeedbackExplicit
117                    },
118                )
119            })
120            .collect();
121        rows.extend([
122            event(201, "memory.recall", EventKind::FeedbackExplicit),
123            event(202, "brain.state", EventKind::Audit),
124            event(203, "create", EventKind::Audit),
125            event(204, "other", EventKind::FeedbackExplicit),
126        ]);
127        store.append_events(rows).await.unwrap();
128        let other_store = runtime.events(&other).unwrap();
129        other_store
130            .append_events(vec![
131                event(301, "recall", EventKind::Audit),
132                event(302, "brain.feedback", EventKind::FeedbackExplicit),
133            ])
134            .await
135            .unwrap();
136        let before = store
137            .query_events(
138                EventFilter::default(),
139                PageRequest {
140                    offset: 0,
141                    limit: 200,
142                },
143            )
144            .await
145            .unwrap();
146        let other_before = other_store
147            .query_events(
148                EventFilter::default(),
149                PageRequest {
150                    offset: 0,
151                    limit: 200,
152                },
153            )
154            .await
155            .unwrap();
156        assert_eq!(before.items.len(), 105);
157        assert_eq!(other_before.items.len(), 2);
158
159        let default = runtime.read_brain_events(&token, json!({})).await.unwrap();
160        assert_eq!(
161            default["count"], 20,
162            "recent events retain the default20 window"
163        );
164        assert_eq!(
165            ids(&default),
166            (82..=101)
167                .rev()
168                .map(|id| Uuid::from_u128(id).to_string())
169                .collect::<Vec<_>>(),
170            "closed verbs, namespace and unfiltered event kinds select the exact newest rows"
171        );
172        let capped = runtime
173            .read_brain_events(&token, json!({"limit": 1000}))
174            .await
175            .unwrap();
176        assert_eq!(
177            capped["count"], 100,
178            "recent events cap the requested limit at100"
179        );
180        assert_eq!(
181            ids(&capped),
182            (2..=101)
183                .rev()
184                .map(|id| Uuid::from_u128(id).to_string())
185                .collect::<Vec<_>>()
186        );
187        assert_eq!(
188            runtime
189                .read_brain_events(&token, json!({"limit": null}))
190                .await
191                .unwrap(),
192            default
193        );
194        assert_eq!(
195            runtime
196                .read_brain_events(&token, json!({"limit": 0}))
197                .await
198                .unwrap(),
199            json!({"count": 0, "events": []})
200        );
201        let other_result = runtime.read_brain_events(&other, json!({})).await.unwrap();
202        assert_eq!(other_result["count"], 2);
203        assert_eq!(
204            ids(&other_result),
205            vec![
206                Uuid::from_u128(302).to_string(),
207                Uuid::from_u128(301).to_string()
208            ]
209        );
210        assert_eq!(
211            store
212                .query_events(
213                    EventFilter::default(),
214                    PageRequest {
215                        offset: 0,
216                        limit: 200
217                    }
218                )
219                .await
220                .unwrap()
221                .items,
222            before.items,
223            "recent reads preserve every stored local event"
224        );
225        assert_eq!(
226            other_store
227                .query_events(
228                    EventFilter::default(),
229                    PageRequest {
230                        offset: 0,
231                        limit: 200
232                    }
233                )
234                .await
235                .unwrap()
236                .items,
237            other_before.items,
238            "recent reads preserve the other namespace too"
239        );
240    }
241
242    #[tokio::test]
243    async fn recent_events_preserve_exact_projection_and_null_target() {
244        let runtime = KhiveRuntime::memory().unwrap();
245        let token = runtime.authorize(Namespace::local()).unwrap();
246        let mut first = event(1, "get", EventKind::Audit);
247        first.created_at = 1_000_123;
248        first.duration_us = -7;
249        first.outcome = EventOutcome::Denied;
250        first.target_id = Some(Uuid::from_u128(99));
251        first.payload = json!({"nested": [null, {"value": "kept"}]});
252        first.session_id = Some(Uuid::from_u128(100));
253        let mut second = event(2, "brain.emit", EventKind::FeedbackExplicit);
254        second.created_at = 2_000_456;
255        second.duration_us = 42;
256        second.outcome = EventOutcome::Error;
257        second.payload = json!({"signal": "useful"});
258        runtime
259            .events(&token)
260            .unwrap()
261            .append_events(vec![first, second])
262            .await
263            .unwrap();
264        let result = runtime.read_brain_events(&token, json!({})).await.unwrap();
265        assert_eq!(
266            result,
267            json!({
268                "count": 2,
269                "events": [
270                    {"id": Uuid::from_u128(2).to_string(), "verb": "brain.emit", "outcome": "error", "target_id": null, "duration_us": 42, "created_at": "1970-01-01T00:00:02.000456Z", "payload": {"signal": "useful"}},
271                    {"id": Uuid::from_u128(1).to_string(), "verb": "get", "outcome": "denied", "target_id": Uuid::from_u128(99).to_string(), "duration_us": -7, "created_at": "1970-01-01T00:00:01.000123Z", "payload": {"nested": [null, {"value": "kept"}]}}
272                ]
273            }),
274            "recent-event wire projection is exact, including omission of unprojected fields"
275        );
276    }
277
278    #[tokio::test]
279    async fn recent_events_keep_events_params_refusals() {
280        let runtime = KhiveRuntime::memory().unwrap();
281        let token = runtime.authorize(Namespace::local()).unwrap();
282        for (params, expected) in [
283            (
284                json!({"namespace": "other"}),
285                "unknown field `namespace`, expected `limit`",
286            ),
287            (
288                json!({"kind": "audit"}),
289                "unknown field `kind`, expected `limit`",
290            ),
291            (json!({"limit": -1}), "expected u32"),
292            (json!({"limit": 4294967296_u64}), "expected u32"),
293            (json!({"limit": "1"}), "expected u32"),
294            (json!({"limit": 1.5}), "expected u32"),
295            (json!(7), "expected struct EventsParams"),
296        ] {
297            let result = runtime.read_brain_events(&token, params.clone()).await;
298            assert!(
299                matches!(&result, Err(RuntimeError::InvalidInput(message)) if message.contains(expected)),
300                "recent EventsParams refusal for {params}: {result:?}"
301            );
302        }
303    }
304}