car-server-core 0.55.0

//! Choosing what the self-healing loop works on next.
//!
//! Pure: no I/O, no network, no model, no clock — `now_ms` is an argument. The
//! decision is the part that must be reviewable and reproducible, so it is
//! separated from the reads that feed it and the actions that follow, in the
//! same shape `car-selfheal` already uses for detection.
//!
//! ## Deterministic, and deliberately dull
//!
//! Nothing here asks a model anything. Priority is a signal humans already
//! express through labels; inferring it would add a failure mode and buy
//! nothing. Ordering is oldest-first, which is a total order over a `u64` and
//! therefore stable across ticks — two daemons reading the same queue reach the
//! same answer, and a restart resumes where it left off rather than re-picking
//! whatever a model found most interesting this time.
//!
//! ## What "eligible" means, and why each clause exists
//!
//! Every clause below removes a way for the loop to do something a human did
//! not ask for:
//!
//! - **Authorised by provenance.** A public author can never seed a session.
//!   The label narrows; the tier authorises. See [`super::provenance`].
//! - **Opted in by label.** Silence is not consent: an unlabelled item is
//!   invisible.
//! - **Writable target.** A target with no checkout is watch-only.
//! - **Not already claimed.** Unless the claim has expired, which is how a
//!   crashed tick releases its item instead of stranding it forever.
//! - **Not already covered.** An open pull request referencing the issue means
//!   the work exists; a second one is noise a human has to close.

use std::collections::HashMap;

use super::heal_claims::Attempts;
use super::heal_intake::{ChecksState, HealTarget, RawPullRequest};
use super::provenance::ProvenanceTier;

/// How long a claim holds an item before another tick may take it.
///
/// Long enough that an ordinary coder session finishes inside it, short enough
/// that a crashed daemon does not park an issue for a day. A claim is a
/// courtesy between ticks, not a lock: the cost of getting this wrong in one
/// direction is duplicated work, and in the other a queue that silently stops
/// moving. Duplicated work is the cheaper mistake, so this errs short.
pub const CLAIM_TTL_MS: u64 = 90 * 60 * 1000;

/// One thing the loop could work on, reduced to what the decision needs.
///
/// Deliberately not a GitHub type. The selection rules are about authorisation,
/// opt-in and duplication — none of which need a body, and all of which are
/// easier to reason about when the body is not reachable. Building one of these
/// is where tracker text stops and decisions begin.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Candidate {
    pub repo: String,
    pub number: u64,
    /// The provenance tier the author resolved to, or `None` when nobody has
    /// resolved it yet.
    ///
    /// `None` is a real state, not a default to be filled in: resolving costs a
    /// `gh api` call per item and goes stale in two minutes, so the live path
    /// scans cheaply and tiers only the item it actually reaches. See
    /// [`ineligible`] for why deferring does not widen what may run.
    pub tier: Option<ProvenanceTier>,
    /// Whether the target's opt-in label is present.
    pub labelled: bool,
    /// Unix ms the item was created. The sort key.
    pub created_ms: u64,
    pub kind: CandidateKind,
}

/// What sort of work an item represents.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CandidateKind {
    /// An open issue: fix it and open a pull request.
    Issue,
    /// An open pull request whose checks are failing or whose reviewers asked
    /// for changes.
    FailingPullRequest,
}

/// An outstanding claim on an item.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Claim {
    pub run_id: String,
    pub claimed_ms: u64,
}

impl Claim {
    fn is_live(&self, now_ms: u64) -> bool {
        now_ms.saturating_sub(self.claimed_ms) < CLAIM_TTL_MS
    }
}

