areev-loop-adapter 1.13.1

//! # areev-loop-adapter
//!
//! The Areev substrate adapter for the [`areev_loop`] engine. It implements
//! [`areev_loop::OmsSubstrate`] over [`areev_cal::AreevFacade`], so the governed
//! self-improvement loop runs against real Areev `.mg`/Turso memory files.
//!
//! ```no_run
//! use areev_loop_adapter::{AreevSubstrate, now_ms};
//! use areev_store::Areev;
//! use areev_loop::{Engine, RunOptions};
//!
//! let store = Areev::open("agent.db").unwrap();
//! let mut sub = AreevSubstrate::new(store, None);
//! let engine = Engine::with_builtins();
//! let result = engine.run(&mut sub, &RunOptions::default(), now_ms()).unwrap();
//! println!("proposed {} recommendation(s)", result.stored);
//! ```

mod decide;
mod governance;
mod substrate;

pub use decide::LoopDecider;
pub use governance::LoopGovernance;
pub use substrate::{loop_state_of, AreevSubstrate, BorrowedSubstrate};

use std::time::{SystemTime, UNIX_EPOCH};

/// Map a session's grants onto the loop engine's scope set — the one
/// translation between Areev's verb model (`areev_core::authz`) and
/// `areev_loop::Scope`, so surfaces stop handing out `ScopeSet::all()`
/// unconditionally. Loop verbs are checked against the loop's own namespace
/// (`areev_loop::LOOP_NS`), which a grant covers by naming it or `*`.
/// An owner session maps to every scope — the CLI's local-root-of-trust
/// behavior, unchanged.
pub fn scopes_for(authz: &areev_core::authz::AuthzSet) -> areev_loop::ScopeSet {
    use areev_loop::Scope;
    use areev_loop::LOOP_NS;
    use areev_core::authz::Verb;
    let mut scopes = Vec::new();
    for (verb, scope) in [
        (Verb::Read, Scope::Read),
        (Verb::Write, Scope::Write),
        (Verb::LoopReview, Scope::Review),
        (Verb::LoopApply, Scope::Apply),
        (Verb::Admin, Scope::Admin),
    ] {
        if authz.allows(verb, LOOP_NS) {
            scopes.push(scope);
        }
    }
    areev_loop::ScopeSet::of(&scopes)
}

/// The scopes a session holds over ONE recommendation, given the namespaces
/// it was derived from (#312).
///
/// The loop's reads are namespace-grant-gated; its outputs were not — every
/// recommendation went to one namespace, `areev-loop`, and rights were
/// checked against that one namespace. So one `read ON areev-loop` grant
/// disclosed the summary, proposal, guidance and evidence hashes of findings
/// derived from every namespace in the memory, and one `loop.review` grant
/// decided all of them, striking a memory-wide cooldown each time.
///
/// The rule: a principal covers a recommendation when its grants allow the
/// verb on EVERY namespace in the recommendation's scope.
///
/// Two deliberate escape hatches, both of which keep existing deployments
/// working unchanged:
///
/// * A grant on `areev-loop` itself (or `*`) means the WHOLE queue, so owner
///   sessions and today's operator grants behave exactly as before.
/// * An EMPTY scope — an unscoped pass, and every recommendation written
///   before this existed — is covered only by such a whole-queue grant. Fail
///   closed: "derived from we-don't-know-where" must not be readable by
///   someone holding one namespace.
pub fn scopes_for_rec(
    authz: &areev_core::authz::AuthzSet,
    scope: &[String],
) -> areev_loop::ScopeSet {
    use areev_core::authz::Verb;
    use areev_loop::Scope;
    use areev_loop::LOOP_NS;
    // The whole-queue grant short-circuits: unchanged behaviour.
    let whole_queue = scopes_for(authz);
    if scope.is_empty() {
        return whole_queue;
    }
    let mut scopes = Vec::new();
    for (verb, s) in [
        (Verb::Read, Scope::Read),
        (Verb::Write, Scope::Write),
        (Verb::LoopReview, Scope::Review),
        (Verb::LoopApply, Scope::Apply),
        (Verb::Admin, Scope::Admin),
    ] {
        // Either the whole queue, or coverage of every namespace the
        // finding was derived from. Never a partial read: a finding derived
        // from `a` and `b` discloses both, so holding `a` alone is not
        // enough.
        if authz.allows(verb, LOOP_NS) || scope.iter().all(|ns| authz.allows(verb, ns)) {
            scopes.push(s);
        }
    }
    areev_loop::ScopeSet::of(&scopes)
}

