CONCEPTS

Policy, verdicts & escalation

Every claim submitted to the Decision Receipt API is measured against an explicit, declared policy. The evaluation returns a verdict — allowed, blocked, or escalated — together with the per-rule reasoning that produced it. This page explains how a claim is judged and what each outcome means for the system acting on it.

The policy that judges a claim

A policy is a set of thresholds the evidence must clear. You supply one per claim through the optional policyConfig object on POST /v1/evaluate; if you omit it, the API applies its default policy. Each field is an independent check, and a claim is measured against all of them together.

Field	Type	What it requires
`minSources`	integer	Minimum number of evidence sources attached to the claim.
`minSourceTypes`	integer	Minimum number of distinct source types — a CI run and a code review count as two; two CI runs count as one.
`minConfidence`	number	Minimum average confidence across the sources (0.0–1.0).
`requireProvenance`	boolean	Whether every source must carry chain-of-custody provenance.
`requireReplay`	boolean	Whether the evaluation must replay deterministically to pass.
`requireHumanApproval`	boolean	Whether a `human_approval` source type must be present.
`maxRiskScope`	integer	Maximum allowed size of the action's risk scope.

The policy is part of the evaluation, not a side note. Because it travels with the claim and is reflected in the receipt, anyone reviewing the decision later can see the exact standard it was held to.

How the result is reported

The evaluation response carries a policy object. It holds the overall verdict, a human-readable reason, and a rules array — one entry per check, each with the rule name, whether it passed, and a short reason explaining the outcome. The per-rule detail is what makes a verdict auditable rather than opaque: you can see not only that a claim failed, but which threshold it failed and by how much.

POLICY RESULT

"policy": {
  "verdict": "BLOCKED",
  "reason": "One or more required checks failed",
  "rules": [
    { "rule": "min_sources",      "passed": true,  "reason": "2 sources >= 2 required" },
    { "rule": "min_source_types", "passed": false, "reason": "1 type < 2 required" },
    { "rule": "min_confidence",   "passed": true,  "reason": "avg 0.88 >= 0.60 required" },
    { "rule": "require_replay",   "passed": true,  "reason": "replay deterministic" }
  ]
}

Here the claim carried enough sources and high enough confidence, but every source was of a single type, so the distinct-type check failed and the overall verdict is BLOCKED. The rule that failed is named explicitly, so the caller knows precisely what to remedy.

The three verdicts and what to do

A verdict is a decision the caller is expected to act on. There are exactly three, and each implies a different next step.

ALLOWED — every check passed. The evidence met or exceeded the policy and the evaluation was clean. The intended caller behavior is to proceed with the action and keep the signed receipt as the record of why it was permitted.
BLOCKED — a hard check failed. The evidence did not meet the policy — too few sources, confidence below the floor, missing provenance, or a non-deterministic replay where one was required. The intended caller behavior is to stop: do not take the action. The receipt records the failure so the decision to hold is itself documented.
ESCALATED — the claim needs human review before it can proceed. This is the outcome when a policy requires a person in the loop, most directly through requireHumanApproval. The action is neither approved nor refused by the policy alone; the intended caller behavior is to route the claim to a human and let that reviewer make the call.

Note

Escalation is not a failure state. It is the policy declaring that this class of action is too consequential to settle automatically — the system is choosing to ask rather than to guess.

Verdict, admissibility, and replay

The policy verdict and the receipt's admissibility.status describe two related but distinct things. The verdict answers did the evidence satisfy the policy? The admissibility status answers can this whole evaluation — evidence, policy, and replay together — be trusted as a record?

A receipt is marked ACCEPTED when the evaluation is sound end to end: the policy passed and the result replays deterministically. It is marked REJECTED when the evidence or policy fails outright. The third status, NON_DETERMINISTIC, arises specifically when replay does not reproduce the original result — the same inputs evaluated again did not yield the same outcome, so the judgment cannot be defended as reproducible regardless of how the policy rules scored. A decision that cannot be replayed cannot be relied upon, and the receipt says so plainly rather than hiding it.

Dry runs and custom policies

You do not have to persist a receipt to find out how a claim would be judged. POST /v1/simulate runs the same policy evaluation as a dry run and returns the verdict and per-rule detail without writing anything to the ledger — useful for tuning a policy or previewing whether a claim would pass before you commit to evaluating it.

The default policy suits many actions, but consequential ones often warrant stricter standards. You can register a reusable policy of your own with POST /v1/policies and apply it by reference. For the mechanics of defining, storing, and applying policies, see the policies guide.

← PreviousEvidence & provenance Next →Replay & determinism