areev_loop/
analyzer.rs

1//! The `Analyzer` trait and `AnalyzeCtx` — the SDK seam. `AnalyzeCtx` is a
2//! struct (not a trait) so the engine can add methods without breaking
3//! implementors. It exposes only read-only substrate access plus resolved
4//! params, the watermark, and `now` — analyzers cannot write (trust floor),
5//! enforced by holding `&dyn SubstrateRead`.
6
7use crate::error::Result;
8use crate::manifest::{AnalyzerManifest, Params};
9use crate::model::GrainRecord;
10use crate::recommendation::RecDraft;
11use crate::substrate::{HeadGroup, ReadOpts, SubstrateRead, TelemetryView};
12
13/// One applied recommendation due for outcome review, with its metric already
14/// re-measured by the engine (which owns the `&mut` substrate). The outcome
15/// analyzer makes the deterministic changed/regressed decision over this — I/O
16/// in the engine, judgment in the analyzer.
17#[derive(Debug, Clone, PartialEq)]
18pub struct OutcomeInput {
19    pub rec_hash: String,
20    pub target_ref: String,
21    pub metric: String,
22    pub baseline: f64,
23    pub current: f64,
24    pub unit: String,
25    /// Carried from the metric snapshot so the analyzer applies the SAME
26    /// direction the engine did — see `recommendation::is_regression`.
27    pub higher_is_better: bool,
28    /// Where `baseline` came from (`OutcomeResult::baseline_kind`).
29    pub baseline_kind: String,
30    /// The evalset run `baseline` was read from, when it was read from one.
31    pub baseline_run_id: Option<String>,
32    /// The best value before the apply (`OutcomeResult::best_before`).
33    pub best_before: Option<f64>,
34    /// The minimum effect size the engine judged under, in the metric's unit
35    /// — passed through so the revert draft applies the SAME floor.
36    pub tolerance: f64,
37    /// The evalset run `current` was read from, when it was read from one.
38    pub current_run_id: Option<String>,
39    /// The cost bound's reading, when the policy set one
40    /// (`OutcomeResult::cost`). A breached bound with quality held is the
41    /// advisory-Flag case; with quality regressed it rides on the revert.
42    pub cost: Option<crate::recommendation::CostRead>,
43}
44
45/// The context handed to `analyze`. Read-only by construction.
46pub struct AnalyzeCtx<'a> {
47    reader: &'a dyn SubstrateRead,
48    params: &'a Params,
49    namespaces: &'a [String],
50    watermark_ms: Option<i64>,
51    now_ms: i64,
52    outcome_inputs: &'a [OutcomeInput],
53    verdicts: &'a std::collections::BTreeMap<String, String>,
54}
55
56impl<'a> AnalyzeCtx<'a> {
57    #[allow(clippy::too_many_arguments)]
58    pub fn new(
59        reader: &'a dyn SubstrateRead,
60        params: &'a Params,
61        namespaces: &'a [String],
62        watermark_ms: Option<i64>,
63        now_ms: i64,
64        outcome_inputs: &'a [OutcomeInput],
65        verdicts: &'a std::collections::BTreeMap<String, String>,
66    ) -> Self {
67        AnalyzeCtx {
68            reader,
69            params,
70            namespaces,
71            watermark_ms,
72            now_ms,
73            outcome_inputs,
74            verdicts,
75        }
76    }
77
78    /// The latest Verify-gate verdict for a grain an applied recommendation
79    /// created (`held`, `regressed`, `drifted`, `held_costlier`,
80    /// `unmeasured`), or `None` for a grain no apply created.
81    pub fn verdict_for(&self, created_hash: &str) -> Option<&str> {
82        self.verdicts.get(created_hash).map(String::as_str)
83    }
84
85    pub fn params(&self) -> &Params {
86        self.params
87    }
88    pub fn now_ms(&self) -> i64 {
89        self.now_ms
90    }
91    pub fn watermark_ms(&self) -> Option<i64> {
92        self.watermark_ms
93    }
94    pub fn capabilities(&self) -> crate::substrate::Capabilities {
95        self.reader.capabilities()
96    }
97    pub fn outcome_inputs(&self) -> &[OutcomeInput] {
98        self.outcome_inputs
99    }
100
101    /// All grains of a type across the configured namespaces (or all namespaces
102    /// when none are configured).
103    pub fn grains_of_type(&self, grain_type: &str, opts: ReadOpts) -> Result<Vec<GrainRecord>> {
104        if self.namespaces.is_empty() {
105            self.reader.grains_of_type(grain_type, None, opts)
106        } else {
107            let mut out = Vec::new();
108            for ns in self.namespaces {
109                out.extend(self.reader.grains_of_type(grain_type, Some(ns), opts)?);
110            }
111            Ok(out)
112        }
113    }
114
115    /// Live facts across configured namespaces.
116    pub fn facts(&self) -> Result<Vec<GrainRecord>> {
117        self.grains_of_type(crate::model::grain_type::FACT, ReadOpts::default())
118    }
119
120    /// Live observations across configured namespaces.
121    pub fn observations(&self) -> Result<Vec<GrainRecord>> {
122        self.grains_of_type(crate::model::grain_type::OBSERVATION, ReadOpts::default())
123    }
124
125    /// Live grains of one type in ONE explicit namespace — for analyzers
126    /// whose datasource lives in a well-known system namespace (the run
127    /// journals in `agent:harness`) regardless of the sweep's configured
128    /// scope.
129    pub fn grains_in(&self, grain_type: &str, namespace: &str) -> Result<Vec<GrainRecord>> {
130        self.reader
131            .grains_of_type(grain_type, Some(namespace), ReadOpts::default())
132    }
133
134    /// Live Skill grains across configured namespaces.
135    pub fn skills(&self) -> Result<Vec<GrainRecord>> {
136        self.grains_of_type(crate::model::grain_type::SKILL, ReadOpts::default())
137    }
138
139    /// Live Goal grains across configured namespaces.
140    pub fn goals(&self) -> Result<Vec<GrainRecord>> {
141        self.grains_of_type(crate::model::grain_type::GOAL, ReadOpts::default())
142    }
143
144    /// Tool grains (captured tool calls), optionally windowed by a `since`
145    /// watermark, live only. The flagship analyzer's input.
146    pub fn tools_since(&self, since_ms: Option<i64>) -> Result<Vec<GrainRecord>> {
147        self.grains_of_type(
148            crate::model::grain_type::TOOL,
149            ReadOpts {
150                live_only: true,
151                since_ms,
152            },
153        )
154    }
155
156    /// Entities with more than one live head (requires the forks capability).
157    pub fn heads(&self) -> Result<Vec<HeadGroup>> {
158        let ns = if self.namespaces.len() == 1 {
159            Some(self.namespaces[0].as_str())
160        } else {
161            None
162        };
163        self.reader.heads(ns)
164    }
165
166    /// A snapshot of the recall-telemetry rollups (requires the `telemetry`
167    /// capability). `None` when the substrate has no sidecar — a telemetry-fed
168    /// analyzer then degrades to an activation-ladder entry.
169    pub fn telemetry(&self) -> Result<Option<TelemetryView>> {
170        let ns = if self.namespaces.len() == 1 {
171            Some(self.namespaces[0].as_str())
172        } else {
173            None
174        };
175        self.reader.telemetry(ns)
176    }
177}
178
179/// An analysis unit. Object-safe so `builtin_analyzers()` yields trait objects.
180pub trait Analyzer: Send + Sync {
181    fn manifest(&self) -> &AnalyzerManifest;
182
183    /// Produce recommendation drafts. `dedup_key`, `origin`, and the params
184    /// snapshot are stamped by the engine afterward, not here. Returning an
185    /// error drops *this* analyzer's findings for the run; other analyzers are
186    /// unaffected.
187    fn analyze(&self, ctx: &AnalyzeCtx) -> Result<Vec<RecDraft>>;
188}
189
190/// The default-registered built-in analyzers. Count is test-pinned (§11).
191pub fn builtin_analyzers() -> Vec<Box<dyn Analyzer>> {
192    vec![
193        Box::new(crate::analyzers::tool_failure::ToolFailureClustering::new()),
194        Box::new(crate::analyzers::duplicate_sweep::DuplicateSweep::new()),
195        Box::new(crate::analyzers::contradiction_sweep::ContradictionSweep::new()),
196        Box::new(crate::analyzers::fork_surfacing::ForkSurfacing::new()),
197        Box::new(crate::analyzers::staleness::Staleness::new()),
198        Box::new(crate::analyzers::skill_stall::SkillStall::new()),
199        Box::new(crate::analyzers::goal_stagnation::GoalStagnation::new()),
200        Box::new(crate::analyzers::cold_grains::ColdGrains::new()),
201        Box::new(crate::analyzers::coverage_gap::CoverageGap::new()),
202        Box::new(crate::analyzers::budget_pressure::BudgetPressure::new()),
203        Box::new(crate::analyzers::outcome_review::OutcomeReview::new()),
204        Box::new(crate::analyzers::retention_sweep::RetentionSweep::new()),
205        Box::new(crate::analyzers::run_outcome::RunOutcome::new()),
206        Box::new(crate::analyzers::adapter_intake::AdapterIntake::new()),
207        Box::new(crate::analyzers::lesson_pile::LessonPile::new()),
208    ]
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214
215    #[test]
216    fn builtins_have_unique_ids() {
217        let a = builtin_analyzers();
218        assert_eq!(
219            a.len(),
220            15,
221            "6 hygiene + skill/goal trajectory + 3 telemetry-fed (cold/coverage/budget) \
222             + retention (default-off) + run_outcome + adapter_intake + lesson_pile (default-off)"
223        );
224        let mut ids: Vec<&str> = a.iter().map(|x| x.manifest().id.as_str()).collect();
225        ids.sort_unstable();
226        ids.dedup();
227        assert_eq!(ids.len(), 15, "analyzer ids must be unique");
228    }
229
230    #[test]
231    fn all_builtins_are_trust_class_builtin() {
232        for a in builtin_analyzers() {
233            assert_eq!(
234                a.manifest().trust_class,
235                crate::manifest::TrustClass::Builtin,
236                "{} must be builtin trust class",
237                a.manifest().id
238            );
239        }
240    }
241}
areev_loop/analyzer.rs

areev_loop/
analyzer.rs
