# Provenance Pipeline QuickStart

Prove which data in your AI agent's output was never touched by the model — in 5 minutes.

## 1. Install

```bash
cargo install --git https://github.com/coproduct-opensource/nucleus nucleus-claude-hook
cargo install --git https://github.com/coproduct-opensource/nucleus nucleus-audit
nucleus-claude-hook --setup
```

## 2. Create a Provenance Schema

Save as `.provenance.json` in your project root:

```json
{
  "schema_version": 1,
  "description": "Stock quote extraction demo",
  "sources": {
    "quote_api": {
      "url_template": "https://api.example.com/quote?symbol={ticker}",
      "content_type": "application/json",
      "max_staleness_secs": 300
    }
  },
  "fields": {
    "price": {
      "source": "quote_api",
      "derivation": "deterministic",
      "parser": "jq",
      "expression": ".price"
    },
    "volume": {
      "source": "quote_api",
      "derivation": "deterministic",
      "parser": "jq",
      "expression": ".volume"
    },
    "analysis": {
      "source": "quote_api",
      "derivation": "ai_derived"
    }
  }
}
```

**Key concept**: Fields marked `deterministic` MUST come from the parser pipeline — the model cannot write them directly. Fields marked `ai_derived` are generated by the model and honestly labeled.

## 3. Run

```bash
claude -p "populate .provenance.json for ticker AAPL"
```

The model will:
1. Read the schema and enter provenance mode
2. Fetch the source URL (content hash captured automatically)
3. Parser pipeline extracts `price` and `volume` (model excluded)
4. Model writes `analysis` (honestly labeled as AI-derived)
5. On session end, `provenance-output.json` is written automatically

## 4. Verify

```bash
nucleus-audit verify-provenance \
  --output provenance-output.json \
  --schema .provenance.json
```

Expected output:
```
Verifying provenance: provenance-output.json
  ✓ Provenance header present
    schema_hash: sha256:abcd1234...
  ✓ price: Deterministic — hash chain present
  ✓ volume: Deterministic — hash chain present
  ℹ️  analysis: AIDerived — honestly labeled, no verification possible

✓ Verification passed: 4 checks, 0 failures
```

## 5. Export for Compliance

```bash
# W3C PROV-JSON (for compliance tooling)
# Coming soon: nucleus-audit export-prov --output provenance-output.json
```

## What Just Happened?

The `price` and `volume` values have a **cryptographic proof chain**:

```
Source URL → SHA-256 content hash → WASM parser (content-addressed) → output hash
```

The flow graph proves there is **no model node** in the causal ancestry of these values. The model orchestrated the fetch and parser, but never touched the data. An auditor can independently re-execute the parser on the raw content and verify the output hash matches.

The `analysis` field is honestly labeled as `AIDerived` — the model generated it, and the provenance output says so. No false claims.

## Schema Reference

### Sources

```json
{
  "url_template": "https://...",     // {key} placeholders resolved from user params
  "content_type": "application/json", // expected MIME type (optional)
  "max_staleness_secs": 600          // reject data older than N seconds (optional)
}
```

### Fields

```json
{
  "source": "source_name",           // which source this field draws from
  "derivation": "deterministic",     // "deterministic" | "ai_derived" | "user_provided"
  "parser": "jq",                    // parser ID from registry (deterministic only)
  "expression": ".field.path"        // parser expression (deterministic only)
}
```

### Derivation Types

| Type | Model Touches Data? | Verification | Use For |
|------|-------------------|-------------|---------|
| `deterministic` | **No** — WASM parser extracts, model excluded | Full hash chain + replay | Financial data, regulatory values |
| `ai_derived` | **Yes** — model generates the value | Honest labeling only | Summaries, analysis, formatting |
| `user_provided` | **No** — user supplies directly | Directive authority | Parameters, configuration |

## Next Steps

- **Compartments**: Use `research` → `draft` compartment transitions for web content isolation
- **Multi-agent**: Sub-agents carry provenance chains linked to the parent
- **Custom parsers**: Build WASM parsers with the nucleus parser ABI (alloc + parse exports)
- **Security demos**: Run `nucleus-claude-hook --smoke-test` to verify defense layers

## Regulatory Compliance

| Standard | What Nucleus Provides |
|----------|----------------------|
| **EU AI Act Article 50** | `contains_ai_derived` flag, machine-readable provenance |
| **FINRA/SEC** | Immutable receipt chain, Ed25519 signed |
| **W3C PROV-DM** | PROV-JSON export from flow graph |
| **NIST AI RMF** | Execution context telemetry in receipts |
