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

# Audit Lineage

> How audit records connect to form a complete, reproducible decision chain

## The lineage chain

Every authority verification outcome creates a connected set of records linked by `execution_id` and `execution_fingerprint`:

```
execution_id                        execution_fingerprint
"claim-CLM-2024-00443"              "a3f8d2c1e4b5f6a7..."
        │                                   │
        ▼                                   ▼
audit_decisions ──────────────────── audit_decisions
(execution record)                  (semantic identity)
        │                                   │
        ▼                                   ▼
audit_overrides ──────────────────── audit_overrides
(override record)                   (override context)
        │                                   │
        ▼                                   ▼
audit_verifications ─────────────── audit_verifications
(verification record)               (verified this fingerprint)
```

**`execution_id`** — the business transaction identifier you provided. Links records to your business event.

**`execution_fingerprint`** — the semantic hash of the decision inputs. Links records to the specific combination of policy + signals that was evaluated.

***

## Reconstructing the full lineage of a decision

```typescript theme={null}
// 1. Get the core decision record
const decision = await client.audit.decision("claim-CLM-2024-00443");

console.log("Decision:");
console.log(`  action:       ${decision.decision}`);
console.log(`  state:        ${decision.execution_state}`);
console.log(`  policy:       ${decision.policy_id} v${decision.policy_version}`);
console.log(`  fingerprint:  ${decision.execution_fingerprint}`);
console.log(`  executed_at:  ${decision.executed_at}`);
console.log(`  verified:     ${decision.verification_valid}`);

// 2. The full attestation is embedded in the record
const attestation = decision.attestation;
console.log("\nAttestation signature:", attestation?.signature?.slice(0, 20) + "...");

// 3. Verify the attestation independently
if (attestation) {
  const verification = await client.verify(attestation);
  console.log("\nVerification:", verification.valid ? "VALID" : "FAILED");
  console.log("  checks:", verification.checks);
}
```

***

## Lineage for override decisions

When an execution was overridden, the lineage includes the override record. Query via SQL:

```sql theme={null}
SELECT
  d.execution_id,
  d.execution_fingerprint,
  d.decision           AS original_decision,
  d.execution_state,
  d.executed_at,
  o.approved_by,
  o.approver_role,
  o.resolution_status,
  o.reason             AS override_reason,
  o.resolved_at
FROM audit_decisions d
LEFT JOIN audit_overrides o
  ON d.execution_id = o.execution_id
WHERE d.execution_id = 'claim-CLM-2024-00443';
```

***

## Providing lineage to auditors

An auditor who wants to verify a decision needs the following chain:

1. **Attestation** — from `audit_decisions.attestation` (the signed JSON)
2. **Public key** — `trust/root.pub` — to verify the signature
3. **Override record** (if applicable) — `approved_by`, `approver_role`, `reason`, `override_signature` from `audit_overrides`
4. **Policy bundle** (optional) — the compiled bundle at `policies/{policyId}/{policyVersion}/`, identified by `bundleHash` in the attestation

With these four artifacts, the auditor can:

* Verify the attestation signature (proves the decision was made by the governed runtime)
* Verify the policy bundle (proves the exact rules that applied)
* Read the override record (proves who authorized the override and why)
* Reproduce the decision by evaluating the same signals against the same policy

***

## Export for compliance

```typescript theme={null}
// Export all decisions for a compliance audit period
const decisions = await client.audit.decisions({
  from: "2024-01-01T00:00:00Z",
  to: "2024-03-31T23:59:59Z",
  limit: 10000,
});

// Export the full detail (including attestation) for each
const fullRecords = await Promise.all(
  decisions.map(d => client.audit.decision(d.execution_id))
);

// Write to file for auditor
const { writeFile } = await import("node:fs/promises");
await writeFile(
  "audit-export-q1-2024.json",
  JSON.stringify(fullRecords, null, 2)
);
```

***

## Troubleshooting

**Decision record exists but attestation field is empty** — The execution was recorded before the full attestation was available, or the record was written in an older format. Check the `signature` column directly — if it is non-null, the record is complete.

**Cannot find decision by `execution_id`** — Verify the exact ID including any prefixes (`claim-`, `payment-`, etc.). IDs are case-sensitive.

**`verified_at` is null for old records** — Verification was not run at execution time. Run a backfill verification job against historical records if required for compliance.