CONCEPTS

Evidence & provenance

A claim is only as defensible as the evidence behind it. The sources array — and the provenance metadata attached to each source — is what turns an assertion that an action was safe into a record you can stand behind under scrutiny.

When you submit a claim to POST /v1/evaluate, the sources array is the substance the policy reasons over. Everything else in the request — the action metadata, the policy configuration — describes what happened and how it should be judged. The sources are the proof. Each entry is a discrete piece of evidence with a type, a confidence score, a pointer to where it lives, and optional metadata describing how it was collected. The receipt records the count and the set of types it saw, and the policy decides whether that evidence is sufficient.

What an evidence source is

Each element of sources is an object. At minimum it carries an identifier, a type, a URI, a confidence score, and a human-readable description. Two optional objects — admissibility and provenance — let a source carry its own override and its own chain of custody.

The type field is a closed enum. Every source declares exactly which kind of signal it represents:

github ci agent_trace code_review test_result policy_check human_approval model_output runtime_log infrastructure manual

At least one source is required. In practice a defensible claim carries several, drawn from different types — a passing test suite, a human review, a runtime log — so that no single failure of collection can hollow out the record.

Why typed evidence matters

Counting sources is not enough. Ten copies of the same CI run are ten sources, but they are one signal: if that pipeline is misconfigured or compromised, all ten are wrong together. Typed evidence is how the policy refuses to be fooled by volume.

The policy configuration exposes both knobs independently. minSources sets a floor on the raw count. minSourceTypes sets a floor on the number of distinct type values present. A policy that requires minSourceTypes: 3 cannot be satisfied by any quantity of a single type — the claim must be corroborated by at least three different kinds of signal before it can be ALLOWED. The receipt's evidence block records exactly what was seen, both the source_count and the deduplicated source_types array, so the basis for the verdict is auditable after the fact.

Confidence scoring

Every source carries a confidence score between 0.0 and 1.0 — a calibrated statement of how much weight that piece of evidence deserves. A green test run might warrant 0.9; a terse review comment, 0.6. The score is yours to assign; the policy's job is to hold the aggregate to a standard.

The minConfidence policy field sets a floor on the average confidence across all sources. Because it averages, a single low-confidence source does not sink a claim on its own, and a single high-confidence source cannot carry weak corroboration past the bar. The mean has to clear the threshold. This pairs naturally with the type requirements: minSourceTypes ensures breadth, minConfidence ensures the evidence is, on balance, strong enough to act on.

Provenance & chain of custody

Knowing what the evidence says is one thing. Knowing where it came from is the difference between a decision you can stand behind and one you can only stand near. The optional provenance object records the custody of a source: when it was captured, the immutable snapshot it was captured from, what collected it, and the hand-off path it traveled.

The requireProvenance policy field enforces it. When set to true, every source in the claim must carry a provenance object — a claim with bare, unsourced evidence cannot be ALLOWED under that policy. This is how a receipt earns the right to be replayed and verified months later: the trail back to the originating snapshot is recorded, not assumed.

ONE SOURCE OBJECT WITH PROVENANCE

{
  "id": "evd_ci_42",
  "type": "ci",
  "uri": "https://github.com/acme-corp/widget-api/actions/runs/123",
  "confidence": 0.9,
  "content": "All 47 tests passing, 0 failures",
  "provenance": {
    "captured_at": "2026-05-30T10:00:00Z",
    "snapshot_id": "snap_ci_42",
    "collector": "github-actions",
    "chain_of_custody": ["github", "decrec-client"]
  }
}

Read this object as a sworn statement. The content asserts the facts; confidence rates them; uri lets a reader go look; and provenance establishes that the assertion came from a named snapshot, through a known collector, along a recorded path. Each source object becomes part of the claim, and the resulting receipt is signed and hash-chained — so the evidence behind a decision cannot be quietly revised after the verdict is rendered.