---
title: "Explanation, audit and provenance"
summary: "What the explanation, audit, provenance and degraded fields of a result mean, how to use them for an audit trail, and when to switch the explanation off."
category: "developer"
tags: ["explanation", "audit", "provenance", "degraded", "hashes", "reproducibility"]
updated: "2026-09-14T04:25:02.329Z"
url: "https://support.quorumtech.ch/articles/api-explanation-and-audit"
markdown: "https://support.quorumtech.ch/articles/api-explanation-and-audit.md"
---

# Explanation, audit and provenance

A verdict alone is a decision. The rest of the result is the reasoning, the check on that reasoning, and the record that lets someone reproduce it later.

## Explanation

For a claim checked against inline evidence, three rubric axes mark propositions about the claim, each with its reasoning and the spans it relied on:

```json
{
  "explanation": {
    "axes": {
      "entailment": {
        "covers_every_assertion": {
          "reasoning": "Only the revenue assertion is supported; the operating margin improvement lacks evidence.",
          "holds": "false",
          "spans": ["ev_1:0"]
        }
      }
    },
    "citedSpans": ["ev_1:0"],
    "availableSpans": 2,
    "axesRun": ["entailment", "contradiction", "scope"],
    "axesExpected": ["entailment", "contradiction", "scope"]
  }
}
```

`holds` is `"true"`, `"false"` or `"unclear"`. The explanation does not decide the verdict. It is produced independently and can disagree with it.

For a claim checked against a batch, the explanation is different in shape: `reasoning`, the list of `unverifiedAssertions` (the actionable output), `searchedThoroughly`, and a `trace` of what was searched and read, in order, with the number of `steps` taken.

## Audit

```json
{
  "audit": {
    "referentialIntegrity": 1,
    "explanationTrust": 1,
    "findings": [],
    "explanationDisagrees": false
  }
}
```

- `referentialIntegrity` is the share of cited spans that resolve to text you sent, from 0 to 1. A citation the model invented was removed and lowers this.
- `explanationTrust` is that figure less mechanical coherence penalties.
- `findings` names problems, for example `fabricated_span_reference`.
- `explanationDisagrees: true` means the explanation read the evidence differently from the verdict. It is not an error. It flags a borderline case and is surfaced rather than reconciled away. In practice it fires on `DISPUTED` cases, where the contradiction axis sees a refutation while the verdict declines to pick a side.

## Provenance

```json
{
  "provenance": {
    "measurementHash": "3f9c...",
    "policyHash": "a41b...",
    "rulesApplied": ["precedence", "adjacent-not-partial"],
    "promptVersion": "attest-routed-v1+precedence+adjacent-not-partial",
    "scoringVersion": "attest-scoring-v1",
    "serviceVersion": "attest-service-v0.1",
    "model": "openai/gpt-oss-120b",
    "createdAt": "2026-09-06T14:02:11.318Z",
    "mode": "evidence"
  }
}
```

- `measurementHash` identifies the inputs: the canonical claim, the evidence and the measurements. `policyHash` identifies the scoring configuration. They are separate so that changing a threshold does not invalidate a measurement no model call would produce differently.
- `rulesApplied` lists the reading rules chosen for this request. The set is part of `promptVersion`, so two responses with the same version were produced by the same instructions.
- `mode` is `evidence` or `batch-agent`.

A verdict is reproducible from the document you still hold plus these hashes and versions. It is not retrievable from Quorum, because Quorum does not keep it. See Privacy.

## Degraded

```json
{ "degraded": ["explanation_incomplete: 2/3 axes"] }
```

Non-fatal problems, so you always learn when an answer was produced with reduced measurement. An empty array means nothing was compromised.

## Switching the explanation off

`config.explain: false` skips the explanation pass. You get the verdict at a fraction of the latency, but `explanation` and `audit` come back `null` and the span lists are empty, so there is no audit trail and no citations. It costs the same credits as an explained check, on purpose, so nobody is nudged away from the audit trail. Reach for it when you are triaging volume, not when the answer matters.

## Keeping an audit trail

Store, per claim you checked: the claim, the evidence ids and their `fileHash` or content, the verdict, the span ids, and the whole `provenance` block. That is enough to answer "was this verdict produced against the document I signed off" by hashing the file you still hold, and to replay the check against the same versions.