didbot_policy/

outcome.rs

//! The evaluator contract: what a policy decides, how stale its view may be,
//! and the three channels an evaluator is asked to answer on.

use std::time::Duration;

use crate::policy::{CompiledId, PolicyId};
use crate::subject::Subject;

/// What one policy decides about one subject.
///
/// Deny-only: no variant grants. An empty policy set — or a subject no
/// policy applies to — permits everything by the absence of any [`Outcome`]
/// at all, never by one of these variants saying so.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Outcome {
    /// This policy has nothing to say against the subject.
    Allow,
    /// This policy refuses the subject. `reason` is authored by the policy
    /// itself, since the policy is the only thing that knows which parts of
    /// its input are safe to surface to the caller.
    Reject {
        /// Why this policy refused.
        reason: String,
    },
    /// This policy refuses the subject *and* judges the account unfit to keep
    /// writing until an operator intervenes.
    Freeze {
        /// Why this policy froze the account.
        reason: String,
    },
}

/// How stale an evaluator's view of the world may be before it is
/// unhealthy.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Staleness {
    /// Blocks rather than answer from a stale view. Its lag bound is its
    /// latency bound, and it is a throughput ceiling — the right choice for
    /// a deterministic, in-process evaluator whose answer is exact and
    /// cheap.
    Linearized,
    /// Answers from what it has seen. Exceeding `max_lag` is a health
    /// failure, routed the same way a crashed evaluator is: the writes the
    /// tree scopes to it are refused until it catches up.
    BestEffort {
        /// The most this evaluator's view may lag reality before it counts
        /// as unhealthy.
        max_lag: Duration,
    },
}

/// One evaluator's account of a single policy's attempt and outcome, on its
/// declared observation surface.
///
/// The decision channel ([`Evaluator::evaluate`]) short-circuits once an
/// overall verdict cannot get any more severe. This one does not: a
/// metapolicy that freezes agents for repeatedly tripping other policies has
/// to see every attempt and outcome on its declared surface, whether or not
/// evaluation of the write as a whole stopped early.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Observed<'a> {
    /// The subject the attempt was against.
    pub subject: &'a Subject<'a>,
    /// Which policy this attempt and outcome belong to, in this crate's own
    /// bookkeeping -- useful for a caller correlating this event with a
    /// [`crate::evaluate::Verdict`], but not what an evaluator serving many
    /// compiled policies uses to tell them apart; see `compiled`.
    pub policy: PolicyId,
    /// Which compiled artifact this attempt and outcome belong to, in the
    /// evaluator's own naming -- see [`CompiledId`]'s doc comment. This,
    /// not `policy`, is what a multi-policy evaluator consults.
    pub compiled: CompiledId,
    /// The verdict every policy that judged the subject reached together:
    /// what the write path did with the attempt, not only what this policy
    /// said.
    pub outcome: &'a Outcome,
}

/// An account-lifecycle event, so an evaluator's per-account state does not
/// outlive the account it belongs to. Not agent-only — any
/// [`AccountKind`](crate::subject::AccountKind) can be frozen, unfrozen or
/// deleted.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Lifecycle<'a> {
    /// The account was frozen. Carries why, so state that reflects the
    /// freeze reason can be told apart from state that predates it.
    Frozen {
        /// The frozen account.
        account: &'a str,
        /// Why it was frozen.
        reason: &'a str,
    },
    /// The account was unfrozen by an operator. An evaluator that does not
    /// act on this will re-trip the freeze on the next attempt, because the
    /// state that caused it survives — see `plan/policy.md`'s "an evaluator
    /// can never unfreeze" note.
    Unfrozen {
        /// The unfrozen account.
        account: &'a str,
    },
    /// The account no longer exists.
    Deleted {
        /// The deleted account.
        account: &'a str,
    },
}

/// A policy-lifecycle event, parallel to [`Lifecycle`] but scoped to a
/// compiled artifact rather than an account. Without it, an evaluator that
/// accumulates state per compiled policy (a cache, a counter) has no way to
/// learn that one of its artifacts no longer corresponds to anything the
/// tree will ever route to again, and keeps it forever.
///
/// Delivery is not reliable, and does not need to be: a caller who never
/// sends [`Removed`](PolicyLifecycle::Removed) for a policy that stopped
/// existing has left an evaluator holding a stale artifact, but the tree
/// this crate builds decides what is routed anywhere -- a stale artifact
/// nothing routes to is a memory leak, never a correctness problem. See
/// `plan/policy.md`'s "a missed removal is inert, not dangerous." Do not
/// build retry or acknowledgement machinery for this channel.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PolicyLifecycle {
    /// `compile` produced this artifact and it is now (or remains) the one
    /// a tree may route decisions to.
    Loaded(CompiledId),
    /// A newer compile of the same logical policy succeeded, and this
    /// artifact is no longer the one any tree routes to -- safe to drop.
    /// Never sent when a newer revision *failed* to compile: `didbot-pds`'s
    /// loader keeps routing to the last-good artifact in that case, so it
    /// is very much still in use -- see `plan/policy.md`'s last-good-
    /// revision behaviour.
    Superseded(CompiledId),
    /// The record this artifact was compiled from is gone from every
    /// source -- deleted, or never re-observed after a source's own
    /// failure recovered onto a view that no longer names it. Safe to
    /// drop.
    Removed(CompiledId),
}

