CONCEPTS

Anatomy of a claim

A claim is the structured input to an admissibility evaluation: a statement of the action taken, the evidence it rested on, who was entitled to take it, and how sure the result should be. Submitting a claim to POST /v1/evaluate is what produces a Decision Receipt in response.

Where a receipt is the signed record of what was decided, a claim is the honest statement of what is being asserted. The two are counterparts: the claim is the input contract, the receipt is the output. A claim does not argue that an action was good; it lays out, in a fixed shape, the facts on which a verdict can be reached. The evaluator reads those facts, applies a policy, checks replay determinism, and returns a receipt that anyone can independently verify.

Only four parts are required — claim_id, entity, claim, and sources. Everything else is optional and serves to enrich the record: the more precisely you describe the action, the rights behind it, and the determinism you expect, the more the resulting receipt can say.

Identity and subject

Three required fields establish what this claim is and what it is about.

• claim_id — the stable identity of this decision. A unique string you choose. It ties the claim, the resulting verdict, and the receipt together, and lets you correlate the same decision across systems.
• entity — what is being evaluated: the thing the action touches, typically a repository name or other system identifier.
• claim — the human-readable description of the action, in plain language. This is the sentence a reviewer would read first, e.g. "PR #42: Add rate limiting to /api/orders".

Together these answer "which decision, about what, in words." They are the minimum needed to name a claim unambiguously.

The action

The optional action object describes the concrete operation in structured form, so the receipt's subject is machine-readable rather than only prose. Two fields are required within the object once you include it:

• action_type — an enum naming the kind of operation: code_change, infra_change, access_change, deployment, merge, policy_exception, or agent_execution.
• target_system — the system being acted on, e.g. github.

The remaining fields locate and characterize the action: repository, pull_request, commit, branch, and environment pin it to an exact place; risk_scope and affected_controls declare what it touches; and agent, agent_model, and human_operator name who performed it — the agent, the model behind it, and the human accountable for it.

Evidence and rights

The required sources array is the heart of a claim — the evidence the action rested on. Each source is typed and provenanced, so the record carries not just an assertion but where the assertion came from. A source declares an id, a type (one of github, ci, agent_trace, code_review, test_result, policy_check, human_approval, model_output, runtime_log, infrastructure, or manual), a uri pointing to it, a confidence score from 0.0 to 1.0, and a content description. Optional provenance records the chain of custody — when it was captured, by which collector, and through which hands. See Evidence and provenance for how this array is structured and why typing and provenance matter.

The optional decision_rights array asserts who was entitled to take the action — principal, role, and permission claims that say the actor had standing, not merely capability. See Decision rights.

Expectations and policy

Two optional parts say how the claim should be judged. expected_replay_match declares whether re-evaluating the claim should reproduce the same result — your stated expectation of determinism, which the receipt's replay result is checked against. policyConfig supplies the per-request policy: thresholds such as minSources, minSourceTypes, minConfidence, requireProvenance, requireReplay, requireHumanApproval, and maxRiskScope. Omit it to evaluate against the default policy. See Policy and verdicts for how these settings shape the verdict.

CLAIMINPUT (ABRIDGED)

{
  "claim_id": "my-unique-claim-001",
  "entity": "acme-corp/widget-api",
  "claim": "PR #42: Add rate limiting to /api/orders",
  "expected_replay_match": true,
  "action": {
    "action_type": "merge",
    "target_system": "github",
    "repository": "acme-corp/widget-api",
    "pull_request": 42,
    "agent": "claude-code",
    "human_operator": "jdoe"
  },
  "sources": [
    {
      "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",
        "collector": "github-actions",
        "chain_of_custody": ["github", "decrec-client"]
      }
    },
    {
      "id": "evd_review_42",
      "type": "code_review",
      "uri": "https://github.com/acme-corp/widget-api/pull/42",
      "confidence": 0.85,
      "content": "Approved by senior engineer with no blocking comments"
    }
  ],
  "policyConfig": {
    "minSources": 2,
    "minSourceTypes": 2,
    "minConfidence": 0.6
  }
}

Read end to end, a well-formed claim says: here is the action, here is everything it rested on, here is who was entitled to take it, and here is how sure we expect to be. The receipt is what comes back when that statement is evaluated.