# Predicate Schema Registry

## Status
- Status: DRAFT (2026-02-19)
- Owner: Attestor Guild
- Sprint: SPRINT_20260219_010

## Purpose
Replace hardcoded predicate type URIs scattered across the codebase with a discoverable, versioned, PostgreSQL-backed registry. External tooling (cosign, policy-as-code engines, audit exporters) can query the registry to discover and validate predicate schemas.

## Design

### Storage
- Schema: `proofchain` (alongside existing proof chain tables)
- Table: `proofchain.predicate_type_registry`

### Data Model
Each registry entry:
| Column | Type | Description |
|--------|------|-------------|
| `registry_id` | UUID | Primary key |
| `predicate_type_uri` | TEXT UNIQUE | The canonical predicate type URI |
| `display_name` | TEXT | Human-readable name |
| `version` | TEXT | Semver string (e.g., "1.0.0") |
| `category` | TEXT | Category: stella-core, stella-proof, ecosystem, intoto |
| `json_schema` | JSONB | JSON Schema document for payload validation (nullable) |
| `description` | TEXT | Purpose description |
| `is_active` | BOOLEAN | Whether this type accepts new submissions |
| `validation_mode` | TEXT | log-only / warn / reject (default: log-only) |
| `created_at` | TIMESTAMPTZ | Created timestamp |
| `updated_at` | TIMESTAMPTZ | Last update timestamp |

### Immutability Rule
Once a `(predicate_type_uri, version)` pair is published, its `json_schema` MUST NOT change. New versions get new semver.

### API Endpoints
- `GET /api/v1/attestor/predicates` — List all registered predicate types (paged, filterable by category and is_active)
- `GET /api/v1/attestor/predicates/{uri}` — Get schema and metadata for a specific predicate type URI (URI is URL-encoded)
- `POST /api/v1/attestor/predicates` — Register a new predicate type (admin-only, OpTok-gated with `attestor:admin` scope)

### Submission Validation
When a DSSE envelope is submitted via `POST /api/v1/rekor/entries`:
1. Look up `predicate_type` in registry
2. If found and `validation_mode = "log-only"`: validate payload against `json_schema`, log result (pass/mismatch), proceed
3. If found and `validation_mode = "warn"`: validate, emit warning metric, proceed
4. If found and `validation_mode = "reject"`: validate, reject on mismatch (400 Bad Request)
5. If not found: log unknown predicate type, proceed (don't block unregistered types during rollout)

### Seeded Predicate Types (from codebase analysis)

**stella-core (Attestor native):**
1. `https://stella-ops.org/predicates/sbom-linkage/v1`
2. `https://stella-ops.org/predicates/vex-verdict/v1`
3. `https://stella-ops.org/predicates/evidence/v1`
4. `https://stella-ops.org/predicates/reasoning/v1`
5. `https://stella-ops.org/predicates/proof-spine/v1`
6. `https://stella-ops.org/predicates/reachability-drift/v1`
7. `https://stella-ops.org/predicates/reachability-subgraph/v1`
8. `https://stella-ops.org/predicates/delta-verdict/v1`
9. `https://stella-ops.org/predicates/policy-decision/v1`
10. `https://stella-ops.org/predicates/unknowns-budget/v1`
11. `https://stella-ops.org/predicates/ai-code-guard/v1`
12. `https://stella-ops.org/predicates/fix-chain/v1`
13. `https://stella-ops.org/attestation/graph-root/v1`

**stella-proof (ProofChain predicates):**
14. `https://stella.ops/predicates/path-witness/v1`
15. `https://stella.ops/predicates/runtime-witness/v1`
16. `https://stella.ops/predicates/policy-decision@v2`
17. `https://stellaops.dev/predicates/binary-micro-witness@v1`
18. `https://stellaops.dev/predicates/binary-fingerprint-evidence@v1`
19. `https://stellaops.io/attestation/budget-check/v1`
20. `https://stellaops.dev/attestation/vex/v1`
21. `https://stellaops.dev/attestations/vex-override/v1`
22. `https://stellaops.dev/predicates/trust-verdict@v1`
23. `https://stellaops.io/attestation/v1/signed-exception`
24. `https://stellaops.dev/attestation/verification-report/v1`

**stella-delta (Delta predicates):**
25. `stella.ops/changetrace@v1`
26. `stella.ops/vex-delta@v1`
27. `stella.ops/sbom-delta@v1`
28. `stella.ops/verdict-delta@v1`
29. `stellaops.binarydiff.v1`

**ecosystem (Standard predicates):**
30. `https://spdx.dev/Document`
31. `https://cyclonedx.org/bom`
32. `https://slsa.dev/provenance`

**intoto (In-Toto standard):**
33. `https://in-toto.io/Statement/v1`
34. `https://in-toto.io/Link/v1`
35. `https://in-toto.io/Layout/v1`