> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clevis.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Provenance

> The record object: rule fingerprint, engine version, and content digest

Every calculation carries a `record` object describing **what produced it**. It is present
both on creation and on retrieval, so the two bodies are the same document.

```json theme={null}
{
  "id": "01HX9B2KM3V4W5X6Y7Z8A9B0CD",
  "record": {
    "stored": true,
    "rule_fingerprint": "sha256:b90834cebdc4224c3...",
    "engine_version": "9f2c1ab",
    "schema_version": 1,
    "content_digest": "sha256:41d0ae9f77b2c518...",
    "batch_id": null,
    "supersedes_id": null,
    "metadata": { "run": "nomina-2026-09-q1" }
  }
}
```

| Field              | What it is                                                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `stored`           | Always `true`. A calculation that could not be stored is not returned at all                                     |
| `rule_fingerprint` | SHA-256 of the rule file that produced these amounts                                                             |
| `engine_version`   | Build of the calculation engine, as a git SHA                                                                    |
| `schema_version`   | Shape of this stored response. An old record is returned in the shape it was written in, never upgraded in place |
| `content_digest`   | SHA-256 over the canonical form of this response                                                                 |
| `batch_id`         | The batch this row belonged to, if any                                                                           |
| `supersedes_id`    | The calculation this one replaces, if it is a [correction](/calculations/corrections)                            |
| `metadata`         | Your own labels, echoed back                                                                                     |

## Why a fingerprint and not a version label

A version label is written by one person and forgotten by the next.

Under the single label `version: "2026.1"`, **four different contents** of
`rules/MX/2026/ordinario.yml` have shipped — and five for Colombia, seven for Chile, five
for Argentina. At least two of those changes moved amounts. A label that four different
rule sets have shared is not an identity.

The fingerprint is the SHA-256 of the rule file itself, so two calculations carrying the
same fingerprint ran against byte-identical rules. That is a claim you can check.

## Verifying a calculation later

Keep the `content_digest` you received. Fetch the calculation any time afterwards and
compare: if the digests match, what you are being handed now is what you were handed then.

<CodeGroup>
  ```python Python theme={null}
  import httpx

  original_digest = "sha256:41d0ae9f77b2c518..."  # kept from the original response

  fetched = httpx.get(
      "https://api.clevis.dev/v1/payroll/calculations/01HX9B2KM3V4W5X6Y7Z8A9B0CD",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  ).json()

  assert fetched["record"]["content_digest"] == original_digest
  ```

  ```javascript Node.js theme={null}
  const originalDigest = "sha256:41d0ae9f77b2c518..."; // kept from the original response

  const fetched = await fetch(
    "https://api.clevis.dev/v1/payroll/calculations/01HX9B2KM3V4W5X6Y7Z8A9B0CD",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } },
  ).then((r) => r.json());

  console.assert(fetched.record.content_digest === originalDigest);
  ```
</CodeGroup>

## Labelling calculations with metadata

`options.metadata` accepts up to **20 keys**, values up to 500 characters. Use it for a
payroll run id, a cost centre, a `"test"` marker — anything you will want to filter or
recognise later. It is echoed back in `record.metadata`.

```json theme={null}
{
  "country": "CO",
  "scheme": "ordinario",
  "year": 2026,
  "options": {
    "metadata": {
      "run": "nomina-2026-09-q1",
      "cost_center": "ops-bogota"
    }
  }
}
```

<Warning>
  **Never put personal data in `metadata`.** It is stored verbatim.
</Warning>

## What provenance does not give you

<Warning>
  Provenance lets you prove **which rules ran**. It does not let you **re-run them**.
</Warning>