/// Whether this session may SEE a recommendation with this scope (#312).
///
/// A recommendation the caller does not cover answers "not found" rather
/// than "not authorized", so its existence is not disclosed — the same
/// reasoning `recall` applies when it declines to name a sibling namespace
/// in a refusal.
pub fn covers_rec(authz: &areev_core::authz::AuthzSet, scope: &[String]) -> bool {
    scopes_for_rec(authz, scope).has(areev_loop::Scope::Read)
}

/// Every recommendation a session may SEE, filtered by coverage (#312).
///
/// ONE filtered read that every surface goes through — the CLI, the server,
/// MCP, both bindings and `DESCRIBE LOOP` — so a surface added later cannot
/// forget the check by calling `Engine::recommendations` directly and
/// listing the whole namespace.
pub fn visible_recommendations<S: areev_loop::OmsSubstrate>(
    engine: &areev_loop::Engine,
    sub: &S,
    authz: &areev_core::authz::AuthzSet,
    status: Option<areev_loop::RecStatus>,
) -> areev_loop::Result<Vec<areev_loop::Recommendation>> {
    let all = engine.recommendations(sub, status)?;
    Ok(all.into_iter().filter(|r| covers_rec(authz, &r.scope)).collect())
}

/// The one recommendation among `recs` whose hash starts with `prefix` —
/// the lookup `areev loop show` and the bindings' `recommendation(hash)`
/// share. Pass the coverage-filtered list ([`visible_recommendations`]) on a
/// principal-bindable surface, so a hash the caller cannot see is "no
/// match", indistinguishable from one that does not exist.
pub fn find_recommendation<'a>(
    recs: &'a [areev_loop::Recommendation],
    prefix: &str,
) -> Result<&'a areev_loop::Recommendation, String> {
    let matches: Vec<&areev_loop::Recommendation> =
        recs.iter().filter(|r| r.hash.starts_with(prefix)).collect();
    match matches.as_slice() {
        [] => Err(format!("no recommendation matches '{prefix}'")),
        [one] => Ok(one),
        many => Err(format!(
            "'{prefix}' is ambiguous ({} matches) — use more characters",
            many.len()
        )),
    }
}

/// One recommendation as the review surface shows it: `areev loop show` and
/// the bindings' `recommendation(hash)` print exactly this object (#348).
///
/// The reviewable change itself rides along — `show` is the review surface,
/// so the proposal must be visible before approve/apply. Flattened
/// (`proposal` kind tag + its fields, e.g. `cal`) exactly like the stored
/// grain body; `action_kind`, the outcome metric and any LLM guidance ride
/// along too. The proposal is derived content governed by the same grants
/// as the summary: callers reach this only through a coverage-filtered list.
pub fn recommendation_detail(r: &areev_loop::Recommendation) -> serde_json::Value {
    let mut out = serde_json::json!({
        "hash": r.hash,
        "status": r.status.as_str(),
        "severity": r.severity.as_str(),
        "analyzer": r.analyzer,
        "origin": r.origin,
        "target_ref": r.target_ref,
        "action_kind": r.action_kind,
        "summary": r.summary.render(),
        "destructive": r.destructive,
        "rollbackable": r.rollbackable,
        "evidence": r.evidence,
        "dedup_key": r.dedup_key,
        "confidence": r.confidence,
    });
    let o = out.as_object_mut().expect("json! object");
    if let Some(pin) = &r.evalset_hash {
        o.insert("evalset_hash".into(), serde_json::json!(pin));
    }
    if !r.near_duplicate_of.is_empty() {
        o.insert("near_duplicate_of".into(), serde_json::json!(r.near_duplicate_of));
    }
    // A plan revision's rehearsal against the plan's journaled runs
    // (`areev run shadow --plan-file`), when the substrate could run
    // one — the reviewer approves from evidence, not prose.
    if let Some(replay) = &r.replay {
        o.insert("replay".into(), replay.clone());
    }
    o.extend(proposal_fields(r));
    if let Some(m) = r.metric.as_ref().and_then(|m| serde_json::to_value(m).ok()) {
        o.insert("metric".into(), m);
    }
    if let Some(gd) = &r.guidance {
        o.insert("guidance".into(), serde_json::Value::from(gd.clone()));
    }
    // A decision backend's part in this finding (provider, model,
    // calibrated, latency, the probabilities) and, for an LLM draft routed
    // on the decision, the verifier's own self-report beside it — the
    // reviewer sees who judged, and any disagreement.
    if let Some(j) = &r.judged_by {
        o.insert("judged_by".into(), serde_json::json!(j));
    }
    if let Some(c) = r.llm_confidence {
        o.insert("llm_confidence".into(), serde_json::json!(c));
    }
    out
}

