metrics: cg_component_gate_declines_total carries events that are not declines

[amiddavid]

rep.Gate is used as a component's per-event histogram, and it surfaces through the Prometheus series cg_component_gate_declines_total{component,gate}. Several of the events it now carries are not declines:

• extract_llm_sweep: sweep_dropped, sweep_adjudicated, sweep_offered — these count work done, not work refused.
• extract_llm: reapplied_same_session, reapplied_cross_session — a cache hit, i.e. a success.

So a dashboard or alert reading that series as "how often did components decline to act" is reading a mixture of declines and successes, and the more a component succeeds the higher its "declines" go. Anyone summing it to reason about pipeline effectiveness gets the wrong sign.

Pre-existing and shipped, which is the reason it was not fixed in #118: the series name is in use, and renaming it is a breaking change for whatever scrapes and graphs it. extract_llm already had this shape before the sweep component existed.

The options, and why this needs a decision rather than a patch

1. Rename the series to something honest (cg_component_gate_events_total) and keep the old name as an alias for a deprecation window. Correct, but touches every dashboard and alert that references it.
2. Split the series — declines stay in the current name, non-decline events move to a new one. Most accurate, most work, and it means each component's gate calls have to be classified.
3. Leave it and document the convention where it is read, not just where it is written. Cheapest; leaves a metric whose name misdescribes its contents, which is how it produced this issue.

Found by

The implementation pass for #118, which added the sweep counters and noticed they were landing in a series named for the opposite of what they measure. Flagged rather than renamed, since a shipped series is not something to change as a side effect of unrelated work.

[amiddavid]

Fixed in 59606c5 on feat/sweep-adjudicator (#118), taking option 2 — split the series — since as you noted both ends live in this repo and there is therefore no compatibility problem to carry.

Split at the API, not in the exporter. Report.Event/EventN write a second map and the call site says which one it is. Classifying names inside promexport was the other option and it is the wrong place: there are 58 gate names across 31 files, they are string literals with no static enumeration, so a lookup table would have been stale within a release and the judgement would sit where the author is not.

The axis is one question — did the component ACT, or did it turn a candidate away. Eleven names moved:

reapplied_same_session, reapplied_cross_session, model_source_fell_back_to_config, sweep_adjudicated, sweep_dropped, sweep_offered, sweep_candidate_at_depth, sweep_prefix_cache_read_ok, sweep_fallback_used, sweep_inventory_of_one, sweep_inventory_thinned.

Everything meaning "we did not act on this candidate" stays a decline — including the ones that read like observations but resolve toward keep (sweep_kept, sweep_kept_everything, sweep_quote_fabricated, sweep_drop_refused_obligation) and sweep_inventory_below_min, since declining to ask is a decline.

Both ends updated, which is what made the blunt fix safe: producer proxy/promexport.go now emits cg_component_events_total{component,event} beside the declines series, and the consumers — the Grafana panel in deploy/grafana/dashboards/context-guru-logs.json and docs/reference/routes.md — say the declines series carries declines only and name where the rest went.

TestGatesAndEventsAreDisjoint pins the invariant that makes the split mean anything: a name in both maps would mean the component cannot say whether the thing succeeded or was refused, and a consumer summing either series would double-count it.

Two things worth recording as done deliberately:

• metrics.addEvents is a separate method rather than addGates with a different target. One function writing to whichever map it is handed is how the two would come back together. It is also deep-copied in forSnapshot beside Gates, in the same place, for the reason already recorded there — a shallow copy once handed the live map to /stats and raced the observe worker pool.
• The sweep's counter-contract test now looks a name up across both histograms. What it pins is that the component raises the contracted name; which series it lands in is the exporter's contract (proxy/sweep_counters_test.go) and disjointness is the components one. Asserting all three in one fixture would make it fail for unrelated reasons.

Left alone: cg_extract_gate_declines_total{reason} is a separate series with its own vocabulary and nothing in it is a success.