ADR-030 — Périmètre de la règle des 80 % : dépendances de production vs test-only

Statut : Accepté. Companion d’ADR-024 (n’amende pas ADR-024, en précise le périmètre).

Catégorie : Méthode (gouvernance technique).

Contexte

Le Principe d’ingénierie 6 (« règle des 80 % ») et son workflow opérationnel (ADR-024) imposent : si moins de 80 % de l’API d’une crate candidate est utilisée, la dépendance est refusée et le code nécessaire est intégré (vendoré partiellement) en sous-module Air.

Cette règle a été pensée pour le code livré : ce qui entre dans l’artefact binaire d’Air, en détermine l’ABI, la reproductibilité (ADR-025) et la surface de supply-chain du produit. Elle ne répond pas explicitement au cas des outils de test qui ne sont jamais livrés.

L’implémentation du module io_uring (couche 0) en a besoin pour atteindre le standard de test couche 0 (Principe 1) :

• proptest — property-based testing (invariants du slab S1, du jeton slot+génération) ;
• loom — modèle de concurrence du protocole d’anneau acquire/release (§3.2 de io-uring-1-core.md), activé uniquement sous cfg(loom) ;
• cargo-fuzz (libfuzzer-sys + arbitrary) — fuzzing du décodage des CQE et des io_uring_params (données kernel = externes, Principe 3), dans une crate fuzz/ séparée.

Appliquer la règle des 80 % et le vendoring à ces frameworks serait absurde : ce sont des dizaines de milliers de lignes, non raisonnablement vendorables, et ils ne participent pas au binaire livré.

Décision

La règle des 80 % et l’obligation de vendoring d’ADR-024 / Principe 6 s’appliquent aux dépendances de PRODUCTION — celles déclarées en [dependencies], qui entrent dans l’artefact livré, son ABI et sa reproductibilité.

En sont EXEMPTÉES les dépendances qui ne sont jamais livrées :

1. les dépendances [dev-dependencies] (tests, benchmarks, exemples) ;
2. les dépendances activées uniquement par un cfg de test/modèle (p. ex. [target.'cfg(loom)'.dependencies]) ;
3. la (les) crate(s) fuzz/ séparée(s), hors du workspace couche 0.

Cette exemption porte uniquement sur la règle des 80 % et le vendoring.

Garde-fous maintenus (l’exemption ne les lève PAS)

Les dépendances test-only restent soumises à :

• Licences : deny.toml reste autoritaire sur l’arbre transitif complet (une dev-dep qui tire rand, bit-set, … : c’est tout l’arbre qui doit passer cargo deny check, pas seulement les crates de tête). Allowlist inchangée (MPL-2.0, Apache-2.0, MIT, BSD-3-Clause, ISC, Unicode-DFS-2016).
• Advisories : cargo audit vert sur l’arbre complet.
• Documentation : entrée par crate dans le DEPENDENCIES.md de la crate, avec le champ « % API utilisée » = N/A (test-only) et la justification du carve-out référençant le présent ADR.
• Isolation fuzz/ : la crate fuzz/ a ses propres Cargo.toml/Cargo.lock et ne touche ni la reproductibilité ni la mesure de couverture du produit. La barrière de couverture 100 % (couches 0/1) se mesure sur la lib, pas sur fuzz/ ; le fuzzing tourne sur une cadence séparée.
• cfg(loom) : loom est déclarée sous [target.'cfg(loom)'.dependencies], hors du graphe de build normal (inerte sans --cfg loom). Vérifier que cargo machete ne la signale pas à tort (l’ajouter à son ignore si besoin).

Conséquences

• Le module io_uring peut être testé au standard couche 0 (property-based, loom, fuzzing) sans violer le Principe 6.
• DEPENDENCIES.md peut référencer cette politique pour justifier proptest / loom / cargo-fuzz comme exemptés-mais-conformes.
• Toute dépendance qui migrerait vers [dependencies] (production) reperd l’exemption et redevient pleinement soumise à ADR-024.

Alternatives écartées

• Vendorer proptest/loom : impraticable (taille), et sans bénéfice (non livré).
• Une ligne dans EXCEPTIONS.md : EXCEPTIONS.md est réservé aux exceptions nommées de la règle des 80 % pour des deps de production (p. ex. icu4x, bitflags). Le cas présent est une politique de périmètre, pas une exception ponctuelle — sa place est dans la couche ADR.

Licence du document : MPL 2.0