# The wedge: 5-tier cryptographic chain-of-custody for AI artifacts

**Companion doc to the cycle-415 MCP surface** (`ip://wedge/tiers` resource +
`explain_wedge` tool). The platform's differentiator vs generic RAG stores
is not "we serve content" — it's "we sign a receipt at every layer of how
the artifact came to be." A regulator, a Drata import worker, or a
court-of-record auditor can re-derive the chain from raw bytes without
trusting the platform.

This doc is the REST-readable channel of the triplicate-channels pattern
(resource + tool + doc) the cycle-415 commit body called out as a strength
to amplify.

## The five tiers

| # | Name | What gets signed | Attested by | Schema |
|---|---|---|---|---|
| 1 | **pipeline** | Data-movement step (a dbt / Airflow / Spark / Flink run that produced the dataset bytes the model trained on) | Platform domain key OR runner `did:web` | [`/credentials/pipeline-facet/v1`](/credentials/pipeline-facet/v1) |
| 2 | **experiment** | Training-run completion (hyperparams + checkpoint sha + dataset sha) | Training operator `did:key`/`did:web` | [`/credentials/experiment-receipt/v1`](/credentials/experiment-receipt/v1) |
| 3 | **leaderboard** | Eval-harness score (runId + harnessVersionSha + datasetSha + evalCodeSha + samplingParams) | Runner `did:web` — Princeton HAL, Scale Labs, AISI, etc. | [`/credentials/eval-run/v1`](/credentials/eval-run/v1) |
| 4 | **review** | PR / code-review verdict — the first cryptographic merge gate | Reviewer `did:key` + optional human co-signer DID | [`/credentials/review/v1`](/credentials/review/v1) |
| 5 | **governance** | controlId × frameworkId × subjectArtifactId (Drata / Vanta / OneTrust import row) | Audit firm `did:web` (or platform `did:web` for self-attest) | [`/credentials/governance-compliance/v1`](/credentials/governance-compliance/v1) |

Each tier signs the layer below. A verifier walking *upward* from the
attestation they hold ends at the raw bytes; a verifier walking *downward*
from the bytes ends at the most-recent governance attestation.

## Five killer features

The five tiers above are the *architecture*. The five killer
features below are *what an agent does with the architecture* —
the value-prop names that distinguish IntelligencePro from a
generic registry. Each feature is a workflow an agent can ship
TODAY against the platform's existing schemas. (CSN-756-P0-1
cycle-757 fix: pre-cycle-757 these names appeared only in
`/llms.txt` + `/.well-known/ip-knowledge.json`; a cold-start
agent following this doc never saw them.)

