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}