# AI Codex — Adaptateur A2A v1 (GELÉ)

> Adaptateur V2 = interop agents. Projection du DID canonique (SPEC-identity-v0.1 §2) en Agent Card A2A. Contrat normatif, non modifiable en place : tout changement = `a2a-v2`. La réputation est **liée, jamais copiée** (toujours fraîche, vérifiable à la source).

## 1. Transport & enveloppe

- Agent Card servie en JSON statique à deux emplacements équivalents :
  - `https://maxiaworld.app/.well-known/agent.json` (découverte A2A standard, racine du domaine de l'agent).
  - `service[#a2a]` du DID Document : `https://maxiaworld.app/a2a/<did>.json` (résolution par DID).
- Lecture seule, **publique**, aucune auth. `Content-Type: application/json`. UTF-8.
- L'Agent Card ne contient **aucune VC**. Elle ne contient que des liens résolvables. Toute valeur de réputation se récupère hors de la carte (§4).
- Conformité cible : **A2A Agent Card** (champs standard) + extension privée `x-aicodex`. Le coeur reste W3C-pur (DID/VC) ; A2A est une projection jetable.

## 2. Liaison au DID canonique (figée)

L'Agent Card projette **un** DID canonique dérivé Ed25519 (SPEC-identity §2, `did:key` multicodec `0xED01` ou `did:web`). Aucune identité A2A n'existe sans DID préalablement enregistré via l'adaptateur MCP V1 (`register`). L'Agent Card est un **dérivé** du registre, jamais une source d'identité.

## 3. Agent Card (structure figée)

### 3.1 Forme

```json
{
  "name": "<nom agent>",
  "description": "<description courte>",
  "url": "https://<endpoint A2A de l'agent>",
  "version": "<version agent>",
  "provider": { "organization": "<org|null>", "url": "<url|null>" },
  "capabilities": { "streaming": false, "pushNotifications": false },
  "skills": [],
  "x-aicodex": {
    "did": "did:key:z6Mk...",
    "reputationCredentialUrl": "https://maxiaworld.app/reputation/did:key:z6Mk...",
    "spec": "https://maxiaworld.app/spec/SPEC-adapter-a2a-v1.md",
    "profile": "aicodex-norm-v1"
  }
}
```

### 3.2 Champs standard A2A

`name`, `description`, `url`, `version`, `provider`, `capabilities`, `skills` : projetés depuis les métadonnées agent (SPEC-identity §2.2) et la configuration de l'agent. Hors périmètre normatif AI Codex (gouvernés par A2A). AI Codex ne les valide pas, ne les signe pas.

### 3.3 Extension `x-aicodex` (normative, octet-stable)

Bloc obligatoire pour qu'une carte soit AI Codex-conforme. Champs figés :

| Champ | Type | Règle |
|---|---|---|
| `did` | string | DID canonique exact (SPEC-identity §2), résolvable via `resolve` MCP. Sans préfixe ni suffixe. |
| `reputationCredentialUrl` | string | URL absolue HTTPS de la Reputation VC vivante du `did`. **Lien, jamais valeur inline.** |
| `spec` | string | URL absolue de ce document (ancre de version de l'adaptateur). |
| `profile` | string | `"aicodex-norm-v1"` exact (profil de normalisation, SPEC-identity §3.3). |

Aucun autre champ dans `x-aicodex` en v1. Aucun champ `score`, `components`, ni copie de VC : interdits dans la carte (sinon non-conforme, §6). Une réputation figée dans une carte serait périmée et non vérifiable : seul le lien est autorisé.

## 4. Flux de consommation (figé)

Un consommateur A2A obtient la confiance ainsi, sans qu'AI Codex soit dans le chemin de données A2A :

1. Lire l'Agent Card (`/.well-known/agent.json` ou `service[#a2a]`).
2. Extraire `x-aicodex.did`. Le résoudre via l'adaptateur MCP `resolve` → DID Document W3C (SPEC-identity §2.1). Vérifier que le DID Document contient un `service[#a2a]` cohérent avec l'URL de la carte.
3. Récupérer la Reputation VC à `x-aicodex.reputationCredentialUrl` (équivalent au `get_reputation` MCP : VC toujours présente pour un DID connu, planchers §3.3 si pas d'activité).
4. **Vérifier la VC hors plateforme** : signature `eddsa-jcs-2022` de l'issuer `did:web:maxiaworld.app`, `credentialSubject.id == x-aicodex.did`, `validUntil` non dépassé, `credentialStatus` non révoqué (StatusList2021, SPEC-identity §3.2). AI Codex n'est pas requis pour cette vérification.

La carte ne fait jamais autorité sur la réputation. Elle ne fait qu'**indiquer où** la vérifier à la source.

## 5. Codes d'erreur (figés)

Servis en HTTP (carte = ressource statique). Corps JSON `{ "code": "...", "message": "..." }`, message générique (aucune fuite d'état interne ; détail loggé serveur).

| Code | HTTP | Sens |
|---|---|---|
| `E_CARD_NOT_FOUND` | 404 | Aucune Agent Card pour cet emplacement / ce DID |
| `E_DID_MALFORMED` | 400 | DID demandé non conforme `did:key`/`did:web` Ed25519 |
| `E_DID_NOT_FOUND` | 404 | DID inconnu du registre (pas de carte dérivable) |
| `E_CARD_NONCONFORMANT` | 422 | Carte présente mais `x-aicodex` absent/invalide (état serveur, jamais servi tel quel en prod) |
| `E_RATE_LIMITED` | 429 | Quota dépassé (§7) |
| `E_INTERNAL` | 500 | Erreur serveur, aucun détail divulgué |

Aucun autre code en v1. Pas de code divulguant la réputation par canal d'erreur (la réputation passe uniquement par la VC liée).

## 6. Conformité adaptateur

Carte A2A AI Codex-conforme si, et seulement si : (a) servie aux deux emplacements §1 avec le même contenu, (b) `x-aicodex` présent et conforme §3.3 (4 champs exacts, rien de plus), (c) `reputationCredentialUrl` est un lien résolvable vers la VC vivante, **aucune VC ni score inline**, (d) `x-aicodex.did` résout à un DID Document §2.1 dont le `service[#a2a]` est cohérent. Les quatre nécessaires et suffisants.

## 7. Quotas & tailles (figés)

- Lecture Agent Card : 120 / min / IP.
- Dépassement → `E_RATE_LIMITED` (jamais d'erreur silencieuse).
- Taille carte servie ≤ 16 KiB. `skills` ≤ 64 entrées (champ A2A standard, borné pour DoS, non interprété par AI Codex).

## 8. Neutralité

L'Agent Card n'expose aucun rail de paiement, aucune adresse crypto, aucune préférence de réseau. Elle ne porte que l'identité (DID) et le pointeur de réputation. Les rails restent hors du coeur et hors de cet adaptateur (condition de neutralité, SPEC-identity §1).

## 9. Suivant

Adaptateur V3 **AP2** : la Reputation VC liée ici devient une attestation attachable à un mandate AP2, sans dépendance inverse. Voir `SPEC-adapter-ap2-v1.md`.