/// Why an item was passed over. Recorded rather than dropped, because "the
/// queue looks full but the loop does nothing" is otherwise unexplainable
/// without attaching a debugger.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
#[serde(tag = "skip", rename_all = "snake_case")]
pub enum Skip {
    /// The author may not seed a coder session at this tier.
    UntrustedAuthor { tier: ProvenanceTier },
    /// The opt-in label is absent.
    NotLabelled,
    /// The target has no checkout, so nothing can be written.
    WatchOnly,
    /// Another tick holds it.
    Claimed { run_id: String },
    /// An open pull request already references this issue.
    AlreadyCovered { pr_number: u64 },
    /// The item's text could not be trust-cleared into a session seed.
    ///
    /// Distinct from [`Self::UntrustedAuthor`], which is about the author's
    /// tier. An item can pass the tier gate and still fail clearance — most
    /// often because the tier was resolved too long ago to rely on. Reporting
    /// that as an authorisation failure sends an operator to check permissions
    /// when the remedy is to retry.
    IntentNotCleared,
    /// Closed or edited between the scan and the moment it was reached.
    ///
    /// Not a failure of anything: a human-authored queue moves while the loop
    /// reads it. Distinct from every other variant because it needs no backoff
    /// — a later tick will not see this item at all.
    Gone,
    /// Attempted before and failed; waiting out its backoff, or exhausted.
    RecentlyFailed {
        attempts: u32,
        next_eligible_ms: Option<u64>,
        reason: String,
    },
}

/// One item, with the reason it was passed over.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct SkippedItem {
    pub repo: String,
    pub number: u64,
    pub reason: Skip,
}

/// What one pass over the queue decided.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Selection {
    /// The item to work on, if any is eligible.
    pub chosen: Option<Candidate>,
    /// Everything passed over, and why.
    pub skipped: Vec<SkippedItem>,
}

/// Pick at most one item to work on.
///
/// `open_prs` is every open pull request on the same repository — used only to
/// answer "is this issue already covered". `claims` is keyed `repo#number`.
///
/// Returns `None` for `chosen` when nothing is eligible, which is the loop's
/// **steady state**: the queue is human-authored, so an empty or fully-handled
/// queue means there is nothing to do, not that something is wrong.
pub fn select(
    target: &HealTarget,
    candidates: &[Candidate],
    open_prs: &[RawPullRequest],
    claims: &HashMap<String, Claim>,
    attempts: &HashMap<String, Attempts>,
    now_ms: u64,
) -> Selection {
    let mut skipped = Vec::new();
    let mut eligible: Vec<&Candidate> = Vec::new();

    for c in candidates {
        if let Some(reason) = ineligible(target, c, open_prs, claims, attempts, now_ms) {
            skipped.push(SkippedItem {
                repo: c.repo.clone(),
                number: c.number,
                reason,
            });
            continue;
        }
        eligible.push(c);
    }

    // Oldest first, then by number, so the order is total even when two items
    // share a timestamp — otherwise two daemons could disagree about "oldest"
    // and both take work.
    eligible.sort_by_key(|c| (c.created_ms, c.number));

    Selection {
        chosen: eligible.first().map(|c| (*c).clone()),
        skipped,
    }
}

