khive-runtime 0.21.0

Composable Service API: entity/note CRUD, graph traversal, hybrid search, curation.
Documentation
use std::collections::BTreeMap;

use crate::audit_error::AuditErrorClass;
use khive_storage::Event;
use khive_types::{EventKind, EventOutcome};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

use super::counts::{event_cost_unit, event_work_class, truncatable_total_key};

#[derive(Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EventCountDimension {
    Verb,
    Actor,
}

#[derive(Clone, Copy, Deserialize)]
#[serde(try_from = "[EventCountDimension; 2]")]
pub enum EventCountGroupBy {
    VerbActor,
}

impl TryFrom<[EventCountDimension; 2]> for EventCountGroupBy {
    type Error = &'static str;

    fn try_from(dimensions: [EventCountDimension; 2]) -> Result<Self, Self::Error> {
        match dimensions {
            [EventCountDimension::Verb, EventCountDimension::Actor] => Ok(Self::VerbActor),
            _ => Err("group_by supports only [\"verb\", \"actor\"] in that order"),
        }
    }
}

impl EventCountGroupBy {
    #[cfg(any(test, feature = "test-internals"))]
    pub fn add_to_result(
        self,
        result: &mut Value,
        items: &[Event],
        default_actor: Option<&str>,
        truncated: bool,
    ) {
        let mut cross = EventCountCross::default();
        for event in items {
            cross.observe(event, default_actor);
        }
        cross.add_to_result(result, truncated);
    }
}

#[derive(Default)]
pub(crate) struct EventCountCross {
    counts: BTreeMap<String, BTreeMap<String, u64>>,
}

impl EventCountCross {
    pub(crate) fn observe(&mut self, event: &Event, default_actor: Option<&str>) {
        let actor = default_actor.unwrap_or(event.actor.as_str());
        *self
            .counts
            .entry(event.verb.clone())
            .or_default()
            .entry(actor.to_owned())
            .or_default() += 1;
    }

    pub(crate) fn add_to_result(self, result: &mut Value, truncated: bool) {
        result[truncatable_total_key("counts_by_verb_and_actor", truncated)] = json!(self.counts);
    }
}

/// Counts own only output keys and scalar aggregates, never event payloads.
#[derive(Default)]
pub struct EventCountsAccumulator {
    default_actor: Option<String>,
    group_counts: Option<EventCountCross>,
    counts_by_kind: std::collections::BTreeMap<String, u64>,
    counts_by_actor: std::collections::BTreeMap<String, u64>,
    counts_by_verb: std::collections::BTreeMap<String, u64>,
    counts_by_error_class: BTreeMap<&'static str, u64>,
    unclassified_error_count: u64,
    by_profile: std::collections::BTreeMap<String, u64>,
    feedback_by_originating_verb: std::collections::BTreeMap<String, u64>,
    // #34: flat and profile-crossed signal counts read the same payload
    // attribution fields stamped by brain.feedback/brain.auto_feedback.
    counts_by_signal: std::collections::BTreeMap<String, u64>,
    by_profile_and_signal:
        std::collections::BTreeMap<String, std::collections::BTreeMap<String, u64>>,
    counts_by_work_class: std::collections::BTreeMap<String, u64>,
    total_cost_unit: i64,
    cost_unit_by_verb: std::collections::BTreeMap<String, i64>,
    sampled_success_rows: BTreeMap<String, SampledSuccessRows>,
}

impl EventCountsAccumulator {
    pub fn new(default_actor: Option<&str>, group_by: Option<EventCountGroupBy>) -> Self {
        Self {
            default_actor: default_actor.map(str::to_owned),
            group_counts: group_by.map(|_| Default::default()),
            ..Default::default()
        }
    }

