Skip to main content

khive_runtime/events_split/
stores.rs

1use super::events_count_read_budget::CountReadBudget;
2#[cfg(unix)]
3use super::events_count_read_budget::{self, restore_count_read_failure};
4#[cfg(unix)]
5use super::forwarder::EventsSplitClient;
6#[cfg(unix)]
7use super::paths::EVENTS_PROTOCOL_VERSION;
8#[cfg(unix)]
9use super::protocol::{EventsRequest, EventsResponse, WireWriterTaskFailure};
10use async_trait::async_trait;
11use khive_storage::event::{
12    EventGroupBy, EventPageQuery, EventPageWindow, IdempotentEventBatchResult,
13};
14use khive_storage::{
15    BatchWriteSummary, Event, EventFilter, EventStore, Page, PageRequest, StorageError,
16    StorageResult,
17};
18use std::collections::BTreeMap;
19use std::sync::Arc;
20use uuid::Uuid;
21
22/// [`EventStore`] implementation the runtime hands out when the events split
23/// runs in daemon mode. Appends are fire-and-forget through the client's
24/// bounded queue; the ADR-133 idempotent lane and all reads are synchronous
25/// round-trips to the events daemon.
26#[cfg(unix)]
27#[derive(Debug)]
28pub struct ForwardingEventStore {
29    pub(super) namespace: String,
30    pub(super) client: Arc<EventsSplitClient>,
31}
32
33#[cfg(unix)]
34impl ForwardingEventStore {
35    pub fn new(namespace: impl Into<String>, client: Arc<EventsSplitClient>) -> Self {
36        Self {
37            namespace: namespace.into(),
38            client,
39        }
40    }
41
42    pub(super) fn unexpected_count(
43        &self,
44        op: &'static str,
45        response: EventsResponse,
46    ) -> StorageError {
47        match restore_count_read_failure(response) {
48            Err(error) => error,
49            Ok(other) => self.unexpected(op, other),
50        }
51    }
52
53    pub(super) fn unexpected(&self, op: &'static str, response: EventsResponse) -> StorageError {
54        match response {
55            EventsResponse::Error {
56                message,
57                retryable,
58                writer_task_failure,
59                sqlite_write_failure,
60                read_failure,
61            } => {
62                if read_failure.is_some() {
63                    return events_count_read_budget::malformed_read_failure(
64                        "non-count response carries read failure evidence",
65                    );
66                }
67                // Reconstruct the same legacy policy first; evidence must not
68                // widen retries or turn a known rollback into task termination.
69                let source = if retryable {
70                    StorageError::Pool {
71                        operation: op.into(),
72                        message,
73                    }
74                } else {
75                    StorageError::InvalidInput {
76                        capability: khive_storage::StorageCapability::Events,
77                        operation: op.into(),
78                        message,
79                    }
80                };
81                let source = match sqlite_write_failure {
82                    Some(failure) => source.with_sqlite_write_failure(failure),
83                    None => source,
84                };
85                match writer_task_failure {
86                    Some(WireWriterTaskFailure::RequestFailed { request_state }) => {
87                        StorageError::WriterTaskRequestFailed {
88                            request_state: request_state.into(),
89                            source: Box::new(source),
90                        }
91                    }
92                    Some(WireWriterTaskFailure::TaskTerminated {
93                        request_state,
94                        sqlite_full_codes,
95                    }) => {
96                        let terminal = StorageError::WriterTaskTerminated {
97                            request_state: request_state.into(),
98                            sqlite_full_codes,
99                        };
100                        match sqlite_write_failure {
101                            Some(failure) => terminal.with_sqlite_write_failure(failure),
102                            None => terminal,
103                        }
104                    }
105                    None => source,
106                }
107            }
108            other => StorageError::Serialization {
109                capability: khive_storage::StorageCapability::Events,
110                message: format!("events daemon returned mismatched response for {op}: {other:?}"),
111            },
112        }
113    }
114}
115
116#[cfg(unix)]
117#[async_trait]
118impl EventStore for ForwardingEventStore {
119    async fn append_event(&self, event: Event) -> StorageResult<()> {
120        self.client.enqueue(&self.namespace, vec![event]);
121        Ok(())
122    }
123
124    async fn append_events(&self, events: Vec<Event>) -> StorageResult<BatchWriteSummary> {
125        let attempted = events.len() as u64;
126        self.client.enqueue(&self.namespace, events);
127        // Fire-and-forget: the hand-off succeeded or was counted as a drop;
128        // either way the caller's contract is "accepted for forwarding".
129        Ok(BatchWriteSummary {
130            attempted,
131            affected: attempted,
132            ..BatchWriteSummary::default()
133        })
134    }
135
136    async fn get_event(&self, id: Uuid) -> StorageResult<Option<Event>> {
137        let request = EventsRequest::GetEvent {
138            protocol_version: EVENTS_PROTOCOL_VERSION,
139            namespace: self.namespace.clone(),
140            id,
141        };
142        match self.client.round_trip(&request).await? {
143            EventsResponse::Event { event } => Ok(event),
144            other => Err(self.unexpected("get_event", other)),
145        }
146    }
147
148    async fn query_events(
149        &self,
150        filter: EventFilter,
151        page: PageRequest,
152    ) -> StorageResult<Page<Event>> {
153        let request = EventsRequest::QueryEvents {
154            protocol_version: EVENTS_PROTOCOL_VERSION,
155            namespace: self.namespace.clone(),
156            filter,
157            page,
158        };
159        match self.client.round_trip(&request).await? {
160            EventsResponse::Pageful { page } => Ok(page),
161            other => Err(self.unexpected("query_events", other)),
162        }
163    }
164
165    async fn count_events(&self, filter: EventFilter) -> StorageResult<u64> {
166        let budget = CountReadBudget::capture();
167        let request = EventsRequest::CountEvents {
168            protocol_version: EVENTS_PROTOCOL_VERSION,
169            namespace: self.namespace.clone(),
170            operator_read_budget_secs: Some(budget.operator_read_budget_secs),
171            filter,
172        };
173        match self.client.round_trip_count(&request, &budget).await? {
174            EventsResponse::Count { count } => Ok(count),
175            other => Err(self.unexpected_count("count_events", other)),
176        }
177    }
178
179    async fn count_events_grouped(
180        &self,
181        filter: EventFilter,
182        group_by: EventGroupBy,
183    ) -> StorageResult<BTreeMap<String, u64>> {
184        let budget = CountReadBudget::capture();
185        let request = EventsRequest::CountEventsGrouped {
186            protocol_version: EVENTS_PROTOCOL_VERSION,
187            namespace: self.namespace.clone(),
188            operator_read_budget_secs: Some(budget.operator_read_budget_secs),
189            filter,
190            group_by,
191        };
192        match self.client.round_trip_count(&request, &budget).await? {
193            EventsResponse::GroupedCount { counts } => Ok(counts),
194            other => Err(self.unexpected_count("count_events_grouped", other)),
195        }
196    }
197
198    async fn query_event_page(&self, query: EventPageQuery) -> StorageResult<EventPageWindow> {
199        crate::event_page::validate_page_query(&query)?;
200        let request = EventsRequest::QueryEventPage {
201            protocol_version: EVENTS_PROTOCOL_VERSION,
202            namespace: self.namespace.clone(),
203            query: query.clone(),
204        };
205        match self.client.round_trip(&request).await? {
206            EventsResponse::EventPageWindow { window } => {
207                crate::event_page::validate_window(&query, Some(&self.namespace), &window)?;
208                Ok(window)
209            }
210            error @ EventsResponse::Error { .. } => Err(self.unexpected("query_event_page", error)),
211            _ => Err(crate::event_page::page_error(
212                "events page response kind mismatch",
213            )),
214        }
215    }
216
217    fn preflight_event(&self, event: &Event) -> StorageResult<()> {
218        // Same validation code path as the daemon-side store, zero I/O.
219        self.client.preflight_store.preflight_event(event)
220    }
221
222    async fn append_events_idempotent(
223        &self,
224        events: Vec<Event>,
225    ) -> StorageResult<IdempotentEventBatchResult> {
226        let request = EventsRequest::AppendEventsIdempotent {
227            protocol_version: EVENTS_PROTOCOL_VERSION,
228            namespace: self.namespace.clone(),
229            events,
230        };
231        match self.client.round_trip(&request).await? {
232            EventsResponse::Idempotent { result } => Ok(result),
233            other => Err(self.unexpected("append_events_idempotent", other)),
234        }
235    }
236
237    fn supports_idempotent_audit_batch(&self) -> bool {
238        true
239    }
240}
241
242/// The store the runtime hands out when the events split is configured:
243/// routes by APPEND CLASS rather than moving the whole event plane.
244///
245/// - The ADR-133 idempotent audit-batch lane — the measured bulk of event
246///   write volume (verb-dispatch audit plus the config-lock rows that ride
247///   the same flusher) — goes to the events lane (the events database, forwarded or
248///   direct).
249/// - Plain appends stay on the legacy store, because the legacy `events`
250///   table has raw-SQL consumers whose correctness depends on finding those
251///   rows there: the schedule drain's creator-provenance fence, the kg
252///   projection worker's guarded event INSERT (transactional with main-db
253///   state), and GraphQuery's cross-substrate UNION. Those events are
254///   low-volume domain facts; the split's contention relief does not need
255///   them moved, and moving them breaks the consumers by construction.
256/// - Reads merge both stores so trait-level consumers
257///   (`brain.event_counts`, event getters) observe one event plane.
258pub struct SplitEventStore {
259    pub(super) legacy: Arc<dyn EventStore>,
260    pub(super) lane: Arc<dyn EventStore>,
261}
262
263impl std::fmt::Debug for SplitEventStore {
264    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
265        f.debug_struct("SplitEventStore").finish_non_exhaustive()
266    }
267}
268
269impl SplitEventStore {
270    /// Bound on `offset + limit` for a merged `query_events` window. Offset
271    /// pagination over two stores materializes the whole prefix in memory
272    /// (see `query_events`), so an unbounded offset would let a single
273    /// request buffer both stores wholesale. The bound comfortably admits
274    /// the largest legitimate bounded window in the tree
275    /// (`brain.event_counts`' 50k page); deep walks page with a `before`
276    /// cursor at `offset: 0`, which never grows the materialized prefix.
277    pub const MAX_MERGED_WINDOW_ROWS: u64 = 100_000;
278
279    pub fn new(legacy: Arc<dyn EventStore>, lane: Arc<dyn EventStore>) -> Self {
280        Self { legacy, lane }
281    }
282}
283
284#[async_trait]
285impl EventStore for SplitEventStore {
286    async fn append_event(&self, event: Event) -> StorageResult<()> {
287        self.legacy.append_event(event).await
288    }
289
290    async fn append_events(&self, events: Vec<Event>) -> StorageResult<BatchWriteSummary> {
291        self.legacy.append_events(events).await
292    }
293
294    async fn get_event(&self, id: Uuid) -> StorageResult<Option<Event>> {
295        // Domain events (legacy) are the likelier and cheaper hit; fall back
296        // to the lane for audit-batch rows.
297        if let Some(event) = self.legacy.get_event(id).await? {
298            return Ok(Some(event));
299        }
300        self.lane.get_event(id).await
301    }
302
303    async fn query_events(
304        &self,
305        filter: EventFilter,
306        page: PageRequest,
307    ) -> StorageResult<Page<Event>> {
308        // Offset pagination cannot be split across two stores: fetch each
309        // store's prefix covering the requested window, merge in the stores'
310        // shared order (created_at DESC, id DESC), then window in memory.
311        // Cost is O(offset + limit) rows materialized from each store — the
312        // floor for offset semantics over two sources, since the split point
313        // is unknowable without both prefixes. The sort below is a single
314        // merge pass in practice (std's stable sort is adaptive on the
315        // concatenation of two sorted runs). That materialization is why the
316        // window is bounded below: without a bound, one authenticated
317        // request with a pathological offset would make both stores buffer
318        // and sort every matching row. Deep walks page with a `before`
319        // cursor (strict `created_at <` bound in `EventFilter`) at
320        // `offset: 0`, which stays inside the bound at any depth.
321        let window = page.offset.saturating_add(u64::from(page.limit));
322        if window > Self::MAX_MERGED_WINDOW_ROWS {
323            return Err(StorageError::InvalidInput {
324                capability: khive_storage::StorageCapability::Events,
325                operation: "query_events".into(),
326                message: format!(
327                    "offset+limit ({window}) exceeds the merged event plane's window bound \
328                     of {}; page deep windows with a `before` cursor at offset 0, or narrow \
329                     the filter",
330                    Self::MAX_MERGED_WINDOW_ROWS
331                ),
332            });
333        }
334        let prefix = PageRequest {
335            offset: 0,
336            limit: window.min(u64::from(u32::MAX)) as u32,
337        };
338        let legacy = self
339            .legacy
340            .query_events(filter.clone(), prefix.clone())
341            .await?;
342        let lane = self.lane.query_events(filter, prefix).await?;
343        let total = match (legacy.total, lane.total) {
344            (Some(a), Some(b)) => Some(a + b),
345            _ => None,
346        };
347        let mut items = legacy.items;
348        items.extend(lane.items);
349        items.sort_by(|a, b| {
350            b.created_at
351                .cmp(&a.created_at)
352                .then_with(|| b.id.cmp(&a.id))
353        });
354        let items = items
355            .into_iter()
356            .skip(page.offset as usize)
357            .take(page.limit as usize)
358            .collect();
359        Ok(Page { items, total })
360    }
361
362    async fn count_events(&self, filter: EventFilter) -> StorageResult<u64> {
363        let budget = CountReadBudget::capture();
364        budget
365            .scope(async {
366                let legacy = self
367                    .legacy
368                    .count_events(filter.clone())
369                    .await
370                    .map_err(|error| budget.attribute(error))?;
371                let lane = self.lane.count_events(filter).await?;
372                Ok(legacy + lane)
373            })
374            .await
375    }
376
377    async fn count_events_grouped(
378        &self,
379        filter: EventFilter,
380        group_by: EventGroupBy,
381    ) -> StorageResult<BTreeMap<String, u64>> {
382        let budget = CountReadBudget::capture();
383        budget
384            .scope(async {
385                let mut counts = self
386                    .legacy
387                    .count_events_grouped(filter.clone(), group_by)
388                    .await
389                    .map_err(|error| budget.attribute(error))?;
390                for (key, count) in self.lane.count_events_grouped(filter, group_by).await? {
391                    let total = counts.entry(key).or_default();
392                    *total =
393                        total
394                            .checked_add(count)
395                            .ok_or_else(|| StorageError::InvalidInput {
396                                capability: khive_storage::StorageCapability::Events,
397                                operation: "count_events_grouped".into(),
398                                message: "grouped event count overflow".into(),
399                            })?;
400                }
401                Ok(counts)
402            })
403            .await
404    }
405
406    async fn query_event_page(&self, query: EventPageQuery) -> StorageResult<EventPageWindow> {
407        crate::event_page::split_page(self.legacy.as_ref(), self.lane.as_ref(), query).await
408    }
409
410    fn preflight_event(&self, event: &Event) -> StorageResult<()> {
411        // Validation is store-independent; the lane's implementation is the
412        // local zero-I/O validator in forwarding mode.
413        self.lane.preflight_event(event)
414    }
415
416    async fn append_events_idempotent(
417        &self,
418        events: Vec<Event>,
419    ) -> StorageResult<IdempotentEventBatchResult> {
420        // A retried batch may have landed — fully or partially — on the
421        // legacy store before the split cutover, and merged reads stay
422        // duplicate-free only while an id lives in exactly one store. Probe
423        // the legacy store for the batch's ids and route resident rows back
424        // through the legacy store's own idempotent machinery, which compares
425        // every persisted column without re-inserting; only genuinely new
426        // rows reach the lane. Without the probe, a legacy-resident id would
427        // be inserted a second time into the lane and every merged query and
428        // count would double-count it.
429        if events.is_empty() {
430            return self.lane.append_events_idempotent(events).await;
431        }
432        let ids: Vec<Uuid> = events.iter().map(|event| event.id).collect();
433        let probe_limit = u32::try_from(ids.len()).map_err(|_| StorageError::InvalidInput {
434            capability: khive_storage::StorageCapability::Events,
435            operation: "append_events_idempotent".into(),
436            message: format!(
437                "batch of {} rows exceeds the legacy probe window",
438                ids.len()
439            ),
440        })?;
441        let existing = self
442            .legacy
443            .query_events(
444                EventFilter {
445                    ids,
446                    ..EventFilter::default()
447                },
448                PageRequest {
449                    offset: 0,
450                    limit: probe_limit,
451                },
452            )
453            .await?;
454        let legacy_resident: std::collections::HashSet<Uuid> =
455            existing.items.iter().map(|event| event.id).collect();
456        if legacy_resident.is_empty() {
457            return self.lane.append_events_idempotent(events).await;
458        }
459        let mut legacy_rows = Vec::new();
460        let mut lane_rows = Vec::new();
461        let mut routed_to_legacy = Vec::with_capacity(events.len());
462        for event in events {
463            if legacy_resident.contains(&event.id) {
464                routed_to_legacy.push(true);
465                legacy_rows.push(event);
466            } else {
467                routed_to_legacy.push(false);
468                lane_rows.push(event);
469            }
470        }
471        let legacy_expected = legacy_rows.len();
472        let lane_expected = lane_rows.len();
473        let legacy_result = self.legacy.append_events_idempotent(legacy_rows).await?;
474        let lane_result = if lane_expected == 0 {
475            IdempotentEventBatchResult { rows: Vec::new() }
476        } else {
477            self.lane.append_events_idempotent(lane_rows).await?
478        };
479        if legacy_result.rows.len() != legacy_expected || lane_result.rows.len() != lane_expected {
480            return Err(StorageError::Driver {
481                capability: khive_storage::StorageCapability::Events,
482                operation: "append_events_idempotent".into(),
483                source: format!(
484                    "idempotent sub-batch result length mismatch: legacy {}/{}, lane {}/{}",
485                    legacy_result.rows.len(),
486                    legacy_expected,
487                    lane_result.rows.len(),
488                    lane_expected
489                )
490                .into(),
491            });
492        }
493        let mut legacy_iter = legacy_result.rows.into_iter();
494        let mut lane_iter = lane_result.rows.into_iter();
495        let rows = routed_to_legacy
496            .into_iter()
497            .map(|to_legacy| {
498                if to_legacy {
499                    legacy_iter.next().expect("length checked above")
500                } else {
501                    lane_iter.next().expect("length checked above")
502                }
503            })
504            .collect();
505        Ok(IdempotentEventBatchResult { rows })
506    }
507
508    fn supports_idempotent_audit_batch(&self) -> bool {
509        // The legacy-resident probe above routes retried rows through the
510        // legacy store's idempotent path, so the split supports the audit
511        // batch only when BOTH stores do.
512        self.lane.supports_idempotent_audit_batch() && self.legacy.supports_idempotent_audit_batch()
513    }
514}