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

# Override Audit Lineage

> How override decisions are recorded and linked to the original execution

## The audit chain

Every override produces three linked records:

```
audit_decisions
  └─ execution_id: "claim-CLM-2024-00443"
     execution_state: "pending_override"
     execution_fingerprint: "a3f8..."

audit_overrides
  └─ execution_id: "claim-CLM-2024-00443"
     execution_fingerprint: "a3f8..."
     approved_by: "adjuster-sarah-chen"
     approver_role: "senior_adjuster"
     reason: "Verified documentation..."
     resolution_status: "approved"
     override_signature: "ed25519sig..."

audit_verifications (after resolution execution)
  └─ execution_fingerprint: "a3f8..."
     valid: true
     signature_verified: "verified"
```

The `execution_fingerprint` is the link across all three records. It uniquely identifies the semantic execution (the combination of policy + signals that was evaluated).

***

## Querying the audit chain

### Check if an execution was overridden

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

console.log(record.execution_state);    // "completed" (after override resolved)
console.log(record.decision);           // "manual_review" (the original decision)
console.log(record.verification_valid); // true
```

<Note>
  After an override is approved and the resolution execution completes, the `execution_state` in the audit record updates to `"completed"`. The original decision (`"manual_review"`) remains — it is the decision that was authorized by the policy.
</Note>

***

### List all decisions that required override

```typescript theme={null}
const decisions = await client.audit.decisions({ limit: 500 });

const overrideRequired = decisions.filter(
  d => d.execution_state === "pending_override"
);

const overrideCompleted = decisions.filter(
  d => d.execution_state === "completed" && d.decision === "manual_review"
);
```

***

## What the override audit record contains

The `audit_overrides` table stores:

| Column                         | Description                                               |
| ------------------------------ | --------------------------------------------------------- |
| `execution_id`                 | The `executionId` from the original execute request       |
| `execution_fingerprint`        | The semantic hash of the execution                        |
| `policy_id` / `policy_version` | Policy that governed the original decision                |
| `schema_version`               | Policy schema version                                     |
| `decision`                     | The original decision JSON                                |
| `approved_by`                  | Who approved or rejected the override                     |
| `resolution_status`            | `"pending"` → `"approved"` or `"rejected"`                |
| `override_signature`           | Ed25519 signature of the override authorization           |
| `signature_type`               | Signing algorithm used                                    |
| `pending_context`              | Stored execution context (used to re-execute on approval) |
| `created_at`                   | When the override request was created                     |
| `resolved_at`                  | When the override was resolved                            |

***

## Querying override lineage via SQL

```sql theme={null}
-- Full override lineage for a decision
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';
```

***

## Constructing an override proof for an auditor

An auditor who wants to verify that an override was properly authorized needs:

1. The original attestation (from `audit_decisions.attestation`)
2. The override record (`approved_by`, `approver_role`, `reason`, `override_signature`)
3. The resolution execution signature (`audit_overrides.resolution_status` + the `overrideId`)

Provide all three to demonstrate:

* The original authority verification outcome was produced by the policy engine
* A named, credentialed human authorized the override
* The override authorization is cryptographically signed

```typescript theme={null}
// Export override proof
const decision = await client.audit.decision("claim-CLM-2024-00443");

const proof = {
  attestation: decision.attestation,
  executedAt: decision.executed_at,
  policyId: decision.policy_id,
  policyVersion: decision.policy_version,
  originalDecision: decision.decision,
  // Override details retrieved directly from audit_overrides (database query)
};
```

***

## Troubleshooting

**Override record exists but no resolution execution** — The override was recorded but the re-execution failed. Check server logs for `[SYS-024]` or other errors. Check the `audit_verifications` table for a verification record matching the `execution_fingerprint`.

**`audit_db: false` in /health** — Override records cannot be stored without Postgres. All override lineage is lost if Postgres is not connected when the override occurs.

**Multiple override attempts for the same execution** — The server returns 409 on the second attempt. Only one override resolution is allowed per `executionId`. The first resolution (approved or rejected) is final.