Decision Provenance

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.

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?

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.
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

lexq provenance get --trace-id <traceId>

API

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:

{
  "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 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.

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.

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

lexq provenance reveal-audits --start-date 2026-07-01 --format table

API

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

{
  "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.

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.

Getting Started

Core Concepts

Features

Decision Provenance

What is Decision Provenance?

When to Use

Getting a Decision’s Lineage

Console

CLI

API

Response

PII Masking and Reveal

The Reveal Audit Ledger

Console

CLI

API

Response

Next Steps

Decision Replay

Fact Definitions

​What is Decision Provenance?

​When to Use

​Getting a Decision’s Lineage

​Console

​CLI

​API

​Response

​PII Masking and Reveal

​The Reveal Audit Ledger

​Console

​CLI

​API

​Response

​Next Steps

Decision Replay

Fact Definitions

What is Decision Provenance?

When to Use

Getting a Decision’s Lineage

Console

CLI

API

Response

PII Masking and Reveal

The Reveal Audit Ledger

Console

CLI

API

Response

Next Steps