# Veritas Integrity & Zero-Copy Auditing

Coreason V2 incorporates the **Veritas** integrity subsystem to support high-compliance environments (GxP, Finance, Defense). This system addresses two critical challenges in modern AI auditing: **Cost** and **Trust**.

## The Problem

### 1. Cost & Privacy (The "Data Gravity" Problem)
In high-throughput systems, logging every single input and output payload to a central audit log is prohibitively expensive and risky.
*   **Cost:** Storing terabytes of JSON payloads.
*   **Privacy:** Aggregating PII/PHI in a single "honeypot" database.

### 2. Trust (The "Black Box" Problem)
For regulated industries, a simple text log is insufficient. We need **Non-Repudiation**: proof that the AI output was generated by a specific model, at a specific time, and has not been tampered with since.

## The Solution: Veritas Schema

The `IntegrityConfig` schema (nested within `ComplianceConfig`) enables granular control over these behaviors.

```python
class IntegrityConfig(CoReasonBaseModel):
    input_mode: AuditContentMode
    output_mode: AuditContentMode
    integrity_level: IntegrityLevel
    hash_algorithm: str
```

### Zero-Copy Auditing (`reference_only`)

Instead of copying the payload into the audit log, the system computes a cryptographic hash (e.g., SHA-256) of the data and stores **only the hash and a pointer** (URI) to the original storage location (e.g., S3, Azure Blob, or a secure enclave).

*   **Benefit:** The audit log remains lightweight and contains no sensitive data.
*   **Verification:** The auditor can later retrieve the data from the source and verify it matches the stored hash.

### Cryptographic Anchoring (`anchor`)

For the highest level of trust, execution traces can be "anchored" to an immutable ledger (e.g., a private blockchain or a Merkle Tree). This provides mathematical proof of:
1.  **Existence:** The event happened at time T.
2.  **Integrity:** The data has not been altered.
3.  **Sequence:** The chain of custody is unbroken.

## Configuration Guide

### Modes (`AuditContentMode`)

| Mode | Behavior | Best For |
| :--- | :--- | :--- |
| `FULL_PAYLOAD` | Default behavior. Copies entire JSON body. | Debugging, Low Volume. |
| `REDACTED` | Runs PII scrubbers *before* storage. | GDPR/CCPA Compliance. |
| `REFERENCE_ONLY` | **Zero-Copy.** Stores `sha256:abcd...` and `s3://...`. | High Volume, HIPAA, Defense. |
| `OFF` | Stores metadata only (timestamp, user_id). | Ephemeral interactions. |

### Integrity Levels (`IntegrityLevel`)

| Level | Behavior | Best For |
| :--- | :--- | :--- |
| `NONE` | Standard database logging. | Internal tools. |
| `CHECKSUM` | Adds a `hash` field to every event. | Data integrity checks. |
| `DIGITAL_SIGNATURE` | Signs the hash with the worker's private key. | Non-repudiation. |
| `BLOCKCHAIN_ANCHOR` | Submits the hash to an immutable ledger. | GxP, Clinical Trials. |

## Example: High-Throughput Financial Analysis

In this scenario, we process millions of documents. Storing them in the audit log is impossible. We use **Reference Only** for data, but require **Digital Signatures** to prove authenticity.

```python
from coreason_manifest.spec.v2.compliance import (
    ComplianceConfig,
    IntegrityConfig,
    AuditContentMode,
    IntegrityLevel
)

recipe.compliance = ComplianceConfig(
    audit_level="gxp",
    integrity=IntegrityConfig(
        input_mode=AuditContentMode.REFERENCE_ONLY,  # Don't copy the 10MB PDF
        output_mode=AuditContentMode.FULL_PAYLOAD,   # Do copy the small summary
        integrity_level=IntegrityLevel.DIGITAL_SIGNATURE # Sign the result
    )
)
```
