hosted/IF_EMOTION_DEBUGGING_TRACE_WHITEPAPER_v3.2_STYLED.md

# IF.EMOTION TRACE PROTOCOL v3.2 — AUDITABLE DEBUGGING (WITHOUT WISHFUL THINKING)

**Alternate title:** Debugging Emotion — the Immutable Flight Recorder

**Subject:** End-to-end traceability, bounded completeness witnessing, and PQ-anchored evidence binding

**Protocol:** IF.TTT (Traceable, Transparent, Trustworthy)

**Version:** 3.2 (Methodology hardening: key separation + monotonic timing + correlation-only client trace)

**Date (UTC):** 2025-12-21

**Status:** AUDIT REQUIRED

**Citation:** `if://whitepaper/emotion/trace-protocol/v3.2`

---

## What this is (and why it matters)

If you run an LLM system in a high-liability environment, you eventually hit the moment where “the logs say” isn’t enough. You need evidence you can hand to someone who does not trust you.

*This is not an observability feature. It’s chain-of-custody.*

This protocol is a practical answer to one question:

Can an external reviewer independently verify what happened from request → retrieval → output, and detect tampering after the fact?

It intentionally separates what we can prove from what we cannot.

---

## Guarantees (and boundaries)

This system provides **integrity** guarantees (tamper-evidence) and **bounded completeness** guarantees (witnessing) within explicit boundaries.

- **Integrity:** the trace timeline is hash-chained; the signed summary binds the final output to a trace head.
- **Completeness (bounded):** a REQ_SEEN ledger witnesses each request that crosses the backend witness boundary, with a signed per-hour Merkle head.
- **PQ anchoring (bounded):** Post-quantum signatures apply at registry anchoring time (IF.TTT), not necessarily on every hot-path artifact.

One sentence boundary (non-negotiable):

Integrity starts at the backend witness boundary; completeness is only meaningful at and after that boundary until edge witnessing is cryptographically enforced.

---

## Layered evidence stack (where guarantees live)

```mermaid
flowchart TB
  U[User] -->|HTTPS| E[Edge]
  E --> B[Backend Witness Boundary]

  B --> R[Retrieval]
  B --> P[Prompt]
  B --> M[Model]
  B --> X[Postprocess]

  B --> T1["REQ_SEEN ledger<br/>(hourly JSONL)"]
  B --> T2["Trace events<br/>(hash chain JSONL)"]
  B --> T3["Signed summary<br/>(output hash + head attestation)"]

  T1 --> H["Signed Merkle head<br/>(per hour)"]
  T2 --> S["Trace head<br/>(event_hash)"]

  H --> BUNDLE["Evidence bundle<br/>(tar.gz + manifest)"]
  S --> BUNDLE
  T3 --> BUNDLE

  BUNDLE --> REG["Registry anchor<br/>(PQ-hybrid)"]
  BUNDLE --> MIRROR["Static mirror<br/>(public download)"]
```

Interpretation:

Integrity starts at the witness boundary; completeness is only meaningful at and after that boundary until edge witnessing exists.

---

## Evidence inventory (what ships)

| Artifact | File | Claim it supports | Verification |
|---|---|---|---|
| Evidence bundle | `emo_trace_payload_96700e8e-6a83-445e-86f7-06905c500146.tar.gz` | Portable reproduction | `sha256sum` + verifier |
| Manifest + checksums | `payload/manifest.json`, `payload/sha256s.txt` | “One check implies contents” | verifier validates per-file SHA256 |
| Trace event chain | `payload/trace_events.jsonl` | Tamper-evident event ordering | verifier recomputes event hashes |
| Signed summary | `payload/ttt_signed_record.json` | Binds response hash → trace head | verifier recomputes HMAC signature |
| REQ_SEEN ledger | `payload/req_seen_<hour>.jsonl` | Bounded completeness | verifier recomputes leaf hashes + Merkle root |
| REQ_SEEN head | `payload/req_seen_head_<hour>.json` | Signed Merkle head | verifier checks Ed25519 signature |
| Inclusion proof | `payload/req_seen_inclusion_proof.json` | Proves this trace is in the hour ledger | verifier checks Merkle path |
| IF.story annex | `payload/if_story.md` and external annex | Human-readable timeline | anchors must reference real `event_hash` |
| Registry corroboration | `*.ttt_chain_record.json` | PQ-anchored record (when available) | compare content hashes |

