# AI Codex — Reputation Receipt v2 (FROZEN)

> Extension of [SPEC-reputation-receipt-v1](./SPEC-reputation-receipt-v1.md). **v1 remains valid and unchanged** (`review`/`dispute`). v2 adds three new `interaction` types (`escrow`, `stake`, `uptime`) so that **all six components** of the `aicodex-norm-v1` score can receive real, verifiable input. **Same rules, same anti-Sybil gate, same submission path.** AI Codex **issues/serves/aggregates/verifies, never executes**. Non-modifiable contract in place: any change = `reputation-receipt-v3`.

## 1. Why v2

The `aicodex-norm-v1` score (SPEC-identity §3.3, frozen) weights six components: `escrow` 40%, `uptime` 20%, `reviews` 20%, `stake` 10%, `age` 10%, `disputes` −30%. v1 only fed `reviews`/`disputes` (receipts) and `age` (intrinsic). `escrow`/`stake` are **financial** and `uptime` comes from **probes**: AI Codex is rail-neutral and does not generate these itself. The honest and consistent way to feed them is **the same as receipts**: **attestations signed by an accountable counterparty**. v2 touches **neither the formula, nor the normalization, nor the anti-Sybil gate**.

## 2. Accountable Issuer (identical to v1, frozen)

Unchanged: a receipt is counted only if its issuer is **accountable** — `did:web:host` (proven domain) **or** a registered `did:key:z…` **AND** bound to a verified principal (SPEC-principal-binding-v1). Otherwise `E_ISSUER_NOT_ACCOUNTABLE` (403). Self-attestation (`issuer == subject`) → `E_SELF_ATTESTATION` (400). This is the cost that makes spam financially expensive.

## 3. New Interaction Receipts (structure frozen)

Same envelope as v1 (`@context`, `type = ["VerifiableCredential","AICodexInteractionReceipt"]`, `issuer`, `validFrom`, `credentialSubject`, `proof` `eddsa-jcs-2022` by the issuer's key, VM references the issuer). Only `credentialSubject` changes based on `interaction`.

### 3.1 `escrow` — attested successful escrows

```json
"credentialSubject": { "id": "did:key:z<agent>", "interaction": "escrow", "count": 3 }
```
- `count`: **integer ≥ 1** (bool excluded). Number of settled escrows that the issuer attests to have completed with the subject.
- No other fields (key set **exactly** `{id, interaction, count}`).

### 3.2 `stake` — current stake in USD

```json
"credentialSubject": { "id": "did:key:z<agent>", "interaction": "stake", "usdValue": 2500.0 }
```
- `usdValue`: **number ≥ 0** (`int` or `float`, bool excluded). Stake currently locked/guaranteed by the subject, attested by the issuer (custodian/registry).
- Key set **exactly** `{id, interaction, usdValue}`.

### 3.3 `uptime` — probe result

```json
"credentialSubject": { "id": "did:key:z<agent>", "interaction": "uptime", "success": 670, "total": 672 }
```
- `success`: **integer ≥ 0**; `total`: **integer ≥ 1**; **`0 ≤ success ≤ total`** (bool excluded). Aggregated results from a third-party probe (cf. norm `uptime`: < 672 probes caps at 50).
- Key set **exactly** `{id, interaction, success, total}`.

`credentialSubject.id` (subject) remains a conformant Ed25519 `did:key`, **distinct from the issuer**. No `validUntil`. **Append-only**, recomputed on every read.

## 4. Signature / Submission / Resolution (identical to v1, frozen)

- Signature `eddsa-jcs-2022` by the issuer's key, VM references the issuer. No new primitive.
- Submission: MCP `declare_receipt`, REST `POST /v1/receipt` (alias `/v1/attestation` accepted). **Server validation order identical to v1 §5**: conformance §3 (`E_RECEIPT_MALFORMED`) → subject `did:key` (`E_DID_MALFORMED`) → subject registered (`E_DID_NOT_FOUND`) → issuer ≠ subject (`E_SELF_ATTESTATION`) → issuer key resolved (`E_ISSUER_MALFORMED`/`E_ISSUER_UNRESOLVABLE`) → issuer accountable (`E_ISSUER_NOT_ACCOUNTABLE`) → valid proof (`E_BAD_SIGNATURE`) → append-only, idempotent insertion.
- Resolution: `GET /v1/receipt/{did}` returns all receipts for the subject (v1+v2), most recent first.

## 5. Score Aggregation (frozen)

At each `get_reputation(subject)` call, in addition to v1 (reviews/disputes) and `age`:
- **`escrow`** = **sum of `count`** across all `escrow` attestations for the subject → `norm.escrow` (log, cap 100). The sum is intentional: issuer accountability (§2) is the anti-Sybil cost; idempotency prevents double-counting of identical attestations.
- **`stake`** = `usdValue` from the **most recent** `stake` attestation (by `validFrom`) → `norm.stake` (log).
- **`uptime`** = `(success, total)` from the **most recent** `uptime` attestation → `norm.uptime`.
- `reviews`/`disputes`/`age` **unchanged**. The final formula §3.1 and normalization §3.3 are **unchanged**.
- As soon as at least one of these inputs contributes, the VC carries `activityTracked: true` (real external activity).

## 6. Conformance (frozen)

A v2 receipt is conformant if and only if: (a) VC `AICodexInteractionReceipt` signed by the issuer (VM references the issuer), (b) `interaction ∈ {review, dispute, escrow, stake, uptime}` with the **EXACT field set and bounds** from §3 (v1) / §3.1-3.3 (v2), (c) subject is an Ed25519 `did:key`, (d) **no rail**, (e) stored append-only. `issuer ≠ subject` and issuer accountability remain **ingestion** conditions (§4), not structural conformance; `verify_receipt` also rejects self-attestation (defense in depth).

## 7. Storage (identical to v1, frozen)

Table `receipts` unchanged: the **full JSON** of the receipt is already stored in the `receipt` column. The fields `count`/`usdValue`/`success`/`total` are read from `receipt.credentialSubject` at aggregation time (the `rating` column remains `NULL` for v2 types). No schema migration.

## 8. Error Codes / Quotas (identical to v1, frozen)

Unchanged (v1 §8-§9). Same codes, same quotas (10/min, 100/day per IP; payload ≤ 8 KiB).

## 9. Out of Scope for v2 (locked)

- Weighting an attestation by the issuer's reputation, attestation dispute, cryptographic on-chain verification of escrow/stake reality: excluded (determinism). Reintroduction = new versioned profile.
- AI Codex **does not verify** that an escrow/stake/uptime actually occurred: it verifies that an **accountable counterparty attests to it** and exposes it, verifiable off-platform. Trust rests on issuer accountability, not on a financial oracle.