# Detectors

A detector is a rule over rollups with a published threshold. It opens an ordinary issue, in the same
stream as crashes, or it does not. No model decides whether it fires, resolves or pages.

Every detector has a **version**, a **state** and a measured **precision**:

| State | What it does |
| --- | --- |
| `live` | Opens its output (an issue, or an alert for the seasonal anomaly). |
| `shadow` | Runs and records every finding, and opens nothing. |
| `retired` | Records nothing and opens nothing. |

A new version starts in `shadow`. It becomes `live` when at least **50** labelled findings have a
precision of at least **0.7**; below either bound it stays in shadow. That promotion is not an action
anyone takes: it is computed from the labels by Bucker's labels pass, and there is no route, tool or
setting that sets it.

The detectors that existed before this registry (seasonal anomaly, latency regression, the performance
patterns and the seven agent-issue kinds) are `live` with precision **not measured**. They keep opening
issues; the gate applies to their next version.

## What a detector reads

Rollups, never raw tables. The registry refuses a detector whose input is a raw telemetry table, with
one exception that only shrinks: the already-built detectors that read spans.

## Labels

A finding is labelled `confirmed` or `not_useful`.

- **Issue outcomes.** When an issue a detector opened is resolved, that is a `confirmed` label; when it is
  permanently archived, it is `not_useful`. A snooze is neither.
- **Shadow review.** A shadow version opens nothing, so its findings could never earn labels from issues.
  Each shadow finding is listed for the project, and a person marks it confirmed or not useful, with one
  reason from a fixed list (`expected_behavior`, `too_noisy`, `duplicate`, `wrong_subject`,
  `threshold_too_tight`, `not_actionable`, `other`). Only a person signed in to the dashboard can do this;
  an agent, a delegation or an OAuth client is refused, because labels decide when a version starts opening
  issues for every project.

Precision is confirmed over labelled findings, one verdict per finding (the newest label wins). A version's
precision counts the labels of every project and names none of them.

## Asking why

`detector_explain` (MCP) and `GET /orgs/:org/projects/:project/detectors/:id/explain` answer from the
stored run record: the inputs (rollup ids and a digest), the window, the value against the threshold and the
decision. They never recompute.

- `decided` — the run exists; the decision is `fired`, `held` or `shadow`.
- `not_enough_data` — the detector lacked the data it needs and decided nothing. This is a result.
- `no_run_recorded` — no run covers that moment. Runs are kept 30 days, and a detector records a run when it
  fires (some also when they lack data), so this does not mean the detector was healthy.

## Reading the registry

`detectors_list` (MCP) and `GET /orgs/:org/projects/:project/detectors` return each detector's version,
state, owner card, inputs, output, published thresholds, precision with its sample size, the last run for
this project, and the project's own count of shadow findings still waiting for a label.

`GET …/detectors/:id/shadow-findings` lists a project's shadow findings (`?unlabelled=true` for the review
list) and `POST …/detectors/:id/shadow-findings/:runId/label` records a verdict.

## Changing a threshold

Not here. A threshold is changed by the area that owns the detector, through its own governed action, with
a simulation attached. Loosening one is a silencing act with a time limit. Simulating a detector over
history is not built yet (`simulateDetector` answers `not_available` and says why).