/// What [`Evaluator::compile`] decided about one predicate document.
///
/// Three outcomes, not two, because a working compile and a working compile
/// with something the operator should see are different enough to need
/// different handling downstream (an operator-facing report, never a
/// blocked policy) and collapsing them would either bury the warning or
/// promote it to a rejection it never earned.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CompileOutcome {
    /// `predicate` compiled cleanly. `evaluate`/`observe`/`policy_lifecycle`
    /// calls for this policy should name this [`CompiledId`] from now on.
    Compiled(CompiledId),
    /// `predicate` compiled, but the evaluator has something to say about
    /// it that does not block it from being used -- e.g. "this pattern is
    /// vulnerable to homoglyphs, normalize first." Reaches the operator;
    /// never the caller's decision to invent on the evaluator's behalf,
    /// since only the evaluator knows what is actually wrong with its own
    /// compiled form.
    CompiledWithWarnings(CompiledId, Vec<String>),
    /// `predicate` could not be compiled at all: bad syntax, an
    /// unsupported combination, whatever this evaluator wants to say. The
    /// caller treats this exactly like an unrecognised `language`
    /// -- [`crate::policy::Predicate::Unusable`],
    /// scoped to this policy's own applicability -- except that
    /// `didbot-pds`'s loader additionally checks whether an earlier
    /// revision of the same policy last compiled successfully, and if so
    /// keeps enforcing that one instead. See `plan/policy.md`'s
    /// last-good-revision behaviour for why a rejection here must never by
    /// itself widen or produce a blanket denial.
    Rejected(String),
}

/// Why an evaluator could not produce an [`Outcome`].
///
/// A [`PolicyTree`](crate::index::PolicyTree)'s evaluation treats any
/// `EvalError` as a refusal of the subject it was judging — fail-closed,
/// scoped to exactly the writes that evaluator was asked about. It never
/// escalates an error into [`Outcome::Freeze`] on its own: freezing an
/// account is a judgement about the account, not a side effect of
/// infrastructure being unavailable.
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
pub enum EvalError {
    /// The evaluator did not answer within its caller-enforced deadline.
    #[error("evaluator timed out")]
    Timeout,
    /// The evaluator's view is more than `Staleness::BestEffort`'s `max_lag`
    /// behind, or it could not be reached at all.
    #[error("evaluator unavailable: {0}")]
    Unavailable(String),
    /// The evaluator was reached and answered, but the answer was not a
    /// verdict — a crash, a malformed response, an internal invariant it
    /// caught itself violating.
    #[error("evaluator failed: {0}")]
    Failed(String),
}

