Core concepts

Evidence

Findings are confirmed, refuted, or unknown. A check that could not run never renders as one that came back clean.

This is the rule the product exists to enforce, so it is worth understanding before anything else.

A check has three possible outcomes, not two:

confirmed: The check ran and the claim holds.
refuted: The check ran and the claim does not hold. This is a real negative result.
unknown: The check could not run. reason says why — an unverified contract, a missing credential, an upstream outage.

Where this keeps breaking

The subtle case is not an error — it is a successful response with an empty field. A chain explorer returns HTTP 200 with is_verified: null for a contract it has no record of. Reading that as "not verified" is wrong; reading it as nothing at all is worse, because then no finding is produced and an unverified token scores identically to a verified one.

When a source answers successfully with an empty field, the emptiness has to mean something explicit. That decision is made once, at the point of reading, and never left to fall through.

What follows from it

Every feature added since inherits this rule:

A portfolio screen that could not run every check reports its score as a ceiling — is_upper_bound is true, and the real score can only be lower.
A comparison with nothing to compare against returns nothing, rather than the words "no changes".
An execution with no summary credential reports summary_status: not_configured instead of generating filler.
A workflow step that could not run appears in the timeline with its reason, rather than being omitted.
Confidence is unknown rather than low when nothing was established at all.

Reading a finding

evidence item

{
  "id": "ev_...",
  "stage": "evidence",
  "kind": "contract:verified",
  "label": "Contract source verified",
  "value": null,
  "state": "unknown",
  "reason": "The explorer has no source for this address.",
  "source_url": "https://robinhoodchain.blockscout.com/address/0x...",
  "created_at": "2026-07-29T09:40:20Z"
}

source_url is what makes a finding checkable independently. It is always present when the source has an addressable page — a claim you cannot verify is worth very little.