---

## Methodology hardening in v3.2 (the changes that close real audit gaps)

### HMAC key separation for REQ_SEEN (no mixed keys)

REQ_SEEN uses HMAC commitments only if `IF_REQ_SEEN_HMAC_KEY` is configured. It never reuses the signing secret used for the signed summary.

If `IF_REQ_SEEN_HMAC_KEY` is missing, REQ_SEEN downgrades to SHA256 commitments and the system must not claim “privacy-preserving HMAC commitments”.

### Correlation-only client trace IDs (collision discipline)

If a client provides `X-IF-Client-Trace`, it is treated as a correlation-only identifier.

The canonical trace ID is always server-generated and returned in `X-IF-Emotion-Trace`.

### Monotonic timing fields (clock realism)

Each trace event includes:

- `ts_utc`: wall-clock timestamp (not trusted for crypto time)
- `mono_ns` / `mono_ms`: monotonic timing since trace start (stable ordering and performance attribution)

This does not solve time attestation, but it removes “clock drift” as an excuse for missing latency evidence.

### Inclusion proof is a first-class prior

The inclusion proof file is registered as a child artifact in IF.TTT. It is not optional.

---

## Reference proof run (v3.2)

Trace ID:

- `96700e8e-6a83-445e-86f7-06905c500146`

Evidence bundle:

- Static mirror (preferred): `https://infrafabric.io/static/hosted/emo_trace_payload_96700e8e-6a83-445e-86f7-06905c500146.tar.gz`
- Forgejo raw (alternate): `https://git.infrafabric.io/danny/hosted/raw/branch/main/emo_trace_payload_96700e8e-6a83-445e-86f7-06905c500146.tar.gz`

Tarball SHA256:

- `85eb323c8e5f11cf4dd18e612e8cde8dcdb355b3fbd6380bbc8d480a5bf97e87`

IF.TTT tarball handle:

- `if://citation/2ec551ec-0a08-487d-a41d-4d068aa8ee2f/v1`

---

## Verification (external reviewer path)

Download + hash:

```bash
curl -fsSL -o emo.tar.gz 'https://infrafabric.io/static/hosted/emo_trace_payload_96700e8e-6a83-445e-86f7-06905c500146.tar.gz'
sha256sum emo.tar.gz
# expected: 85eb323c8e5f11cf4dd18e612e8cde8dcdb355b3fbd6380bbc8d480a5bf97e87
```

Run verifier:

```bash
python3 -m venv venv
./venv/bin/pip install canonicaljson pynacl
curl -fsSL -o iftrace.py 'https://infrafabric.io/static/hosted/iftrace.py'
./venv/bin/python iftrace.py verify emo.tar.gz --expected-sha256 85eb323c8e5f11cf4dd18e612e8cde8dcdb355b3fbd6380bbc8d480a5bf97e87
```

REQ_SEEN inclusion proof check:

```bash
tar -xzf emo.tar.gz
./venv/bin/python iftrace.py verify-inclusion payload/req_seen_inclusion_proof.json
# expected: OK
```

---

## Narrative annex

IF.story is not evidence; it is a deterministic projection keyed by `event_hash`.

- Static mirror: `https://infrafabric.io/static/hosted/IF_EMOTION_TRACE_REFERENCE_96700e8e-6a83-445e-86f7-06905c500146_IF_STORY.md`
- Forgejo raw: `https://git.infrafabric.io/danny/hosted/raw/branch/main/IF_EMOTION_TRACE_REFERENCE_96700e8e-6a83-445e-86f7-06905c500146_IF_STORY.md`

---

## Limitations (still true)

- This proves what the system did and what bytes were served. It does not prove factual truth in the world.
- Completeness is bounded by the witness boundary; requests dropped before the backend boundary are out of scope until edge witnessing is cryptographically bound.
- Key management and time attestation remain the practical certification blockers (HSM/TPM, rotation ceremony, external timestamping).

---

## What to do next (tomorrow’s work, not wishful thinking)

- Move REQ_SEEN witnessing to the true front door (edge) and sign the head there.
- Publish a deploy attestation record (code hash + image digest) into IF.TTT for every release.
- Add a clear anchoring SLO (maximum time from trace finalization → registry anchor) and enforce it.