Crate areev_loop 

Areev Loop

The governed self-improvement engine for AI-agent memory. Areev Loop turns an agent’s own history into recommendations — evidence-cited, reviewable, undoable, measured — and governs every change through four gates (propose, review, apply, verify). The deterministic core produces useful recommendations with zero model calls by computing over declared grain semantics, never raw prose.

This crate is a standalone engine over an OmsSubstrate (CAL text + grains) with zero Areev dependencies (serde only). Areev is the first substrate; ReferenceSubstrate lets tests run with no store at all.

use areev_loop::{Engine, ReferenceSubstrate, RunOptions};

let mut store = ReferenceSubstrate::new();
let engine = Engine::with_builtins();
let result = engine.run(&mut store, &RunOptions::default(), 1_000).unwrap();
assert!(result.ran());

See the design proposal (docs/loop-proposal.md) for the full model.

Re-exports

pub use analyzer::builtin_analyzers;

pub use analyzer::AnalyzeCtx;

pub use analyzer::Analyzer;

pub use analyzer::OutcomeInput;

pub use engine::Decision;

pub use engine::Engine;

pub use engine::Health;

pub use engine::LlmMetrics;

pub use engine::RunOptions;

pub use engine::RunOutcome;

pub use engine::RunResult;

pub use engine::Scope;

pub use engine::ScopeSet;

pub use engine::SkipReason;

pub use engine::LOOP_NS;

pub use config::AnalyzerConfig;

pub use config::AnalyzerConfigUpdate;

pub use config::AnalyzerSetting;

pub use error::Error;

pub use error::Result;

pub use external::CommandAnalyzer;

pub use llm::CommandLlm;

pub use llm::LlmBackend;

pub use manifest::analyzer_family;

pub use manifest::AnalyzerManifest;

pub use manifest::AutoApplyClass;

pub use manifest::CadenceClass;

pub use manifest::Capability;

pub use manifest::ParamSpec;

pub use manifest::Params;

pub use manifest::TargetClass;

pub use manifest::Tier;

pub use manifest::TrustClass;

pub use model::ActionKind;

pub use model::GrainRecord;

pub use model::Origin;

pub use model::Severity;

pub use model::TargetRef;

pub use policy::AutoApplyGrant;

pub use policy::Policy;

pub use policy::TelemetryMode;

pub use recommendation::dedup_key;

pub use recommendation::validate_code_rules;

pub use recommendation::AuditRecord;

pub use recommendation::GatingEvidence;

pub use recommendation::MetricSnapshot;

pub use recommendation::ObserverType;

pub use recommendation::OutcomeResult;

pub use recommendation::Proposal;

pub use recommendation::RecDraft;

pub use recommendation::RecStatus;

pub use recommendation::Recommendation;

pub use recommendation::Summary;

pub use reference::ReferenceSubstrate;

pub use substrate::BudgetUsage;

pub use substrate::Capabilities;

pub use substrate::GrainAccess;

pub use substrate::GrainSpec;

pub use substrate::HeadGroup;

pub use substrate::OmsSubstrate;

pub use substrate::QueryUsage;

pub use substrate::ReadOpts;

pub use substrate::SubstrateRead;

pub use substrate::TelemetryView;

Modules

analyzer

The Analyzer trait and AnalyzeCtx — the SDK seam. AnalyzeCtx is a struct (not a trait) so the engine can add methods without breaking implementors. It exposes only read-only substrate access plus resolved params, the watermark, and now — analyzers cannot write (trust floor), enforced by holding &dyn SubstrateRead.

analyzers

The built-in analyzers (proposal §8). Each computes over declared grain semantics — never raw prose — so the deterministic layer works with zero models. All produce pending drafts; the engine stamps identity/origin and runs the governance gates.

cal

A tiny CAL writer. The engine never parses CAL (that is the substrate’s job — validate_cal/execute_cal); it only emits the handful of statements built-in analyzers propose. Statements are newline-separated to form a batch. Keeping this a writer, not a parser, is what lets the engine claim zero CAL-grammar ownership (proposal §10).

config

In-file loop config + state — file-truths persisted through the substrate’s load_state/store_state as one JSON blob. Carries a schema version; unknown keys are ignored (serde default), so an older binary opens a newer file unchanged (proposal §7.3).

engine

The engine: the analyze → DISCOVER → ENRICH → validate/dedup → store pipeline, the run-outcome contract, and the review/apply/rollback lifecycle with the governance gates. The DETERMINISTIC output is a pure function of (store state, params, now); the optional LLM stages (§9) only add cited drafts (origin=llm, never auto-apply) and whitelisted guidance — with no backend they are the identity, so the deterministic path is unchanged. Auto-apply execution is gated behind a conservative shape check and stays off by default.

error

Areev Loop error type. Follows the Areev error convention: every variant’s Display string leads with a stable LOP-Ennn code, and code() returns it. Codes are append-only — never renumber or reuse (see ERROR_CODES.md). The engine has zero areev dependencies, so it owns its own domain (LOP); REVIEW/APPLY syntax errors belong to the substrate’s CAL domain, not here.

eval

Evalset runs — the one reader for the evalset:<hash> mg:eval_run summaries that areev eval run journals into agent:harness.

external

External command analyzers — the --analyzer-cmd seam (SDK §11).

llm

Optional LLM enrichment (proposal §9).

manifest

Analyzer manifests and the flat ParamSpec list. One manifest is the single source feeding the CLI listing, the HTTP /analyzers route, MCP listing, param validation, docs, and the console’s analyzer cards (proposal §11). Hand-rolled with serde_json only — no JSON-Schema dep.

model

Shared value types: grain records the engine reads, target references it proposes against, severity, action kinds, and provenance origin.

policy

Host policy — the optional loop-policy.json (proposal §6.2). It is the only place auto-apply is granted, and it is host config (per-process, never persisted in a memory file). All fields default-closed; the whole struct rejects unknown keys, so a policy that tries to register an executable (--analyzer-cmd) or touch a trust-floor field fails to load — a stolen or committed policy file must be inert.

recommendation

The recommendation object (OMS 0x0C), the deterministic summary renderer, the dedup key, and the lifecycle state machine + audit records.

reference

An in-memory reference substrate: a grain map plus a deliberately naive CAL subset. Engine CI runs the full suite against it with zero Areev, so the portability claim stays testable, and it doubles as the conformance kit for third-party substrates (proposal §10).

substrate

The OmsSubstrate trait — the engine’s only contact with a store. It is defined in terms of the OMS Level-2 protocol (CAL text ↔ JSON rows, grain get/put/supersede) plus curated typed reads the built-in analyzers use. Areev is the first substrate; the in-repo ReferenceSubstrate lets engine CI run with zero Areev, and doubles as the third-party conformance kit.