ARC/1.0 — Agent-Readable Catalog

Version de la spécification ARC/1.0 · Publiée le 2026-06-10 · Statut : Stable
Steward : Save The Brain (KaliCart) · Licence : CC BY 4.0 · Implémentation de référence : KaliCart Bridge ≥ 1.0.114 pour WooCommerce

Abstract. ARC définit comment une boutique e-commerce expose son catalogue sous forme de surface REST lisible par machine, en lecture seule, que des agents IA autonomes peuvent découvrir, en qui ils peuvent avoir confiance et qu’ils peuvent consommer sans scraping, sans authentification ni verrouillage propriétaire. Elle spécifie trois signaux de découverte, un document de découverte auto-descriptif, un contrat d’endpoints de catalogue, un objet produit normatif, un modèle de consentement explicite pour l’indexation fédérée, et l’interopérabilité avec UCP (/.well-known/ucp). ARC est neutre vis-à-vis de la plateforme ; ce document utilise des exemples WooCommerce tout du long.

1. Niveaux de conformité & terminologie

Les mots-clés must, must not, should et may doivent être interprétés comme décrit dans la RFC 2119.

Niveau	Nom	Exigences
ARC-READ	Catalogue lisible	Au moins un signal de découverte (§2), un document de découverte valide (§3), et les endpoints `search`, `products`, `product` et `categories` (§4) servant des objets produit (§5). Aucune authentification sur aucune de ces surfaces.
ARC-TRUST	Catalogue digne de confiance	ARC-READ, plus : quarantaine qualité (§5.6), drapeaux de consentement explicites (§6), métadonnées de fraîcheur, confiance honnête sur le stock (§5.4), et les règles de vérification prix/total du §5.3.
ARC-CHECKOUT	Transfert de checkout	ARC-TRUST, plus les sessions de checkout (§7). Le paiement must rester sur la boutique du marchand ; les surfaces ARC ne traitent jamais les paiements.

2. Signaux de découverte

Une boutique conforme must publier au moins un — et should les publier tous — des signaux suivants, chacun résolvant vers le document de découverte :

2.1 Lien head HTML

<link rel="kalicart-agent" type="application/json"
      href="https://shop.example.com/wp-json/kalicart/v1/discovery" />

La relation rel="kalicart-agent" dans le <head> de la boutique est le signal in-band principal. Les agents qui analysent le HTML de la boutique should vérifier le head avant de reconstruire un catalogue à partir du contenu de la page. Les implémentations may en outre afficher une ancre visible dans le body (badge) pointant vers un index lisible par humains/agents ; les tests sur le terrain montrent que les ancres de body améliorent sensiblement la découverte par les agents qui naviguent le DOM.

2.2 Chemins well-known

La boutique should servir /.well-known/agent.json, /.well-known/agent-catalog et un alias nommé selon l’implémentation (référence : /.well-known/kalicart-bridge), chacun contenant au minimum l’URL du document de découverte et la version de l’implémentation.

2.3 Surfaces de crawl

La boutique may annoncer l’URL de découverte dans robots.txt (comme entrée commentaire/allow) et exposer un sitemap orienté agents énumérant les endpoints du catalogue.

3. Le document de découverte

Un unique document JSON auto-descriptif. C’est le contrat : un agent qui l’a lu n’a besoin d’aucune documentation hors bande. Champs normatifs :

Champ	Exig.	Signification
`document_kind`	MUST	Chaîne fixe identifiant la famille de documents (référence : `kalicart_agent_discovery`).
`schema_version`	MUST	Version du schéma du document.
`plugin_version`	MUST	Version de l’implémentation (semver).
`endpoints{}`	MUST	URL absolues pour `discovery`, `search`, `products`, `product` (modèle `{id}`), `categories`, `meta`.
`authentication`	MUST	`{required:false, scheme:"none"}` pour toutes les surfaces publiques du catalogue.
`capabilities{}`	MUST	Carte booléenne honnête : `search`, `offers`, `availability`, `shipping_policy`, `coupon_hints`, `cart`, `checkout`, `payments`, `mutations`, `read_only`. Les capacités non implémentées must être `false`.
`crawler_policy{}` / `intent_flags{}`	MUST (L2)	Modèle de consentement — voir §6.
`price_format`	MUST	Déclaration de l’encodage du prix — voir §5.3.
`variation_discovery`	MUST	Déclare le contrat des variantes liste-vs-détail — voir §5.5.
`freshness`	SHOULD (L2)	Si les données sont en direct ou un instantané, et leur borne de fraîcheur.
`trust{}`	SHOULD	Listes de tâches `safe_for[]` / `not_for[]`, autorité de checkout, règle de prix des coupons.
`ucp_profile_url`	SHOULD	URL absolue de `/.well-known/ucp` — voir §8.
`merchant{}`, `return_policy`, `merchant_shipping_policy`	SHOULD	Vérités de frontière exposées comme données structurées, jamais comme conseil rédigé.

Règle de conception — vérité de frontière. Tout ce dont le marchand est l’autorité (prix, disponibilité, livraison au checkout, politique de retour) must être exposé comme donnée structurée avec une note d’autorité explicite, et must not être remplacé par des valeurs calculées ou consultatives.

4. Endpoints du catalogue

Tous les endpoints sont en GET lecture seule, non authentifiés, JSON. Base de référence : /wp-json/kalicart/v1/.