    pub fn observe(&mut self, event: &Event) {
        *self
            .counts_by_kind
            .entry(event.kind.name().to_string())
            .or_insert(0) += 1;
        let actor_key = self.default_actor.as_ref().unwrap_or(&event.actor);
        *self.counts_by_actor.entry(actor_key.clone()).or_insert(0) += 1;
        *self.counts_by_verb.entry(event.verb.clone()).or_insert(0) += 1;
        if event.kind == EventKind::Audit && event.outcome != EventOutcome::Success {
            match event
                .payload
                .get("error_class")
                .and_then(Value::as_str)
                .and_then(AuditErrorClass::from_token)
            {
                Some(class) => {
                    *self
                        .counts_by_error_class
                        .entry(class.as_str())
                        .or_default() += 1
                }
                None => self.unclassified_error_count += 1,
            }
        }
        if event.kind == khive_types::EventKind::FeedbackExplicit {
            let originating_verb = event
                .payload
                .get("originating_verb")
                .and_then(Value::as_str)
                .unwrap_or(event.verb.as_str())
                .to_string();
            *self
                .feedback_by_originating_verb
                .entry(originating_verb)
                .or_insert(0) += 1;
            let profile = event
                .payload
                .get("served_by_profile_id")
                .and_then(Value::as_str)
                .unwrap_or("unspecified")
                .to_string();
            *self.by_profile.entry(profile.clone()).or_insert(0) += 1;
            let signal = event
                .payload
                .get("signal")
                .and_then(Value::as_str)
                .unwrap_or("unspecified")
                .to_string();
            *self.counts_by_signal.entry(signal.clone()).or_insert(0) += 1;
            *self
                .by_profile_and_signal
                .entry(profile)
                .or_default()
                .entry(signal)
                .or_insert(0) += 1;
        }
        if let Some(work_class) = event_work_class(&event.payload) {
            *self
                .counts_by_work_class
                .entry(work_class.to_string())
                .or_insert(0) += 1;
        }
        if let Some(cost_unit) = event_cost_unit(&event.payload) {
            self.total_cost_unit = self.total_cost_unit.saturating_add(cost_unit);
            let entry = self
                .cost_unit_by_verb
                .entry(event.verb.clone())
                .or_insert(0);
            *entry = entry.saturating_add(cost_unit);
        }
        if let Some(cross) = &mut self.group_counts {
            cross.observe(event, self.default_actor.as_deref());
        }
        if event.kind == EventKind::Audit
            && event.outcome == EventOutcome::Success
            && matches!(
                event.verb.as_str(),
                "comm.heartbeat" | "comm.cleanup_expired_quarantine"
            )
        {
            self.sampled_success_rows
                .entry(event.verb.clone())
                .or_default()
                .observe(
                    event
                        .payload
                        .get("resource")
                        .and_then(|resource| resource.get("sampling")),
                );
        }
    }

    pub fn add_to_result(self, result: &mut Value, truncated: bool) {
        result[truncatable_total_key("sampled_success_rows", truncated)] =
            json!(self.sampled_success_rows);
        result["counts_by_kind"] = json!(self.counts_by_kind);
        result["counts_by_actor"] = json!(self.counts_by_actor);
        result["counts_by_verb"] = json!(self.counts_by_verb);
        // Unknown and historical classes are counted without inventing a class
        // or changing stored payloads. Omit both keys if no failed audit was read.
        if !self.counts_by_error_class.is_empty() || self.unclassified_error_count != 0 {
            result[truncatable_total_key("counts_by_error_class", truncated)] =
                json!(self.counts_by_error_class);
            result[truncatable_total_key("unclassified_error_count", truncated)] =
                json!(self.unclassified_error_count);
        }
        if let Some(cross) = self.group_counts {
            cross.add_to_result(result, truncated);
        }
        if !self.by_profile.is_empty() {
            result["by_profile"] = json!(self.by_profile);
        }
        if !self.feedback_by_originating_verb.is_empty() {
            result["feedback_by_originating_verb"] = json!(self.feedback_by_originating_verb);
        }
        if !self.counts_by_signal.is_empty() {
            result["counts_by_signal"] = json!(self.counts_by_signal);
        }
        if !self.by_profile_and_signal.is_empty() {
            result["by_profile_and_signal"] = json!(self.by_profile_and_signal);
        }
        if !self.counts_by_work_class.is_empty() {
            result["counts_by_work_class"] = json!(self.counts_by_work_class);
        }
        if !self.cost_unit_by_verb.is_empty() {
            result[truncatable_total_key("total_cost_unit", truncated)] =
                json!(self.total_cost_unit);
            result["cost_unit_by_verb"] = json!(self.cost_unit_by_verb);
        }
    }
}

#[derive(Default, Serialize)]
struct SampledSuccessRows {
    rows: u64,
    sample_rows: u64,
    forced_rows: u64,
    unsampled_rows: u64,
    every: Option<u64>,
    #[serde(skip)]
    mixed_rates: bool,
}

impl SampledSuccessRows {
    fn observe(&mut self, sampling: Option<&Value>) {
        let Some(sampling) = sampling else {
            self.unsampled_rows += 1;
            return;
        };
        self.rows += 1;
        let (Some(every), Some(_seq), Some(selected_by)) = (
            sampling
                .get("every")
                .and_then(Value::as_u64)
                .filter(|every| *every > 0),
            sampling.get("seq").and_then(Value::as_u64),
            sampling.get("selected_by").and_then(Value::as_str),
        ) else {
            return;
        };
        match selected_by {
            "sample" => self.sample_rows += 1,
            "forced" => self.forced_rows += 1,
            _ => return,
        }
        if !self.mixed_rates {
            match self.every {
                None => self.every = Some(every),
                Some(previous) if previous != every => {
                    self.every = None;
                    self.mixed_rates = true;
                }
                Some(_) => {}
            }
        }
    }
}