fn ineligible(
    target: &HealTarget,
    c: &Candidate,
    open_prs: &[RawPullRequest],
    claims: &HashMap<String, Claim>,
    attempts: &HashMap<String, Attempts>,
    now_ms: u64,
) -> Option<Skip> {
    // Authorisation first, when it is known. Every later clause is about
    // whether there is work to do; this one is about whether we are allowed to
    // do it at all, and a *resolved* denial must not be reachable past a
    // cheaper check that happens to return early.
    //
    // `None` is not a denial and not a grant — it is "nobody has asked yet".
    // Resolving a tier is a `gh api` call per item and deliberately memoizes
    // nothing, so tiering all 200 scanned issues up front would be 200 calls
    // per tick per target AND leave the chosen item's tier minutes stale by the
    // time the gate checks its freshness. `heal_live` therefore builds
    // candidates cheaply and resolves the tier of the one that is actually
    // reached, in `intent_for`.
    //
    // This used to be `ProvenanceTier::Public`, on the reasoning that the
    // absence of a claim about the author should authorise nothing. The
    // reasoning is right and the encoding was wrong: `Public` is a RESOLVED
    // tier meaning "this author is untrusted", so this clause rejected it
    // first, every candidate on the live path was skipped as
    // `UntrustedAuthor`, and the loop could never select anything at all. The
    // symptom was a permanently idle loop that reported a reason which was not
    // true of any of those authors.
    //
    // Deferring is safe because it does not widen what may run: `intent_for`
    // resolves the tier for real, on fresh permission data, and returns no seed
    // when it refuses — which `tick` reports as `IntentNotCleared`. Nothing
    // starts a session on an unresolved tier; the authorisation moved, it did
    // not weaken.
    if let Some(tier) = c.tier {
        if !tier.may_seed_session() {
            return Some(Skip::UntrustedAuthor { tier });
        }
    }
    if !c.labelled {
        return Some(Skip::NotLabelled);
    }
    if !target.can_write() {
        return Some(Skip::WatchOnly);
    }
    if let Some(claim) = claims.get(&claim_key(&c.repo, c.number)) {
        if claim.is_live(now_ms) {
            return Some(Skip::Claimed {
                run_id: claim.run_id.clone(),
            });
        }
    }
    // The backoff, and the only place it is READ.
    //
    // `record_failure` wrote into this map and nothing consulted it, so the
    // exponential backoff, `MAX_ATTEMPTS`, and this whole variant were dead at
    // runtime: a failing item was released with its failure recorded and then
    // re-selected on the very next tick, which is exactly the metronome the
    // ledger exists to stop. Selection is oldest-first with no other memory, so
    // if this clause does not fire, nothing moves the sweep past a item that
    // keeps failing.
    if let Some(a) = attempts.get(&claim_key(&c.repo, c.number)) {
        if !a.ready(now_ms) {
            return Some(Skip::RecentlyFailed {
                attempts: a.count,
                next_eligible_ms: a.next_eligible_ms(),
                reason: a.last_reason.clone(),
            });
        }
    }
    if c.kind == CandidateKind::Issue {
        // QUALIFIED by the tracker repo when the fix lands elsewhere. On a
        // `fix_repo` target, a bare `#123` in a pull request on the source repo
        // means issue 123 *of that repo* — reading it as the tracker's issue
        // 123 marks an unrelated item covered, permanently and silently, and
        // that item never gets worked. The qualified form existed with its own
        // doc naming this hazard and had zero production call sites. The loop's
        // own pull-request bodies write `owner/repo#N`, which matches under
        // both readings, so self-coverage is unaffected.
        let tracker = target.is_cross_repo().then_some(target.repo.as_str());
        if let Some(pr) = open_prs.iter().find(|pr| pr.references(tracker, c.number)) {
            return Some(Skip::AlreadyCovered {
                pr_number: pr.number(),
            });
        }
    }
    None
}

/// The key a claim is stored under. One spelling, because a claim written under
/// one form and read under another is a claim that never holds.
pub fn claim_key(repo: &str, number: u64) -> String {
    format!("{repo}#{number}")
}