/// The flattened proposal body (`proposal` kind tag + its fields) — what
/// `recommendations({"include": "proposal"})` adds to a listing row.
pub fn proposal_fields(r: &areev_loop::Recommendation) -> serde_json::Map<String, serde_json::Value> {
    match serde_json::to_value(&r.proposal) {
        Ok(serde_json::Value::Object(p)) => p,
        _ => serde_json::Map::new(),
    }
}

/// The observer type an actor label implies, used where no credential record
/// declares one (the credential map will carry an explicit `observer` field
/// when the multi-token surfaces land; this prefix heuristic is the interim
/// derivation — a *statement* must never be able to claim humanity, so the
/// answer always comes from the host-held actor label, not request text).
pub fn observer_for_principal(actor: &str) -> areev_loop::ObserverType {
    match areev_core::authz::observer_kind(actor) {
        "agent" => areev_loop::ObserverType::Agent,
        _ => areev_loop::ObserverType::Human,
    }
}

/// Wall-clock now in epoch milliseconds — the `now_ms` the engine's `run`,
/// `review`, `apply`, and `rollback` take. Kept out of `areev-loop` itself so the
/// engine stays deterministic (the caller supplies the clock).
///
/// `AREEV_LOOP_NOW_MS` (epoch ms) overrides the wall clock — the simulation seam
/// that makes a run through the real binary a pure function of (file, policy,
/// time). The golden E2E suite uses it to pin analyzer output and to step time
/// across outcome-review horizons and rejection cooldowns without sleeping.
/// A set-but-unparseable value panics: the caller asked for simulated time,
/// and silently running at wall time instead would defeat the point.
pub fn now_ms() -> i64 {
    if let Ok(v) = std::env::var("AREEV_LOOP_NOW_MS") {
        return v
            .trim()
            .parse()
            .unwrap_or_else(|_| panic!("AREEV_LOOP_NOW_MS is set but not epoch milliseconds: {v:?}"));
    }
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis() as i64)
        .unwrap_or(0)
}

#[cfg(test)]
mod authz_mapping_tests {
    use super::*;
    use areev_core::authz::{AuthzSet, Grant, Verb};

    fn granted(principal: &str, verbs: Vec<Verb>, ns: &[&str]) -> AuthzSet {
        AuthzSet::restricted(
            principal,
            vec![Grant {
                verbs,
                namespaces: ns.iter().map(|s| (*s).to_string()).collect(),
            }],
        )
    }

    // ---- #312: coverage over a recommendation's own scope ----------------

    #[test]
    fn a_namespace_grant_covers_a_finding_derived_from_that_namespace() {
        // The new capability: a reviewer granted on the namespace they work
        // in can read and decide findings derived from it — without a grant
        // on `areev-loop`, which would hand them the whole queue.
        let amy = granted("user:amy", vec![Verb::Read, Verb::LoopReview], &["a"]);
        let s = scopes_for_rec(&amy, &["a".into()]);
        assert!(s.has(areev_loop::Scope::Read));
        assert!(s.has(areev_loop::Scope::Review));
        assert!(covers_rec(&amy, &["a".into()]));
    }

    #[test]
    fn a_namespace_grant_does_not_cover_another_namespaces_finding() {
        let amy = granted("user:amy", vec![Verb::Read, Verb::LoopReview], &["a"]);
        assert!(!covers_rec(&amy, &["b".into()]));
        let s = scopes_for_rec(&amy, &["b".into()]);
        assert!(!s.has(areev_loop::Scope::Read));
        assert!(!s.has(areev_loop::Scope::Review));
    }

    #[test]
    fn coverage_needs_every_namespace_a_finding_was_derived_from() {
        // A finding derived from `a` and `b` discloses both, so holding `a`
        // alone is not enough — it is not a partial read.
        let amy = granted("user:amy", vec![Verb::Read], &["a"]);
        assert!(!covers_rec(&amy, &["a".into(), "b".into()]));
        let both = granted("user:both", vec![Verb::Read], &["a", "b"]);
        assert!(covers_rec(&both, &["a".into(), "b".into()]));
    }

