# Attestation proof shape v1.0.0

Required shape for public **admit** on `/api/package` and `/api/verify`.  
Cheap copies that omit a limb, invent ATTESTED labels, or skip RWA registry refs fail.

**Live copy:** `https://geniusflow-federation.vercel.app/docs/ATTESTATION_PROOF_SHAPE.md`  
**Code:** `engine/bridge/attestation_proof_shape.py` (engine) · embedded stdlib helpers in federation package/verify handlers.  
**OpenAPI:** `/openapi.json` → `components.schemas.ProofShape` / `Proof`  
**Contract tests:** `engine/bridge/tests/test_proof_shape_v1_stable.py` (`proof_shape_v1 stable`)

## Stability guarantee (`best_effort_vercel`)

Under the sit / `best_effort_vercel` tier, **proof_shape v1.0.0 field names and limb order are frozen**:

- Summary keys: `version`, `limbs`, `admitted`, `failed_limbs`, `refuse_limb`
- Detail (`proof`) keys: those plus `spec` (and `invented_attestation` on verify)
- Limb order: `registry_ref` → `refuse_or_admit` → `provenance_spine`

Do **not** rename or silently drop these. Additive optional keys are fine. A rename requires an intentional version bump (`PROOF_SHAPE_VERSION`), not casual churn. Availability of the endpoints remains best-effort; the **shape contract** is what stays stable.

## Limbs (order stable)

| Limb | Role |
|------|------|
| `registry_ref` | Required when claim is RWA-scoped (`rwa`, `requires_registry_ref`, RWA asset_class, registry fields, or known RWA entity). Otherwise `not_applicable`. Never invent a registry address. |
| `refuse_or_admit` | Package disposition semantics, or verify grounding match. Refuse cites `reason` / `note`. |
| `provenance_spine` | Required layer slots (`helix`, `wfp`, `act_account`, `federation`, `cite_verify_rail`) + claim-carried evidence pointers (`grounding.source_url` + `expected`, optional custody/helix fingerprints). **Does not invent** cycle `provenance_spine_latest` ok. |

## Response object

On package/verify responses:

```json
{
  "proof_shape": {
    "version": "1.0.0",
    "limbs": ["registry_ref", "refuse_or_admit", "provenance_spine"],
    "admitted": false,
    "failed_limbs": ["refuse_or_admit"],
    "refuse_limb": "refuse_or_admit"
  },
  "proof": {
    "version": "1.0.0",
    "admitted": false,
    "limbs": { "...": "per-limb detail" },
    "failed_limbs": ["refuse_or_admit"],
    "refuse_limb": "refuse_or_admit",
    "invented_attestation": false
  }
}
```

- **Admit** only when every limb `ok`.
- **Refuse** must set `refuse_limb` (and usually `reason` like `proof_shape_limb_failed:registry_ref:missing_registry_ref`).
- Verify never upgrades a miss to ATTESTED.

## Why cheap copies fail

1. Missing `proof` / `proof_shape` version or limb keys → not shape-conformant.
2. RWA claim without registry contract → registry limb fails.
3. Attested status without grounding pointers → provenance limb fails (no invent).
4. Scrape-only “verify” without published `expected` → refuse; inventing expected is out of policy.

## Counterparties later

Governance mandates / bank signup / paid 5.4 attestation products need counterparties — not invented here.