/// Whether an open pull request is itself work: red checks, or reviewers who
/// asked for changes.
///
/// A draft is excluded — it is explicitly unfinished, and its author has not
/// asked anyone to look yet. Pending checks are excluded too: a pull request
/// whose checks have not reported is not failing.
pub fn pr_needs_work(pr: &RawPullRequest) -> bool {
    if pr.is_draft() {
        return false;
    }
    matches!(pr.checks(), ChecksState::Failing) || pr.changes_requested()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::coder::heal_intake::Checkout;

    fn target() -> HealTarget {
        HealTarget {
            repo: "acme/widgets".into(),
            fix_repo: None,
            checkout: Some(Checkout::Project("widgets".into())),
            label: "self-heal".into(),
            base: "main".into(),
        }
    }

    /// The live path's shape: scanned but not yet tiered.
    fn untiered(number: u64, labelled: bool) -> Candidate {
        Candidate {
            repo: "acme/widgets".into(),
            number,
            tier: None,
            labelled,
            created_ms: number,
            kind: CandidateKind::Issue,
        }
    }

    #[test]
    fn an_untiered_candidate_is_not_rejected_as_untrusted() {
        // THE regression. `heal_live` scans cheaply and tiers only the item it
        // reaches, so every candidate arrives here untiered. Encoding that as
        // `ProvenanceTier::Public` — a resolved "untrusted" — made this
        // function reject all of them before it looked at a single label, and
        // the live loop selected nothing, ever, while reporting a reason that
        // was not true of any of those authors.
        let out = select(
            &target(),
            &[untiered(7, true)],
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(out.chosen.map(|c| c.number), Some(7));
        assert!(out.skipped.is_empty());
    }

    #[test]
    fn an_untiered_candidate_is_still_subject_to_every_other_check() {
        // Deferring the tier must not defer anything else — an unlabelled item
        // is invisible whether or not its author has been resolved.
        let out = select(
            &target(),
            &[untiered(7, false)],
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert!(out.chosen.is_none());
        assert_eq!(out.skipped[0].reason, Skip::NotLabelled);
    }

    #[test]
    fn a_resolved_denial_still_wins_over_every_cheaper_check() {
        // The original ordering property, unchanged: a KNOWN-untrusted author
        // is refused on authorisation, not on some cheaper clause that happens
        // to fire first and would report the wrong reason.
        let mut c = candidate(7, 1, ProvenanceTier::Public);
        c.labelled = false;
        let out = select(&target(), &[c], &[], &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(
            out.skipped[0].reason,
            Skip::UntrustedAuthor {
                tier: ProvenanceTier::Public
            }
        );
    }

    fn candidate(number: u64, created_ms: u64, tier: ProvenanceTier) -> Candidate {
        Candidate {
            repo: "acme/widgets".into(),
            number,
            tier: Some(tier),
            labelled: true,
            created_ms,
            kind: CandidateKind::Issue,
        }
    }

    fn pr_with(number: u64, body: &str) -> RawPullRequest {
        RawPullRequest::new(
            "acme/widgets",
            number,
            "someone",
            "a pull request",
            body,
            vec![],
            ChecksState::Passing,
            "",
            false,
        )
    }

    #[test]
    fn an_empty_queue_selects_nothing() {
        let s = select(&target(), &[], &[], &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(s.chosen, None, "idle is the steady state, not an error");
        assert!(s.skipped.is_empty());
    }

    #[test]
    fn a_public_author_can_never_seed_a_session() {
        // The sharp one: `car-releases` is public, so this is the difference
        // between a loop and an arbitrary-code-execution surface.
        let c = candidate(1, 0, ProvenanceTier::Public);
        let s = select(&target(), &[c], &[], &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(s.chosen, None);
        assert_eq!(
            s.skipped[0].reason,
            Skip::UntrustedAuthor {
                tier: ProvenanceTier::Public
            }
        );
    }

    #[test]
    fn authorisation_is_checked_before_anything_cheaper() {
        // An unlabelled PUBLIC issue must report the tier, not the label:
        // otherwise a reader concludes "add the label and it will run", which
        // is false and dangerously reassuring.
        let mut c = candidate(1, 0, ProvenanceTier::Public);
        c.labelled = false;
        let s = select(&target(), &[c], &[], &HashMap::new(), &HashMap::new(), 0);
        assert!(matches!(s.skipped[0].reason, Skip::UntrustedAuthor { .. }));
    }

    #[test]
    fn an_unlabelled_item_is_invisible() {
        let mut c = candidate(1, 0, ProvenanceTier::Maintainer);
        c.labelled = false;
        let s = select(&target(), &[c], &[], &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(s.chosen, None);
        assert_eq!(s.skipped[0].reason, Skip::NotLabelled);
    }

    #[test]
    fn a_maintainer_issue_is_eligible() {
        let c = candidate(1, 0, ProvenanceTier::Maintainer);
        let s = select(
            &target(),
            std::slice::from_ref(&c),
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s.chosen, Some(c));
    }

    #[test]
    fn a_watch_only_target_selects_nothing() {
        let mut t = target();
        t.checkout = None;
        let c = candidate(1, 0, ProvenanceTier::Maintainer);
        let s = select(&t, &[c], &[], &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(s.chosen, None);
        assert_eq!(s.skipped[0].reason, Skip::WatchOnly);
    }

    #[test]
    fn oldest_first_and_stable_when_timestamps_tie() {
        let a = candidate(9, 100, ProvenanceTier::Maintainer);
        let b = candidate(2, 100, ProvenanceTier::Maintainer);
        let older = candidate(5, 50, ProvenanceTier::Maintainer);
        let s = select(
            &target(),
            &[a, b.clone(), older.clone()],
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s.chosen, Some(older), "oldest wins");

        // With the oldest gone, the tie between 9 and 2 resolves by number, so
        // two daemons reading the same queue cannot disagree.
        let s2 = select(
            &target(),
            &[candidate(9, 100, ProvenanceTier::Maintainer), b.clone()],
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s2.chosen, Some(b));
    }

    #[test]
    fn a_live_claim_holds_the_item() {
        let c = candidate(1, 0, ProvenanceTier::Maintainer);
        let mut claims = HashMap::new();
        claims.insert(
            claim_key("acme/widgets", 1),
            Claim {
                run_id: "run-a".into(),
                claimed_ms: 1_000,
            },
        );
        let s = select(
            &target(),
            &[c],
            &[],
            &claims,
            &HashMap::new(),
            1_000 + CLAIM_TTL_MS - 1,
        );
        assert_eq!(s.chosen, None);
        assert_eq!(
            s.skipped[0].reason,
            Skip::Claimed {
                run_id: "run-a".into()
            }
        );
    }

    #[test]
    fn an_expired_claim_releases_the_item() {
        // How a crashed tick gives its work back instead of parking it.
        let c = candidate(1, 0, ProvenanceTier::Maintainer);
        let mut claims = HashMap::new();
        claims.insert(
            claim_key("acme/widgets", 1),
            Claim {
                run_id: "dead-run".into(),
                claimed_ms: 1_000,
            },
        );
        let s = select(
            &target(),
            std::slice::from_ref(&c),
            &[],
            &claims,
            &HashMap::new(),
            1_000 + CLAIM_TTL_MS,
        );
        assert_eq!(s.chosen, Some(c));
    }

    #[test]
    fn an_issue_already_covered_by_a_pull_request_is_skipped() {
        let c = candidate(42, 0, ProvenanceTier::Maintainer);
        let prs = vec![pr_with(7, "fixes #42")];
        let s = select(&target(), &[c], &prs, &HashMap::new(), &HashMap::new(), 0);
        assert_eq!(s.chosen, None);
        assert_eq!(s.skipped[0].reason, Skip::AlreadyCovered { pr_number: 7 });
    }

    #[test]
    fn a_pull_request_for_a_different_issue_does_not_cover_this_one() {
        let c = candidate(42, 0, ProvenanceTier::Maintainer);
        let prs = vec![pr_with(7, "fixes #43")];
        let s = select(
            &target(),
            std::slice::from_ref(&c),
            &prs,
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s.chosen, Some(c));
    }

    #[test]
    fn coverage_does_not_apply_to_a_failing_pull_request() {
        // A failing PR is not "covered by" itself; that clause is about issues.
        let mut c = candidate(7, 0, ProvenanceTier::Maintainer);
        c.kind = CandidateKind::FailingPullRequest;
        let prs = vec![pr_with(7, "this is the pull request itself, #7")];
        let s = select(
            &target(),
            std::slice::from_ref(&c),
            &prs,
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s.chosen, Some(c));
    }

    #[test]
    fn a_draft_is_never_work() {
        let pr = RawPullRequest::new(
            "acme/widgets",
            1,
            "someone",
            "wip",
            "",
            vec![],
            ChecksState::Failing,
            "",
            true,
        );
        assert!(!pr_needs_work(&pr), "a draft has not asked for review");
    }

    #[test]
    fn pending_checks_are_not_failure() {
        let pr = RawPullRequest::new(
            "acme/widgets",
            1,
            "someone",
            "t",
            "",
            vec![],
            ChecksState::Pending,
            "",
            false,
        );
        assert!(!pr_needs_work(&pr));
    }

    #[test]
    fn failing_checks_or_requested_changes_are_work() {
        let failing = RawPullRequest::new(
            "acme/widgets",
            1,
            "s",
            "t",
            "",
            vec![],
            ChecksState::Failing,
            "",
            false,
        );
        assert!(pr_needs_work(&failing));

        let changes = RawPullRequest::new(
            "acme/widgets",
            2,
            "s",
            "t",
            "",
            vec![],
            ChecksState::Passing,
            "CHANGES_REQUESTED",
            false,
        );
        assert!(pr_needs_work(&changes));
    }

    #[test]
    fn every_skip_is_recorded_so_an_idle_loop_can_be_explained() {
        let mut public = candidate(1, 0, ProvenanceTier::Public);
        public.labelled = true;
        let mut unlabelled = candidate(2, 0, ProvenanceTier::Maintainer);
        unlabelled.labelled = false;
        let s = select(
            &target(),
            &[public, unlabelled],
            &[],
            &HashMap::new(),
            &HashMap::new(),
            0,
        );
        assert_eq!(s.chosen, None);
        assert_eq!(s.skipped.len(), 2, "silence would be unexplainable");
    }
}