Endpoint	Contrat
`catalog/search`	Filtres : `q`, `category`, `gender`, `color`, `on_sale`, `in_stock`, `min_price`, `max_price`. Les filtres acceptés must être énumérés par `catalog/meta`.
`catalog/products`	Liste paginée. La réponse must inclure `products[]`, `total`, `page`, `per_page`, `total_pages`.
`catalog/product/{id}`	Produit unique avec `variants[]` complet (voir §5.5).
`catalog/categories`	Arborescence de catégories avec le nombre de produits par nœud. Les catégories sont la taxonomie propre du marchand ; ARC n’impose pas de taxonomie globale.
`catalog/meta`	Filtres acceptés et fourchette de prix du catalogue.

5. L’objet produit

5.1 Identité

id, sku, type (simple|variable), name, slug, url, status, categories[] (chacune avec un path complet comme "Wine > Prosecco"), tags[], barcodes[] (EAN/GTIN/UPC lorsque présents — additif, vide en leur absence).

5.2 Provenance

metadata.bridge_version (version de l’implémentation ayant émis l’objet) et updated_at/created_at must être présents.

5.3 Prix

Les prix du catalogue sont encodés en decimal_major_units (ex. 29.99 = 29,99 EUR) et l’encodage must être déclaré dans price_format. price.current est toujours le prix catalogue du marchand ; les coupons sont des économies conditionnelles au checkout et must not le remplacer. list_price porte le prix de liste barré pour l’interop UCP. Les agents must not annoncer des totaux que le checkout du marchand n’a pas calculés (règle de vérification du total).

5.4 Stock

stock.availability_status utilise les valeurs standard UCP (in_stock, out_of_stock, backorder). stock.confidence déclare honnêtement la précision : numeric_stock_quantity, availability_status_only, ou variant_dependent. Si quantity est null, l’agent must not inventer un inventaire numérique.

5.5 Variantes

variants[] est toujours un tableau, jamais null. Dans les réponses de liste et de recherche : une entrée unique pour les produits simples, un tableau vide pour les produits variables — les variantes complètes proviennent de catalog/product/{id}. Cette asymétrie must être déclarée dans variation_discovery.list_context_note. Les agents must not annoncer un prix final pour un produit variable tant qu’une variante n’a pas été sélectionnée.

5.6 Quarantaine qualité ARC-TRUST

Chaque produit porte quarantine: {in_quarantine, score, flags[]}. Le score démarre à 100 avec des déductions pour titre, description, catégorie, prix, image, SKU manquants. Les produits mis en quarantaine pour défauts structurels (titre/description/catégorie/prix) must être exclus de tout index aval construit sur le catalogue. Le marchand conserve un tableau de bord de santé privé ; la surface publique n’expose que le verdict.

5.7 Aptitude à l’achat

purchase_readiness: {status, blocking_fields[], can_add_to_cart_directly} indique à l’agent si un ajout au panier direct via checkout_url est possible ou quels attributs doivent être sélectionnés au préalable.

6. Consentement & politique de crawl ARC-TRUST

ARC sépare la lecture d’une boutique unique (toujours autorisée sur les surfaces publiques) de l’indexation fédérée (agrégation du catalogue dans un index cross-marchands). Le consentement pour cette dernière est publié par le marchand dans le document de découverte — le modèle robots.txt : le signal vit avec la donnée, et l’indexeur est tenu de le respecter.

"crawler_policy": {
  "allow_llm_training":    false,
  "allow_live_agent_reads": true,
  "allow_global_indexing":  true
},
"intent_flags": {
  "single_merchant_only":    true,
  "global_indexable":        true,
  "federated_search_source": true,
  "agent_read_surface":      true
}

Un indexeur fédéré must lire ces drapeaux au moment du sondage, must not ingurgiter un catalogue dont allow_global_indexing est false, et must s’identifier avec un User-Agent honnête. L’implémentation de référence expédie le consentement activé par défaut avec un opt-out en un clic dans l’admin marchand ; l’un ou l’autre des réglages par défaut est conforme, mais le bouton must exister et les drapeaux publiés must le refléter dans la limite de fraîcheur.

7. Sessions de checkout (optionnel) ARC-CHECKOUT

POST checkout/session crée une session panier pour un ou plusieurs produits et renvoie cart_url / checkout_url. L’humain finalise le paiement sur la boutique du marchand. Les surfaces ARC must not capturer des paiements, stocker des identifiants de paiement, ou exiger OAuth pour ce transfert. La capacité est désactivée par défaut et son état must être visible dans capabilities.checkout_sessions.

8. Interopérabilité UCP

Une implémentation conforme should servir /.well-known/ucp déclarant catalog.search et catalog.lookup, et le lier via ucp_profile_url. Les contrats availability_status, list_price et variants[] d’ARC sont alignés sur UCP afin qu’un seul catalogue serve les deux écosystèmes sans traduction.

9. Considérations de sécurité

Toutes les surfaces publiques sont en lecture seule ; capabilities.mutations must être false. Aucune clé API sur les surfaces publiques — les secrets fuient dans les contextes agents. Les sondages fédérés must appliquer des protections SSRF (pas de littéraux IP, pas de noms d’hôte internes, redirections/délais bornés) et un User-Agent identifiant. Les surfaces admin/health must exiger des vérifications de capacité de plateforme. Les implémentations must not appeler des services tiers depuis le serveur du marchand comme effet secondaire du service des lectures de catalogue.

10. Journal des modifications de la spécification

Version	Date	Notes
`ARC/1.0`	2026-06-10	Première version stable. Codifie le contrat livré par KaliCart Bridge 1.0.76 : trois signaux de découverte, document de découverte, cinq endpoints de catalogue, objet produit avec quarantaine et aptitude à l’achat, modèle de consentement opt-out pour l’indexation fédérée, sessions de checkout optionnelles, interop UCP.

Retours et rapports d’implémentation : GitHub issues.