fix(scan,get): rank patches by severity, then merge state, then patch recency

[Mikola Lysenko (mikolalysenko)]

The bug

Running scan as a logged-in/authorized user picked the wrong patch when a package had more than one available. select_patches — the single selector both get and every scan mode route through — never consulted severity at all:

group.sort_by(|a, b| b.published_at.cmp(&a.published_at));   // "newest first"
let choice = group.iter().find(|p| p.tier == "paid").or_else(|| group.first())

For can_access_paid == true that is "newest paid patch, else newest patch". A package whose newest patch fixed a low got that one, and its critical patch was silently dropped.

Two more things surfaced while verifying against the live API, both hidden by this repo's fixtures:

1. publishedAt is RFC 2822 / HTTP-date on the wire — Fri, 27 Mar 2026 19:12:42 GMT, confirmed across npm, PyPI, cargo and gem. The String::cmp above therefore sorts by day-of-week name (Fri < Mon < Sat < Sun < Thu < Tue < Wed). Every in-repo fixture uses ISO-8601, which is why this was never caught. "Newest first" was not even true.
2. A second, independent chooser. detect_updates took .first() off the raw batch response with no ordering. So updates[].newUuid could name a different patch than --apply installed.

The order now

Best first, one comparator (socket_patch_core::api::ranking) for selection and every listing:

1. Severity — critical > high > medium/moderate > low > unknown, worst across everything the patch fixes
2. Merge state — a patch remediating more advisories in one blob leads
3. Patch publish date, most recent first
4. tier (paid), then uuid — tiebreaks only, so the order is total and output is reproducible

Merge state is inferred, not reported — no upstream change needed

There is no merged field on the wire and none is required. A merged patch is by definition one that folds several fixes into a single blob, so it names several advisories, which every endpoint already returns. Merge state is the count of distinct advisories a patch remediates: vulnerabilities map keys on by-package/view, ghsaIds on batch (falling back to cveIds only when no GHSA is named).

Advisories are counted, not CVE ids — one advisory routinely carries several CVE aliases, and counting those would inflate a single-fix patch into a phantom merged one.

Production survey, 2026-08-05 (63 PURLs queried, 32 with patches, 28 patches total):

advisories per patch (histogram): {1: 28}
patches covering >=2 advisories:  0

So the rung is inert today and ranking falls through to recency. I also confirmed the multiple patches for a package are built against a shared pristine baseline (identical beforeHash) and conflict rather than chain — e.g. axios lib/adapters/http.js goes from 5bbe4571… to two different outputs. There is no merged patch to find yet; this is not a detection failure. The moment one is published it is preferred automatically, with no client or server change.

Why severity sits above merge state

The merged patch is the general preference — breadth is what an operator wants when only one patch per PURL can be applied — but it must never shadow a worse vulnerability. Because a patch's severity is the worst advisory it fixes, putting severity on the top rung expresses that exactly:

merged patch	rival patch	winner	why
high	critical	rival	higher severity available
critical	high	merged	merged already covers the worst
high	high	merged	severities tie → breadth decides

tier is an access filter, not a ranking key

A free critical outranks a paid low. This deliberately reverses select_paid_user_prefers_paid_over_free_same_purl, which now holds only when everything above tier ties.

Rank 3 is the patch's date

Never the upstream package's release date. axios@1.6.0 shipped to npm 2023-10-26 and carries patches published 2026-03-27 and 2026-08-03.

Implementation

• api/ranking.rs (new) — the single comparator. Ordering is normalized at the API-client boundary, so the table, --json arrays, get's listing, the interactive prompt and detect_updates all inherit it rather than each re-deriving it.
• utils/date.rs (new) — parses RFC 2822, RFC 3339 and bare dates to epoch seconds. No new dependency; reuses the Hinnant calendar algorithm already in vex::time, and pins the inverse against it.
• The three duplicated severity ladders now delegate to one.
• Free/unauthorized callers keep the interactive picker and the selection_required JSON error. Only the presented order changed — which is what fixes scan for them too, since select_one auto-selects index 0 in non-TTY and defaults to it in a TTY.

Known gap

The batch endpoint omits publishedAt; by-package carries it. Ranks 1, 2 and 4 agree across both, so they diverge only when top candidates tie on severity and merge state — there the batch side falls to the UUID tiebreak while apply correctly uses the date.

Live: pkg:npm/axios@1.6.0 has two free HIGH patches; packages[0].patches[0] reports 0bc312a6… (2026-03-27) while --apply installs the newer 83f5a654… (2026-08-03), the correct choice. Only the reported ordering is affected — never which patch lands on disk. Documented in CLI_CONTRACT.md; BatchPatchInfo.published_at is already wired with #[serde(default)], so it closes once the batch endpoint emits it.

Testing

3891 pass, 0 fail. CI clippy (--workspace --all-features -D warnings) clean; changed files rustfmt-clean.

Both new rungs are mutation-checked:

mutation	tests that die
coverage rung stubbed to a constant	9 across core, cli, wiremock e2e
coverage promoted above severity (loses the "unless higher severity" rule)	3, exactly the exception cases
patch-date rung stubbed to a constant	8 across core, cli, wiremock e2e

That exercise also caught two of my own recency tests passing vacuously — their UUIDs happened to agree with the correct answer, so the tiebreak was silently supplying the result. They now use adversarial UUIDs where the tiebreak points the wrong way.

Coverage highlights:

• Closed a real gap: no test anywhere asserted which patch scan picks with multiple candidates — every prior scan fixture mocked exactly one patch per package.
• merged_patch_wins_when_severities_tie / a_higher_severity_patch_beats_the_merged_one / merged_patch_wins_when_it_already_covers_the_worst_advisory — the three rows of the table above.
• coverage_counts_advisories_not_cve_aliases + batch twin, and batch_falls_back_to_cve_ids_when_no_ghsa_is_named.
• scan_apply_picks_critical_over_more_recent_low_for_paid_user, the free/non-TTY twin, and scan_apply_picks_the_more_recently_published_patch_when_severity_ties.
• published_at_is_per_patch_not_per_package — verbatim production payload: one package version, two patches, two dates.
• Two live production canaries (#[ignore], verified passing):
  • canary_patches_name_advisories_so_merge_state_is_inferable — guards the inference signal itself. If production stopped populating vulnerabilities, coverage would collapse to 0, the merge rung would go permanently inert, and selection would fall through to recency with no error anywhere. Asserts only that the signal exists, never a count, so publishing a genuinely merged patch does not fail it — that is reported informationally.
  • canary_published_at_is_a_patch_date_not_a_package_date — fails if the API switches publishedAt to a package-level date.
• Full utils::date suite: all 12 RFC-2822 months, zone aliases and offsets, RFC-3339 variants, rejection cases, adversarial non-ASCII input, a monotonicity sweep, and an exhaustive cross-check of the calendar inverse over ~1265 years.

Out of scope

The manifest still holds one patch record per PURL, so a package with two applicable patches still gets only its best one (axios@1.6.0 has two free HIGH patches; applying one reverts the other — they conflict on lib/adapters/http.js). Pre-existing and tracked separately.

🤖 Generated with Claude Code