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

# Decision Provenance

> Every decision carries its lineage — what was decided, why, on which inputs, and who authored, published, and deployed the rules behind it.

## What is Decision Provenance?

Every execution LexQ records is sealed with its provenance at write time: the decision outcome, a deterministic per-rule reason, the input facts it saw, the fingerprint of the exact rule snapshot that ran, and a three-layer responsibility chain — who authored the version, who published it, who deployed it. Nothing is reconstructed after the fact; what you read is what was sealed when the decision happened.

<Info>
  **Execution History vs Provenance** — Execution History tells you *what happened* across executions: lists, statistics, latencies. Decision Provenance answers, for one decision: *why did it come out this way, on which inputs, under whose rules?*
</Info>

## When to Use

* **Audit response** — an auditor asks why customer X received decision Y on date Z. Pull the trace and hand over the sealed lineage.
* **Customer dispute** — see exactly which rule fired on which (masked) inputs, then verify the fix with [Decision Replay](/guides/decision-replay).
* **Monthly access-log inspection** — the reveal audit ledger records who saw which PII and when, collectable by API for your SIEM.

## Getting a Decision's Lineage

### Console

Open **Decision Provenance** from an execution's detail in Execution History — the lineage view shows the decision, per-rule reasons, masked inputs, and the responsibility chain.

### CLI

```bash theme={null}
lexq provenance get --trace-id <traceId>
```

### API

```bash theme={null}
curl "https://api.lexq.io/api/v1/partners/provenance/<traceId>" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response

Abridged — PII facts arrive masked, and `maskedKeys` names them:

```json theme={null}
{
  "result": "SUCCESS",
  "data": {
    "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
    "requestFacts": {
      "customer_segment": "••••••",
      "purchase_subtotal_usd": 129.9
    },
    "maskedKeys": ["customer_segment"],
    "lineage": {
      "authored":  { "name": "Jane Kim", "at": "2026-06-28T09:14:02Z" },
      "published": { "name": "Jane Kim", "at": "2026-06-30T11:40:55Z" },
      "deployed":  { "name": "Jane Kim", "at": "2026-07-01T08:02:19Z" }
    }
  }
}
```

Alongside these, the payload carries the decision outcome, the deterministic reason for every rule that was evaluated, and the rule snapshot fingerprint — enough to reproduce the decision's context without touching the live system.

## PII Masking and Reveal

Facts marked as PII in [Fact Definitions](/guides/fact-definitions) are masked as `••••••` on **every read surface** — provenance, execution history detail, and any export. `maskedKeys` always tells you what was masked, so the shape of a decision stays fully analyzable without exposing the values.

Revealing a masked value is a separate, deliberate act:

* **Console-only**, for Admin and User roles. API keys are rejected with `403` — an agent or integration can never pull PII plaintext.
* **Write-then-reveal** — the audit row is committed *before* the value is shown. A reveal that is not audited cannot happen.
* Revealing a fact that is not marked as PII fails with `AN-027`.

<Warning>
  The reveal surface is intentionally absent from the CLI and the MCP tools. Routing plaintext PII into an agent's context would copy it beyond the console's audited boundary.
</Warning>

## The Reveal Audit Ledger

Every reveal lands in an append-only ledger: who revealed which fact of which trace, and when. Values are never stored — the ledger is metadata only.

### Console

Open **PII Reveal Audits** in the sidebar and filter by trace, operator, fact key, or period.

### CLI

```bash theme={null}
lexq provenance reveal-audits --start-date 2026-07-01 --format table
```

### API

```bash theme={null}
curl "https://api.lexq.io/api/v1/partners/provenance/reveal-audits?startDate=2026-07-01&factKey=customer" \
  -H "x-api-key: YOUR_API_KEY"
```

| Filter                  | Match                               |
| ----------------------- | ----------------------------------- |
| `traceId`, `revealedBy` | Exact                               |
| `factKey`               | Partial, case-insensitive           |
| `startDate`, `endDate`  | Date range in the tenant's timezone |

### Response

```json theme={null}
{
  "result": "SUCCESS",
  "data": {
    "content": [
      {
        "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
        "factKey": "customer_segment",
        "revealedBy": "6a2f31c0-9b7d-4e2a-8c11-3d5e9f0a1b2c",
        "revealedByName": "Jane Kim",
        "revealedAt": "2026-07-06T14:23:11Z"
      }
    ],
    "totalElements": 7
  }
}
```

Viewer and API-client roles can query the ledger even though they cannot reveal — oversight is broader than the act. That asymmetry is what makes automation possible: point your SIEM at this endpoint with an API key and schedule the periodic access-log inspection that many privacy regulations require, instead of doing it by hand.

<Warning>
  Lineage stays resolvable because audit retention refuses to delete what it references: a version with recorded executions cannot be removed (`AN-028`), and if an audit record cannot be sealed, the operation itself is rejected (`AN-029`) — fail closed, never fail silent.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Decision Replay" icon="rotate-left" href="/guides/decision-replay">
    Re-evaluate a past decision against a candidate version and diff the outcome.
  </Card>

  <Card title="Fact Definitions" icon="database" href="/guides/fact-definitions">
    Mark facts as PII to enable masking and audited reveal.
  </Card>
</CardGroup>