Skip to main content

khive_runtime/event_plane_read/
counts.rs

1use chrono::Utc;
2use khive_storage::event::{Event, EventFilter};
3use serde::Deserialize;
4use serde_json::{json, Value};
5
6use crate::{micros_to_iso, KhiveRuntime, NamespaceToken, RuntimeError};
7
8use super::grouping::EventCountsAccumulator;
9use super::parsing::{
10    event_actor_read_scope, parse_event_kind, parse_handler_params, parse_rfc3339_micros,
11};
12
13// ── brain.event_counts ──────────────────────────────────────────────────
14//
15// ADR-103 Stage 1 (#724 Ask A): a windowed, per-actor, per-kind, per-verb
16// read verb over the event plane, additionally surfacing `work_class`
17// (ADR-103-resource-attribution-model.md:303) via `counts_by_work_class`.
18// `work_class` is read from `payload.work_class` first — the shape the
19// three Phase* events (`PhaseStarted`/`PhaseCompleted`/`PhaseCancelled`,
20// `khive_storage::telemetry`) use today — falling back to
21// `payload.resource.work_class` for the not-yet-emitted future shape
22// where a generic audit row carries a `resource` sub-object (ADR-103
23// Stage 1's "resource payload enrichment", still open). Events with
24// neither path present are simply not counted in the split.
25// `cost_unit` (ADR-103 Amendment 1, `payload.resource.cost_unit`,
26// stamped on every successful verb dispatch since PR #927 via
27// `khive_runtime::cost_unit::resource_payload`) sums into
28// `total_cost_unit` and `cost_unit_by_verb`, both omitted rather than
29// zero-filled when no event in the window carries it. Amendment 1's
30// "absence has exactly two meanings" rule means a missing
31// `resource.cost_unit` is either a pre-Amendment-1 event or an
32// errored/denied dispatch — this verb does not distinguish the two, it
33// simply excludes the event from the sum, matching the `work_class`
34// split's existing exclusion convention.
35//
36// Named `brain.event_counts` rather than the literal
37// `brain.events(...)` shape sketched on the issue — that name is already
38// taken by the `Visibility::Subhandler` debug-listing verb above, which an
39// MCP-boundary test (`subhandler_verbs_are_blocked_at_mcp_boundary`)
40// requires to stay internal-only, and which several existing tests depend
41// on for its `{count, events}` shape. Reusing the name would either break
42// that invariant or overload one verb with two incompatible response
43// shapes; a second, public verb name keeps both surfaces intact.
44
45/// Per-part row cap for the default bounded `brain.event_counts` view.
46/// A kind-filtered call folds at most this many events; an unfiltered call
47/// independently admits up to this many audit and this many non-audit events,
48/// for up to twice this cap in one call. Truncation is checked per part.
49/// Storage-side Kind grouping counts `window_event_total` independently of
50/// the admitted rows folded into profile, cross and cost aggregates.
51pub(crate) const MAX_WINDOW_EVENTS: u32 = 50_000;
52pub(crate) const EXHAUSTIVE_PAGE_SIZE: u32 = 10_000;
53pub(crate) const MAX_EXHAUSTIVE_EVENTS: u64 = 40 * MAX_WINDOW_EVENTS as u64;
54
55/// Issue #14: when the window's aggregation ran over a bounded page
56/// rather than the full window (`truncated`), a bare scalar total next
57/// to complete-looking `counts_by_*` maps reads as authoritative even
58/// though it is only a page-scoped estimate. Storage-side admission totals
59/// do not make the admitted-row aggregates complete: when truncated, the misleading key is
60/// never emitted; the same page-scoped value is returned under an
61/// explicitly incomplete name instead. A missing `total` gets noticed;
62/// a `total` that is wrong by an order of magnitude does not.
63/// `window_event_total` (the true count) and `truncated` (the marker)
64/// are unaffected -- this only renames the page-scoped scalar's own key.
65pub(crate) fn truncatable_total_key(base_key: &str, truncated: bool) -> String {
66    if truncated {
67        format!("{base_key}_page_scoped")
68    } else {
69        base_key.to_string()
70    }
71}
72
73impl KhiveRuntime {
74    /// Read the brain event-count projection under the caller's existing read budget.
75    pub async fn read_event_counts(
76        &self,
77        token: &NamespaceToken,
78        params: Value,
79    ) -> Result<Value, RuntimeError> {
80        let allowance = khive_storage::request_read_timeout_from_env();
81        let deadline = khive_storage::effective_request_read_deadline(
82            khive_storage::RequestReadDeadline::after(allowance),
83        );
84        khive_storage::scope_request_read_deadline_at(deadline, async {
85            let operation = format!(
86                "brain.event_counts (operator read budget {}s; earlier caller deadline retained)",
87                allowance.as_secs()
88            );
89            if khive_storage::request_read_is_cancelled() {
90                return Err(RuntimeError::Storage(
91                    khive_storage::StorageError::Timeout {
92                        operation: operation.into(),
93                    },
94                ));
95            }
96            let result = self.read_event_counts_in_read_scope(token, params).await;
97            if result.is_ok() && khive_storage::request_read_is_cancelled() {
98                return Err(RuntimeError::Storage(
99                    khive_storage::StorageError::Timeout {
100                        operation: operation.into(),
101                    },
102                ));
103            }
104            result
105        })
106        .await
107    }
108
109    async fn read_event_counts_in_read_scope(
110        &self,
111        token: &NamespaceToken,
112        params: Value,
113    ) -> Result<Value, RuntimeError> {
114        #[derive(Deserialize)]
115        #[serde(deny_unknown_fields)]
116        struct EventCountsParams {
117            actor: Option<String>,
118            all_actors: Option<bool>,
119            kind: Option<String>,
120            group_by: Option<super::grouping::EventCountGroupBy>,
121            // `Option`, not a required `String`: a bare-missing `since` must go through
122            // the same named-field-plus-example-format error as a malformed one, not
123            // serde's generic "missing field `since`" message.
124            since: Option<String>,
125            until: Option<String>,
126            // #21: opt into full-window aggregation (paginates through every
127            // matching event instead of a single bounded page) so a coverage
128            // panel gets non-sampled per-verb/kind/actor counts in one call,
129            // without stitching sampled windows client-side. The window is a
130            // best-effort live view, not a snapshot (see the walk's docs). Default false — the
131            // bounded page is cheaper and sufficient for most callers.
132            exhaustive: Option<bool>,
133        }
134        let p: EventCountsParams =
135            parse_handler_params(params).map_err(RuntimeError::InvalidInput)?;
136
137        let actor_scope = event_actor_read_scope(
138            self,
139            token,
140            p.actor.as_deref(),
141            p.all_actors.unwrap_or(false),
142        )?;
143
144        let since_raw = p.since.as_deref().ok_or_else(|| {
145            RuntimeError::InvalidInput(
146                "missing `since`: required ISO-8601/RFC-3339 datetime; expected e.g. \
147                 \"2026-07-01T00:00:00Z\""
148                    .to_string(),
149            )
150        })?;
151        let display_tz = self.config().display_timezone;
152        let since_us = parse_rfc3339_micros("since", since_raw, false, display_tz)?;
153        let until_us = match p.until.as_deref() {
154            Some(u) => parse_rfc3339_micros("until", u, true, display_tz)?,
155            None => Utc::now().timestamp_micros(),
156        };
157
158        let kind_filter = p.kind.as_deref().map(parse_event_kind).transpose()?;
159
160        // The event plane is read through a store scoped to exactly one
161        // namespace (`Runtime::events` opens `token.namespace()` and the SQL
162        // pins `namespace = ?`), so a visibility set does not widen this
163        // window the way it widens a note read. Name the namespace the answer
164        // covers, and name the others this caller may ask for by passing
165        // `namespace=`, so an undercount is legible from the result itself.
166        let scope_namespace = token.namespace().as_str().to_string();
167        let mut scope_other: Vec<String> = token
168            .visible_namespace_strs()
169            .iter()
170            .map(|n| n.to_string())
171            .filter(|n| n != &scope_namespace)
172            .collect();
173        scope_other.sort();
174        scope_other.dedup();
175
176        let store = self.events(token)?;
177        let base_filter = EventFilter {
178            actors: actor_scope.actors,
179            kinds: kind_filter.into_iter().collect(),
180            // Half-open window [since, until): `EventFilter.after` is a strict
181            // `created_at > after`, so subtracting one microsecond from `since`
182            // makes the boundary itself inclusive; `before` is already a strict
183            // `created_at < before`, which is exactly the exclusive `until` we want.
184            after: Some(since_us - 1),
185            before: Some(until_us),
186            ..EventFilter::default()
187        };
188
189        let exhaustive = p.exhaustive.unwrap_or(false);
190        let mut counts =
191            EventCountsAccumulator::new(actor_scope.default_caller.as_deref(), p.group_by);
192        let (total, window_event_total, truncated) = if exhaustive {
193            fold_event_counts_window_exhaustive(
194                store.as_ref(),
195                &base_filter,
196                EXHAUSTIVE_PAGE_SIZE,
197                MAX_EXHAUSTIVE_EVENTS,
198                &mut counts,
199            )
200            .await?
201        } else {
202            let (items, window_event_total, truncated) = fetch_event_counts_window(
203                store.as_ref(),
204                &base_filter,
205                p.kind.is_none(),
206                MAX_WINDOW_EVENTS,
207            )
208            .await?;
209            for event in &items {
210                counts.observe(event);
211            }
212            (items.len() as u64, window_event_total, truncated)
213        };
214
215        let mut result = json!({
216            "since": micros_to_iso(since_us),
217            "until": micros_to_iso(until_us),
218            "actor": p.actor,
219            "kind": p.kind,
220            "truncated": truncated,
221            "window_event_total": window_event_total,
222            "exhaustive": exhaustive,
223            // The scope the answer was computed under, stated rather than
224            // implied. `namespace` is the single namespace this window covers;
225            // `other_namespaces` are the ones this caller may read by asking
226            // for them explicitly, and whose rows are absent here. A caller can
227            // therefore tell a real zero from an out-of-scope population, and
228            // knows what to pass to reach the rest.
229            "scope": {
230                "namespace": scope_namespace,
231                "other_namespaces": scope_other,
232            },
233        });
234        result[truncatable_total_key("total", truncated)] = json!(total);
235        counts.add_to_result(&mut result, truncated);
236        Ok(result)
237    }
238}
239
240/// Fetch the event window for `brain.event_counts`, each bounded query capped at
241/// `page_limit` (`MAX_WINDOW_EVENTS` in production; a free function
242/// parameterized on the cap so a unit test can shrink it and exercise the
243/// crowd-out fix below deterministically, instead of needing tens of thousands
244/// of seeded rows to trigger it).
245///
246/// #26: the unfiltered default view (`unfiltered = true`, i.e. the caller
247/// passed no `kind`) must not let the high-volume `audit` kind crowd every
248/// other kind out of the shared budget. `query_events` orders by `created_at
249/// DESC`, so a single bounded fetch over "all kinds" returns whichever kind
250/// fired most densely in the tail of the window — measured at ~12x undercount
251/// for `feedback_explicit` when `audit` alone runs 37k-50k/week. Segregate
252/// `audit` into its own bounded query so each half gets the full `page_limit`
253/// independently — a quiet kind is never crowded out by a busy one. Only
254/// applies to the unfiltered default view: a caller who already passed `kind`
255/// has no crowding to fix (the single query is already scoped to one kind).
256///
257/// Returns the concatenated items, the independent Kind-grouped window total,
258/// and whether either half was truncated against its own `page_limit`.
259/// Transport-safe per-request page bound for every event read this module
260/// issues. The events-split daemon refuses `QueryEvents` pages above its cap
261/// (`crate::events_split::MAX_QUERY_EVENTS_PAGE_ROWS`), and the
262/// split store's merged read forwards `offset + limit` as one daemon page —
263/// so windows wider than the cap are collected by cursor-walking in pages of
264/// at most this many rows at `offset: 0`, never by one wide request.
265pub const TRANSPORT_PAGE_ROWS: u32 = crate::events_split::MAX_QUERY_EVENTS_PAGE_ROWS;
266
267pub(super) fn event_counts_storage_error(error: khive_storage::StorageError) -> RuntimeError {
268    match error {
269        error @ (khive_storage::StorageError::Timeout { .. }
270        | khive_storage::StorageError::AdmissionTimeout { .. }) => RuntimeError::Storage(error),
271        other => RuntimeError::InvalidInput(other.to_string()),
272    }
273}
274
275/// Read one grouped total; row walks and boundary completeness reads remain
276/// independent live observations. Unsupported grouped stores refuse directly.
277pub(super) async fn grouped_window_total(
278    store: &dyn khive_storage::event::EventStore,
279    filter: &EventFilter,
280) -> Result<u64, RuntimeError> {
281    Ok(store
282        .count_events_grouped(filter.clone(), khive_storage::event::EventGroupBy::Kind)
283        .await
284        .map_err(event_counts_storage_error)?
285        .values()
286        .copied()
287        .sum())
288}
289
290pub async fn fetch_event_counts_window(
291    store: &dyn khive_storage::event::EventStore,
292    base_filter: &EventFilter,
293    unfiltered: bool,
294    page_limit: u32,
295) -> Result<(Vec<Event>, u64, bool), RuntimeError> {
296    if !unfiltered {
297        let window_event_total = grouped_window_total(store, base_filter).await?;
298        let items = collect_events_cursor_walk(
299            store,
300            base_filter,
301            TRANSPORT_PAGE_ROWS,
302            u64::from(page_limit),
303        )
304        .await?;
305        let truncated = window_event_total > items.len() as u64;
306        return Ok((items, window_event_total, truncated));
307    }
308
309    let non_audit_kinds: Vec<khive_types::EventKind> = khive_types::EventKind::ALL
310        .iter()
311        .copied()
312        .filter(|k| *k != khive_types::EventKind::Audit)
313        .collect();
314    let audit_filter = EventFilter {
315        kinds: vec![khive_types::EventKind::Audit],
316        ..base_filter.clone()
317    };
318    let non_audit_filter = EventFilter {
319        kinds: non_audit_kinds,
320        ..base_filter.clone()
321    };
322
323    // Preserve the old closed-kind union: unknown stored kinds belong to
324    // neither half of this unfiltered bounded view.
325    let totals = store
326        .count_events_grouped(
327            EventFilter {
328                kinds: khive_types::EventKind::ALL.to_vec(),
329                ..base_filter.clone()
330            },
331            khive_storage::event::EventGroupBy::Kind,
332        )
333        .await
334        .map_err(event_counts_storage_error)?;
335    let audit_total = totals
336        .get(khive_types::EventKind::Audit.name())
337        .copied()
338        .unwrap_or(0);
339    let non_audit_total: u64 = khive_types::EventKind::ALL
340        .iter()
341        .filter(|kind| **kind != khive_types::EventKind::Audit)
342        .map(|kind| totals.get(kind.name()).copied().unwrap_or(0))
343        .sum();
344    let audit_items = collect_events_cursor_walk(
345        store,
346        &audit_filter,
347        TRANSPORT_PAGE_ROWS,
348        u64::from(page_limit),
349    )
350    .await?;
351    let non_audit_items = collect_events_cursor_walk(
352        store,
353        &non_audit_filter,
354        TRANSPORT_PAGE_ROWS,
355        u64::from(page_limit),
356    )
357    .await?;
358
359    let truncated =
360        audit_total > audit_items.len() as u64 || non_audit_total > non_audit_items.len() as u64;
361    let window_event_total = audit_total + non_audit_total;
362    let mut items = audit_items;
363    items.extend(non_audit_items);
364    Ok((items, window_event_total, truncated))
365}
366
367/// Collect up to `max_rows` events for `base_filter` by walking a strict
368/// descending `before` cursor at `offset: 0`, requesting at most
369/// [`TRANSPORT_PAGE_ROWS`] rows per query so no request exceeds the
370/// events-daemon page cap.
371///
372/// `before` is a strict `created_at <` bound, so stepping the cursor to the
373/// last row's timestamp would drop rows sharing that microsecond beyond the
374/// page edge. Step to `last.created_at + 1` instead — which re-admits the
375/// boundary microsecond — and drop the re-read rows by id. Deliver each row
376/// exactly once in the existing page order; signed saturating cost sums rely
377/// on that order. A timestamp tie run wider than the transport cap cannot be
378/// paged past (widening the page is refused by the
379/// daemon) and is reported as a typed error rather than looping.
380///
381/// Read consistency: the walk issues independent page (and, at the cap,
382/// count) reads against a live event plane with no snapshot spanning them.
383/// The result is a best-effort live-window view, not a snapshot — a row
384/// appended concurrently with the walk may be excluded or included
385/// depending on where the cursor stands when it lands (never duplicated,
386/// and never an error), and a total observed by an independent
387/// `count_events` read can differ from the collected rows. Callers needing
388/// a closed population bound the window with `until` in the past, which is
389/// closed only insofar as the event plane appends rows stamped at append
390/// time rather than backdated.
391pub(crate) async fn collect_events_cursor_walk(
392    store: &dyn khive_storage::event::EventStore,
393    base_filter: &EventFilter,
394    page_size: u32,
395    max_rows: u64,
396) -> Result<Vec<Event>, RuntimeError> {
397    let mut items = Vec::new();
398    visit_events_cursor_walk(store, base_filter, page_size, max_rows, |event| {
399        items.push(event)
400    })
401    .await?;
402    Ok(items)
403}
404
405/// Visit owned rows in cursor order, dropping each page before the next read.
406pub(crate) async fn visit_events_cursor_walk<F: FnMut(Event)>(
407    store: &dyn khive_storage::event::EventStore,
408    base_filter: &EventFilter,
409    page_size: u32,
410    max_rows: u64,
411    visit: F,
412) -> Result<u64, RuntimeError> {
413    crate::visit_events_cursor_walk(store, base_filter, page_size, max_rows, visit)
414        .await
415        .map_err(|cause| match cause {
416            crate::EventCursorWalkError::Storage(error) => event_counts_storage_error(error),
417            crate::EventCursorWalkError::MissingBoundary => RuntimeError::Internal(
418                "event cursor walk saw duplicate rows before any boundary".to_string(),
419            ),
420            crate::EventCursorWalkError::DenseTimestampTie {
421                page_limit: fetch_limit,
422            } => RuntimeError::InvalidInput(format!(
423                "brain.event_counts cannot page this window: more than {fetch_limit} \
424                     events share one created_at microsecond, which exceeds the event \
425                     transport's page cap; narrow `since`/`until` or add filters (`actor` \
426                     or `kind`)"
427            )),
428        })
429}
430
431#[cfg(any(test, feature = "test-internals"))]
432pub async fn fetch_event_counts_window_exhaustive(
433    store: &dyn khive_storage::event::EventStore,
434    base_filter: &EventFilter,
435    page_size: u32,
436    max_events: u64,
437) -> Result<(Vec<Event>, u64, bool), RuntimeError> {
438    let mut items = Vec::new();
439    let (_, total, truncated) =
440        visit_event_counts_window_exhaustive(store, base_filter, page_size, max_events, |event| {
441            items.push(event)
442        })
443        .await?;
444    Ok((items, total, truncated))
445}
446
447/// Production exhaustive aggregation retains counts but no completed page.
448pub(crate) async fn fold_event_counts_window_exhaustive(
449    store: &dyn khive_storage::event::EventStore,
450    base_filter: &EventFilter,
451    page_size: u32,
452    max_events: u64,
453    counts: &mut EventCountsAccumulator,
454) -> Result<(u64, u64, bool), RuntimeError> {
455    visit_event_counts_window_exhaustive(store, base_filter, page_size, max_events, |event| {
456        counts.observe(&event)
457    })
458    .await
459}
460
461/// #21: full-window aggregation for `brain.event_counts(exhaustive=true)`.
462///
463/// Kind-grouped storage counts establish the admission total. Payload-derived
464/// aggregates still paginate `query_events` with a fixed page size until
465/// exhausted, folding every page instead of stopping at a bounded page.
466/// The caller still makes exactly ONE
467/// `brain.event_counts` call — the pagination loop is internal to this
468/// function — so a coverage panel that needed 19 stitched sampled windows
469/// becomes one exhaustive call.
470///
471/// `window_event_total` sums one Kind-grouped count read with the same filter.
472/// It is independent of pagination and does not require the walk to complete.
473/// The subsequent row reads remain a best-effort live view, not a snapshot.
474///
475/// `max_events` is a safety bound, not a design limit: without one,
476/// a caller could open a pathological (multi-year, unfiltered) window and this
477/// function could spend unbounded work reading and aggregating the window.
478/// Set to 40x the bounded-mode cap (`MAX_WINDOW_EVENTS`)
479/// — comfortably above the multi-million-event/month volumes `exhaustive` is
480/// meant to serve — so it only binds on something pathological. A window above
481/// the bound is rejected before aggregation; exhaustive mode never returns a
482/// partial result.
483pub(super) async fn visit_event_counts_window_exhaustive<F: FnMut(Event)>(
484    store: &dyn khive_storage::event::EventStore,
485    base_filter: &EventFilter,
486    page_size: u32,
487    max_events: u64,
488    visit: F,
489) -> Result<(u64, u64, bool), RuntimeError> {
490    let window_event_total = grouped_window_total(store, base_filter).await?;
491    if window_event_total > max_events {
492        return Err(RuntimeError::InvalidInput(format!(
493            "brain.event_counts window exceeds the exhaustive limit of {max_events} events \
494             ({window_event_total} matched); narrow `since`/`until` or add filters (`actor` or \
495             `kind`)"
496        )));
497    }
498
499    // Walk the window with a descending `before` cursor instead of a growing
500    // offset (see `collect_events_cursor_walk`): every query runs at
501    // `offset: 0` in transport-cap-sized pages, so the walk is linear on a
502    // single-store backend and stays inside the merged events-split store's
503    // bounded materialization window — and under the events daemon's
504    // per-request page cap — at any depth. The count check above already
505    // bounds the window, so the walk runs to exhaustion.
506    let admitted =
507        visit_events_cursor_walk(store, base_filter, page_size, max_events, visit).await?;
508
509    let truncated = admitted < window_event_total;
510    Ok((admitted, window_event_total, truncated))
511}
512
513/// Extract `work_class` from an event payload for `brain.event_counts`'
514/// `counts_by_work_class` split (ADR-103 Stage 1, ADR-103-resource-attribution-model.md:303).
515///
516/// Checks two paths, phase-payload first:
517/// 1. `payload.work_class` — the shape `PhaseStarted`/`PhaseCompleted`/`PhaseCancelled`
518///    events use today (`khive_storage::telemetry::{PhaseStartedPayload, ...}`).
519/// 2. `payload.resource.work_class` — the shape successful-dispatch audit rows write:
520///    `crate::cost_unit` constructs the resource object with `work_class` and the
521///    runtime persists it on successful audit rows. Phase payloads keep precedence when
522///    both paths are present.
523///
524/// Returns `None` (silently excluded from the split, not an error) when neither path is
525/// present — the overwhelming majority of event kinds today.
526pub(crate) fn event_work_class(payload: &Value) -> Option<&str> {
527    payload
528        .get("work_class")
529        .and_then(Value::as_str)
530        .or_else(|| {
531            payload
532                .get("resource")
533                .and_then(|resource| resource.get("work_class"))
534                .and_then(Value::as_str)
535        })
536}
537
538/// Extract `cost_unit` from an event payload for `brain.event_counts`'
539/// `total_cost_unit` / `cost_unit_by_verb` aggregation (ADR-103 Amendment 1).
540///
541/// Reads `payload.resource.cost_unit` only — unlike `work_class`, `cost_unit`
542/// has no top-level payload shape: it is emitted exclusively by
543/// `crate::cost_unit::resource_payload` on the per-dispatch audit
544/// row's `resource` sub-object, never by the Phase* background-work events.
545///
546/// Returns `None` (silently excluded from the sum, not an error or a zero)
547/// when the field is absent, which per Amendment 1's "absence has exactly
548/// two meanings" rule is either a pre-Amendment-1 event or an
549/// errored/denied dispatch.
550pub(crate) fn event_cost_unit(payload: &Value) -> Option<i64> {
551    payload
552        .get("resource")
553        .and_then(|resource| resource.get("cost_unit"))
554        .and_then(Value::as_i64)
555}