    #[test]
    fn a_whole_queue_grant_still_means_the_whole_queue() {
        // Owner sessions and existing operator grants are unchanged.
        let op = granted(
            "user:op",
            vec![Verb::Read, Verb::LoopReview],
            &[areev_loop::LOOP_NS],
        );
        assert!(covers_rec(&op, &["a".into()]));
        assert!(covers_rec(&op, &["a".into(), "b".into()]));
        assert!(scopes_for_rec(&op, &["zzz".into()]).has(areev_loop::Scope::Review));
        assert!(covers_rec(&AuthzSet::owner("user:local"), &["a".into()]));
    }

    #[test]
    fn an_unscoped_finding_needs_a_whole_queue_grant() {
        // An unscoped pass — and every recommendation written before the
        // scope existed — is "derived from we-don't-know-where". Fail closed.
        let amy = granted("user:amy", vec![Verb::Read, Verb::LoopReview], &["a"]);
        assert!(!covers_rec(&amy, &[]));
        let op = granted("user:op", vec![Verb::Read], &[areev_loop::LOOP_NS]);
        assert!(covers_rec(&op, &[]));
        assert!(covers_rec(&AuthzSet::owner("user:local"), &[]));
    }

    #[test]
    fn coverage_is_per_verb() {
        // Read but not review: they can see it, and cannot decide it.
        let amy = granted("user:amy", vec![Verb::Read], &["a"]);
        let s = scopes_for_rec(&amy, &["a".into()]);
        assert!(s.has(areev_loop::Scope::Read));
        assert!(!s.has(areev_loop::Scope::Review));
        assert!(!s.has(areev_loop::Scope::Apply));
    }

    #[test]
    fn scope_normalization_is_order_and_duplicate_independent() {
        use areev_loop::normalize_scope;
        assert_eq!(
            normalize_scope(&["b".into(), "a".into(), "a".into(), "  ".into()]),
            vec!["a".to_string(), "b".to_string()]
        );
    }

    #[test]
    fn owner_maps_to_every_scope() {
        let scopes = scopes_for(&AuthzSet::owner("user:local"));
        for s in [
            areev_loop::Scope::Read,
            areev_loop::Scope::Write,
            areev_loop::Scope::Review,
            areev_loop::Scope::Apply,
            areev_loop::Scope::Admin,
        ] {
            assert!(scopes.has(s), "{s:?} missing for owner");
        }
    }

    #[test]
    fn loop_verbs_map_one_to_one_and_namespace_scoping_holds() {
        // A reviewer granted on `*` gets exactly Review (plus nothing else).
        let reviewer = AuthzSet::restricted(
            "user:rev",
            vec![Grant { verbs: vec![Verb::LoopReview], namespaces: vec!["*".into()] }],
        );
        let scopes = scopes_for(&reviewer);
        assert!(scopes.has(areev_loop::Scope::Review));
        for s in [
            areev_loop::Scope::Read,
            areev_loop::Scope::Write,
            areev_loop::Scope::Apply,
            areev_loop::Scope::Admin,
        ] {
            assert!(!scopes.has(s), "{s:?} must not be granted");
        }

        // Loop verbs are checked against the loop's own namespace — a grant
        // scoped to some data namespace does not reach the review queue.
        let elsewhere = AuthzSet::restricted(
            "user:misscoped",
            vec![Grant { verbs: vec![Verb::LoopReview], namespaces: vec!["caller".into()] }],
        );
        assert!(!scopes_for(&elsewhere).has(areev_loop::Scope::Review));
        let on_loop_ns = AuthzSet::restricted(
            "user:scoped",
            vec![Grant {
                verbs: vec![Verb::LoopReview],
                namespaces: vec![areev_loop::LOOP_NS.into()],
            }],
        );
        assert!(scopes_for(&on_loop_ns).has(areev_loop::Scope::Review));
    }

    #[test]
    fn observer_derives_from_the_actor_label() {
        use areev_loop::ObserverType;
        assert_eq!(observer_for_principal("agent:mcp"), ObserverType::Agent);
        assert_eq!(observer_for_principal("bot:sweeper"), ObserverType::Agent);
        assert_eq!(observer_for_principal("job:retention"), ObserverType::Agent);
        assert_eq!(observer_for_principal("engine:loop.llm/1"), ObserverType::Agent);
        assert_eq!(observer_for_principal("user:anna"), ObserverType::Human);
        assert_eq!(observer_for_principal("anna"), ObserverType::Human);
    }
}