| Killer feature | Tier | Schema | What an agent does with it |
|---|---|---|---|
| **ip-merge-gate** | 4 — review | [`/credentials/review/v1`](/credentials/review/v1) | Convert an AI code-review verdict into a SIGNED merge gate. Architecturally impossible for self-reviewing systems (CodeRabbit / Greptile / qodo / GitHub Copilot Code Review) — they're the agents being verified. Detached peer attestation is the only architecture that delivers it. GitHub Action: see `/docs/ip-merge-gate-action.md`. |
| **ip-verified-retrieval** | 4+1 | [`/credentials/retrieval-citation/v1`](/credentials/retrieval-citation/v1) + [`/credentials/pipeline-facet/v1`](/credentials/pipeline-facet/v1) | Bind a retrieval-augmented response to a cryptographically-signed source-attestation chain. Anti-hallucination anchor: the LangChain / LlamaIndex callback handler emits ip.retrieval.citation.v1 per source; downstream consumers verify the citation chain ends in a pipeline-facet attesting where the data came from. |
| **ip-eval-attested** | 3 — leaderboard | [`/credentials/eval-run/v1`](/credentials/eval-run/v1) | Cryptographically attest an eval-harness result. Decouples scoreboard publication from the runner — Princeton HAL / Scale / AISI / Inspect AI / lm-evaluation-harness emit signed eval-run attestations, the platform composes them into a verifiable leaderboard. Closes the cycle-274 "your eval is real" trust gap. |
| **ip-tutorial-attested** | 1 — pipeline | [`/credentials/tutorial-citation/v1`](/credentials/tutorial-citation/v1) | Attest that a tutorial / cookbook recipe's code actually runs against a specific artifact + dataset. Anthropic / OpenAI / Google cookbook pages embed an ip.tutorial.citation.v1 footer; a fresh-eye reader running the recipe knows it WAS verified end-to-end on a real artifact sha at a specific point in time, not just authored-and-shipped. |
| **ip-support-attested** | 4 — review | [`/credentials/support-resolution/v1`](/credentials/support-resolution/v1) | Cryptographic attestation of a customer-support resolution. Same architectural shape as ip-merge-gate (an agent judging another agent's work): a Zendesk / Intercom resolution gets a signed peer-attestation that an INDEPENDENT support agent confirmed the resolution was correct. Closes the cs_agent_judging_cs_agent gap that Salesforce / Zendesk can't ship themselves. |

A cold-start agent reading this table sees the five canonical
**workflows** the platform sells. The tiers above are the
substrate; the killer features are the surface area an agent
ships against. Each schema is independently consumable via
`POST /api/credentials/dry-run` (unauth, free) before committing
to register.

## Why this is the differentiator

Generic AI registries (HuggingFace, OpenRouter, Together AI) serve
**content**. They prove "this model file has this SHA." They don't tell
you which dataset trained the model, which eval harness produced its
score, which reviewer co-signed the PR that landed it, or which audit
framework's control row covers the deployment.

IntelligencePro stitches the receipt chain. Each row is W3C VC 2.0-
shaped, signed with `eddsa-jcs-2022` per RFC 8785 canonicalization. The
chain composes:

```
governance.compliance.v1 (tier 5)
  evidenceShaArray[].sha256 → review.attestation.v1 (tier 4)
                                citedEvidenceShaArray[].sha256
                                  → eval.run.attestation.v1 (tier 3)
                                      datasetSha →
                                        experiment.receipt.v1 (tier 2)
                                          datasetSha →
                                            pipeline.facet.v1 (tier 1)
                                              outputSha → raw bytes
```

Each attestation in this chain is *individually* verifiable today —
fetch it, resolve the issuer key, check the `eddsa-jcs-2022` signature,
all without talking to the platform (the L1 domain + L2 per-judge
cryptography is live and independently sound; an external auditor
confirmed this end-to-end with their own JCS+Ed25519 verifier, cycle
1040). The *end-to-end multi-tier walk* — recursing from a governance
attestation down to the dataset bytes — is the mechanism described
below, but is **not yet demonstrable on live data**: chain population
is issuance-pending (step 3's ⚠ note) and no fully-populated chain is
published yet (`/api/knowledge/eval/list?status=published` is currently
empty). So the links that exist verify cryptographically; the full walk
is real in mechanism and aspirational in live coverage. The platform is
a convenience layer — the cryptography is the trust layer.

## Walk-up verification recipe

Given any tier-N attestation you hold:

1. **Fetch.** GET `/api/badge/v1/attestation/<kind>/<sha>` or the
   canonical `/credentials/<slug>/v1` schema endpoint serves the
   shape; the platform's own surface returns the attestation row.
2. **Verify proof.** The attestation's `proof.signature` is an
   Ed25519 signature over the RFC 8785-canonical bytes of the
   document. Verify against:
   - The issuer's JWKS (resolve via `did:web` to
     `https://<host>/.well-known/jwks.json`), or
   - The `verificationMethod` in the issuer's DID doc at
     `<host>/.well-known/did.json`.
3. **Walk references.** Two parallel substrates point downward toward
   tier-1:
   - **`chain.parentSha256` + `chain.parentKind`** — uniform upward
     traversal added by the cycle-484 substrate. Schema-declared on
     all 19 non-root leaf kinds (every `/credentials/<slug>/v1`
     EXCEPT `pipeline.facet` and `attestation.event`; sp-813-P1-2
     correction cycle 815). Fetch the parent attestation by that
     sha and recurse.
     **⚠ Issuance-pending** (rc-795-P0-1 cycle 801): the field is
     schema-declared but issuance-time population is multi-cycle —
     today most live attestations have `chain: absent`. The dry-run
     advisory (cycle 808) nudges producers to backfill it. Until
     full rollout, the legacy refs below remain the dominant walk.
   - **Legacy per-tier downward refs** (today-dominant): tier-5
     `governance.compliance.evidenceShaArray[]`; tier-3
     `leaderboard.receipt.experimentReceiptId` →
     `experiment.receipt.inputPipelineRunIds[]`; tier-4
     `review.attestation.sandboxRunId`; retrieval +
     tutorial `citedEvidenceShaArray[]`. Each points at a lower-tier
     attestation. Recurse.
4. **Bottom-out.** A tier-1 `pipeline.facet.v1` attestation's
   `outputSha` is the dataset bytes itself. Re-hash the bytes;
   compare. The chain is complete.

See [`/docs/verification-recipe.md`](/docs/verification-recipe.md) for
the curl trail end-to-end. See
[`/docs/judges-digest-recipe.md`](/docs/judges-digest-recipe.md) for
the canonical projection that binds reviewer identity into the
signature. See [`/docs/runner-did-bootstrap.md`](/docs/runner-did-bootstrap.md)
for how to mint the `runnerDid` field on a tier-3 leaderboard attestation.
See [`/docs/eval-attestation-bridge.md`](/docs/eval-attestation-bridge.md)
for the field-by-field mapping from `lm-eval-harness results.json` to
the tier-3 VC envelope.

## Cross-channel discovery

The same content surfaces in four channels for cross-protocol parity:

| Channel | Where | Format |
|---|---|---|
| REST docs | `/docs/wedge.md` (this doc) | Markdown |
| MCP resource | `ip://wedge/tiers` (cycle 415) | JSON via `resources/read` |
| MCP tool | `explain_wedge` (cycle 415) | JSON via `tools/call` |
| Machine-readable catalog | [`/credentials/index.json`](/credentials/index.json) (cycle 387) | JSON (the 21-schema catalog superset; high-risk-classification.v1 added cycle 639) |

All four converge on the same `wedgeTiersPayload()` source of truth in
`app/api/mcp/route.ts`. An MCP-only client reads the resource; a REST-
only client reads this doc; a cross-protocol verifier compares both for
parity. The triplicate-channels pattern follows the cycle-414 MCP-only
audit's S2 strength (onboarding-path served as instructions + prompt +
resource simultaneously).