/// What judges one or more policies.
///
/// Implemented once per language or per stateful mechanism, not once per
/// policy: `plan/policy.md`'s "one evaluator may serve many policies" is why
/// [`evaluate`](Evaluator::evaluate) takes a [`PolicyId`] rather than the
/// evaluator being scoped to a single policy at construction.
///
/// No method here is `async`, and none may perform I/O that assumes a
/// runtime is available to drive it — this crate has no I/O and no async of
/// its own. An evaluator that needs either (a network resolution, a model in
/// the loop, a sidecar process) does so out of process, reached over
/// whatever transport it likes, with the caller enforcing the deadline from
/// outside — see `plan/policy.md`'s "the deadline is a security parameter".
///
/// # What a stateless predicate may reference
///
/// [`evaluate`](Evaluator::evaluate) takes a [`Subject`] and nothing else —
/// no store handle, no resolver, no context object that could later grow
/// one. That signature is the enforcement, not a rule an implementor is
/// trusted to follow: a predicate physically cannot reach for a record it
/// was not handed, because nothing reachable from its arguments can fetch
/// one. What it *can* see, all from `Subject` itself:
///
/// 1. **The subject's own metadata** — its account DID, and whatever
///    [`SubjectAttributes`](crate::subject::SubjectAttributes) names (its
///    account kind and handle, today).
/// 2. **The incoming write** — each [`Change::after`](crate::subject::Change::after)
///    in the diff.
/// 3. **The current version, if it exists** — each
///    [`Change::before`](crate::subject::Change::before), with `None`
///    meaning there isn't one.
///
/// Nothing else. Not another record, not another account's repository, not
/// the network. An evaluator's own accumulated *state* — built from what it
/// has observed via [`observe`](Evaluator::observe) and
/// [`lifecycle`](Evaluator::lifecycle), and read back through `&self` — is
/// a different thing and is exactly what makes an evaluator *stateful*
/// rather than stateless; the boundary here is about what `evaluate` can
/// reach *live*, at the moment it is asked, not about what an evaluator is
/// allowed to remember.
///
/// This is a check on the design, not just a restriction: the epic's
/// motivating *mention / AI opt-out* policy needs to resolve DIDs from
/// other people's servers and cache the answers, which this signature makes
/// impossible for a stateless predicate to do inside `evaluate` itself. That
/// policy is therefore necessarily stateful — owning its cache as state
/// built from what it has seen, with its own [`Staleness`] declaration —
/// exactly where `plan/policy.md` puts it.
/// `Send + Sync`: every evaluator is held as `Arc<dyn Evaluator>` inside a
/// [`PolicyTree`](crate::index::PolicyTree), which a deployment's write path
/// shares across every repository's concurrently-judged writes (see
/// `didbot-pds::writequeue`) — an evaluator that could not cross a thread
/// boundary could never actually be registered into one.
pub trait Evaluator: Send + Sync {
    /// Compile a predicate document into a live artifact this evaluator can
    /// judge, or say why it cannot.
    ///
    /// Validation *is* compilation here — there is deliberately no separate
    /// `validate`: anything a caller would learn from validating ahead of
    /// time is exactly what a real compile attempt already answers, and a
    /// second code path claiming to answer the same question is drift
    /// waiting to happen. Called from the loader, never from the write
    /// path, so a predicate's syntax is known good or known bad from the
    /// moment it is loaded rather than surfacing at the first write.
    ///
    /// # The evaluator owns the artifact
    ///
    /// A successful outcome carries a [`CompiledId`] this evaluator itself
    /// minted; the caller keeps only that id, never the artifact, and
    /// round-trips the id back through `evaluate`, `observe` and
    /// `policy_lifecycle`. See [`CompiledId`]'s doc comment for why: an
    /// evaluator may run out of process, possibly in another language, and
    /// a caller-owned handle to something living on the other side of that
    /// boundary could only ever be an identifier, never the thing itself.
    ///
    /// # Idempotent and re-runnable
    ///
    /// An out-of-process evaluator restarts with nothing, so a caller must
    /// be able to call `compile` again for a predicate it already compiled
    /// once, with no different treatment than the first time — which is
    /// also why a caller must keep the source document around rather than
    /// discarding it once a `CompiledId` comes back. Calling `compile`
    /// twice for the same predicate is expected to succeed both times, not
    /// treated as a duplicate registration.
    ///
    /// # Fallible, and may time out
    ///
    /// This method itself has no deadline built in — this crate has no
    /// I/O, no async, and no clock, and enforcing one against an
    /// in-process call is cooperative rather than real. A caller compiling
    /// against a slow or dead out-of-process evaluator enforces its own
    /// deadline from outside (a `didbot-policy-records`-owned timeout, a
    /// bounded channel) and treats a timeout exactly like
    /// [`Rejected`](CompileOutcome::Rejected): this policy's applicability
    /// is known-good, its predicate is not usable, so the caller registers
    /// [`crate::policy::Predicate::Unusable`] scoped to it — the same
    /// fail-closed, scoped treatment [`EvalError`] gets at decision time.
    fn compile(&self, predicate: &serde_json::Value) -> CompileOutcome;

    /// Given a subject and a compiled artifact, return an outcome, from
    /// only what `subject` carries — see this trait's "What a stateless
    /// predicate may reference" for the boundary the signature enforces.
    /// `compiled` names the artifact [`compile`](Evaluator::compile)
    /// returned for this policy, never [`PolicyId`] — an evaluator serving
    /// many compiled policies tells them apart by `compiled` alone; it
    /// never learns `PolicyId`, which belongs to the caller's own tree.
    fn evaluate(&self, subject: &Subject<'_>, compiled: CompiledId) -> Result<Outcome, EvalError>;

    /// Every attempt and outcome on the declared observation surface,
    /// whether or not evaluation short-circuited. The decision channel
    /// short-circuits; this one does not.
    fn observe(&self, event: &Observed<'_>);

    /// froze / unfroze / deleted, so per-account state does not outlive its
    /// account.
    fn lifecycle(&self, event: &Lifecycle<'_>);

    /// loaded / superseded / removed, so per-policy state does not outlive
    /// the artifact it belongs to — see [`PolicyLifecycle`]'s doc comment.
    /// Defaulted to a no-op: an evaluator that holds no state per compiled
    /// artifact (this crate's regex evaluator, most builtins) has nothing
    /// to clean up, and should not be forced to write an empty override
    /// just to say so.
    fn policy_lifecycle(&self, event: PolicyLifecycle) {
        let _ = event;
    }

    /// How stale this evaluator's view may be before it counts as unhealthy.
    fn staleness(&self) -> Staleness;
}