# AI Codex — Spécification d'identité canonique v0.1

> Document de référence. Neutre, ouvert, versionné. Aucun code applicatif : formats de données et contrats d'interface uniquement. Toute implémentation future doit s'y conformer.
>
> Décisions verrouillées 2026-05-18 (déléguées par l'utilisateur) :
> - Coeur canonique = W3C DID + Verifiable Credentials par-dessus l'ed25519 existant.
> - 3 premiers adaptateurs = MCP → A2A → AP2 (dans cet ordre).
> - Marketplace crypto DÉCOUPLÉE de l'identité (neutralité = condition du rôle de pont).

## 1. Périmètre et principes

- **Un agent = un DID canonique.** Tout le reste (MCP, A2A, AP2) est une *projection* de ce DID.
- **La réputation est une Verifiable Credential** signée, à expiration courte, vérifiable sans AI Codex.
- **Zéro lock-in** : identité et réputation exportables intégralement.
- **Neutralité** : aucun rail (crypto/cartes) privilégié dans le coeur. Les rails vivent dans les adaptateurs.
- Conformité : **W3C DID Core 1.0** + **W3C Verifiable Credentials Data Model 2.0**. Signatures **Ed25519** (`EdDSA`).

## 2. DID canonique

**Méthode** : `did:key` (auto-souverain, par défaut) ou `did:web` (organisations). Identifiant dérivé de la clé publique Ed25519 existante : aucune migration de clé.

### 2.1 DID Document

```json
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:key:z6Mk...",
  "controller": "did:key:z6Mk...",
  "verificationMethod": [{
    "id": "did:key:z6Mk...#key-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:key:z6Mk...",
    "publicKeyMultibase": "z6Mk..."
  }],
  "authentication": ["did:key:z6Mk...#key-1"],
  "assertionMethod": ["did:key:z6Mk...#key-1"],
  "service": [
    { "id": "#mcp",        "type": "AICodexMCP",        "serviceEndpoint": "https://maxiaworld.app/mcp" },
    { "id": "#a2a",        "type": "A2ACard",           "serviceEndpoint": "https://maxiaworld.app/a2a/<did>.json" },
    { "id": "#reputation", "type": "AICodexReputation", "serviceEndpoint": "https://maxiaworld.app/reputation/<did>" }
  ]
}
```

### 2.2 Métadonnées AI Codex (hors DID Core, profil AIP)

Bloc séparé, lié au DID, **jamais** dans le DID Document (le DID Document reste W3C-pur pour interop) :

```json
{
  "did": "did:key:z6Mk...",
  "aip": "0.3.0",
  "birth": { "block": "<chain>:<height>", "ts": "2026-..." },
  "lineage": { "parent": "did:key:z6Mk...|null", "inherited": 0.10 },
  "frameworks": ["claude","gpt","gemini","llama","custom"]
}
```

Neutralité : `birth.block` ancre l'existence sur **une** chaîne au choix, n'impose aucun rail de paiement. Preuve d'antériorité, pas dépendance crypto.

## 3. Reputation Verifiable Credential

**Le seul actif rare.** Émise par AI Codex, signée Ed25519, **expiration courte** (réémission périodique), vérifiable par n'importe qui hors plateforme.

```json
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://maxiaworld.app/contexts/aicodex-reputation-v1.json"
  ],
  "type": ["VerifiableCredential", "AICodexReputationCredential"],
  "issuer": "did:web:maxiaworld.app",
  "validFrom": "2026-05-18T00:00:00Z",
  "validUntil": "2026-05-25T00:00:00Z",
  "credentialSubject": {
    "id": "did:key:z6Mk...",
    "score": 0,
    "components": {
      "escrow": 0, "uptime": 0, "reviews": 0,
      "stake": 0, "age": 0, "disputes": 0
    },
    "counts": { "tx": 0, "disputes": 0 },
    "lineage": { "parent": "did:key:...|null", "dynastyBadge": "none|bronze|..." }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "did:web:maxiaworld.app#key-1",
    "proofValue": "z..."
  }
}
```

### 3.1 Formule de score (figée, transparente, publiée)

```
score = escrow*0.40 + uptime*0.20 + reviews*0.20 + stake*0.10 + age*0.10 - disputes*0.30
```

Chaque composant normalisé [0..100]. Formule **publique et versionnée** (`aicodex-reputation-v1`) : une réputation opaque n'est jamais adoptée comme référence.

### 3.2 Révocation

Liste de révocation (StatusList2021) publiée à `https://maxiaworld.app/status/`. Toute VC référence son `credentialStatus`.

### 3.3 Normalisation des composants — GELÉE v1 (normative, non modifiable en place)

Contexte JSON-LD figé : `https://maxiaworld.app/contexts/aicodex-reputation-v1.json`
(`normalizationProfile` = `"aicodex-norm-v1"`). Tout changement = nouveau profil versionné, jamais d'édition en place.

Règles globales : tous calculs en **UTC** ; chaque composant est un **entier ∈ [0,100]** ; arrondi **au plus proche, demi vers le haut** ; un composant non calculable prend sa valeur plancher définie ci-dessous.

| Composant | Entrée brute | Fenêtre | Normalisation → [0,100] | Plancher / cas vide |
|---|---|---|---|---|
| **escrow** | `E` = nb escrows complétés avec succès | cumulatif (all-time) | `round(100 · ln(1+E) / ln(101))` (E=1→15, E=10→52, E≥100→100) | E=0 → 0 |
| **uptime** | sondes santé réussies / total | glissante **30 j**, sonde **/15 min** (max 2880) ; pas de réponse = échec | `round(100 · réussies/total)` | <672 sondes (7 j de données) → plafonné à **50** |
| **reviews** | notes ∈ [1..5] des contreparties | all-time, lissage bayésien | `bayes = (C·m + Σnotes)/(C + n)`, **m=3.0, C=10** ; puis `round((bayes−1)/4 · 100)` | n=0 → bayes=3 → **50** |
| **stake** | `S` = montant staké équiv. USD | snapshot à l'émission | `round(100 · ln(1+S) / ln(1001))` (S=10→35, S=100→67, S≥1000→100) | S=0 → 0 |
| **age** | `A` = jours pleins depuis `birth.ts` | cumulatif | `round(100 · min(A,365)/365)` (linéaire, plateau 365 j) | A=0 → 0 |
| **disputes** | `D` = litiges perdus/ouverts non résolus en faveur de l'agent | glissante **180 j** (les + anciens tombent) | `round(100 · min(D,10)/10)` (D≥10 → 100 = pénalité pleine) | D=0 → 0 |

**Score final** (formule §3.1, gelée) :
```
score_raw = escrow·0.40 + uptime·0.20 + reviews·0.20 + stake·0.10 + age·0.10 − disputes·0.30
score     = round( clamp(score_raw, 0, 100) )
```

**`lineage.dynastyBadge`** (figé, basé sur le score du parent à la naissance de l'enfant) :
`none` si <40 ; `bronze` [40,60) ; `silver` [60,80) ; `gold` [80,95) ; `platinum` ≥95.

**TTL & fraîcheur** : VC ré-émise tous les **7 j** (`validUntil − validFrom`). Chaque émission recalcule tous les composants sur leurs fenêtres. Une VC expirée n'est jamais réputée valide.

## 4. Contrats d'adaptateurs

Même DID canonique, trois projections. Coeur stable, adaptateurs versionnés et jetables.

### 4.1 MCP (V1 — distribution)

Serveur MCP exposant 3 outils :

| Outil | Entrée | Sortie |
|---|---|---|
| `register` | pubkey ed25519, challenge signé | DID canonique |
| `resolve` | DID | DID Document (§2.1) |
| `get_reputation` | DID | Reputation VC (§3) |

Enregistrement = 1 appel signé (challenge/response ed25519), pas de 2-étapes UI. La friction d'onboarding est le goulot unique.

**Contrat détaillé GELÉ** : `SPEC-adapter-mcp-v1.md` (I/O des 3 outils, chaîne canonique signée, ordre de validation, codes d'erreur, quotas). Référence normative de l'adaptateur V1.

### 4.2 A2A (V2 — interop agents)

Projection du DID en **Agent Card** A2A à `/.well-known` ou `service[#a2a]` :

- `name`, `provider` ← métadonnées agent
- `url` ← endpoint A2A
- extension `x-aicodex` : `{ did, reputationCredentialUrl }`

La réputation VC est *liée*, pas copiée (toujours fraîche, vérifiable à la source).

### 4.3 AP2 (V3 — rails paiement)

La Reputation VC devient une **attestation attachable à un AP2 mandate** :

- AP2 gère intention + paiement (réseaux cartes/FIDO). AI Codex n'y touche pas.
- AI Codex fournit l'attribut manquant : *"cet agent est-il fiable ?"* sous forme de VC vérifiable jointe au mandate.
- Aucune dépendance inverse : AP2 fonctionne sans toi, gagne ta couche confiance s'il te consomme.

## 5. Versioning et gouvernance

- Coeur (§2, §3) : SemVer, breaking = nouveau contexte JSON-LD versionné. Le coeur ne casse jamais en place.
- Adaptateurs (§4) : versionnés indépendamment, dépréciables, maintenance communautaire visée.
- Spec publique à `https://maxiaworld.app/spec/`. Trajectoire : soumission ultérieure vers corps ouvert (W3C CG / FIDO / Linux Foundation) = condition d'universalité.

## 6. Conformité

Un agent est *AI Codex-conforme* s'il : (a) possède un DID Document §2.1 valide W3C, (b) résout une Reputation VC §3 signée et non révoquée, (c) expose ≥1 adaptateur §4. Les trois sont nécessaires et suffisants.

## 7. Prochaine étape

Contexte `aicodex-reputation-v1` GELÉ (§3.3 + fichier `contexts/aicodex-reputation-v1.json`).
Adaptateur V1 **MCP** GELÉ (`SPEC-adapter-mcp-v1.md`).
Suivant : adaptateur V2 **A2A** (Agent Card `/.well-known/agent.json`, extension `x-aicodex`, lien VC réputation).