## What this is NOT

- **Not a model registry.** The wedge is about attestation lineage; the
  artifact-storage layer is HuggingFace / S3 / GCS / your own CAS. The
  platform's `evidenceShaArray[].sha256` points at bytes you host
  wherever; we just sign the *claim* about those bytes.
- **Not a governance dashboard.** Drata / Vanta / OneTrust / IBM
  watsonx.governance render dashboards; the platform supplies the
  *signed evidence rows* those dashboards import. The platform's
  tier-5 schema (`ip.governance.compliance.v1`) is explicitly designed
  as their universal evidence-import shape (see cycle 404 for the
  controlOwnerDid / evidenceCollectedAt / testFrequency / assertionType
  additions that satisfy SOC 2 + PCAOB + ISO 42001 routing).
- **Not a verification cache.** Each verifier re-derives the chain
  from raw bytes; the platform doesn't memoize "this VC is valid."
  Verification is local + deterministic by design.

## See also

- [`/credentials`](/credentials) — HTML catalog of all 21 attestation
  schemas (cycle 401)
- [`/credentials/index.json`](/credentials/index.json) — machine-
  readable catalog (cycle 387)
- [`/.well-known/ip-knowledge.json`](/.well-known/ip-knowledge.json)
  — full platform descriptor
- [`/openapi.json`](/openapi.json) — REST contract for every endpoint
- [`/llms.txt`](/llms.txt) — single-page agent-readable site index