Phase A — Décisions techniques restantes

Document de setup phase 0 — Version 1.0

Vue d’ensemble

La Phase A couvre les décisions techniques structurantes qui n’ont pas été tranchées dans les ADRs fondateurs et qui sont nécessaires avant le démarrage du code. Cette phase formalise les choix concernant :

1. Le runtime asynchrone.
2. La cryptographie.
3. L’outillage de fuzzing.
4. La gestion des erreurs en couches supérieures.
5. Le workflow de gestion des dépendances.

Deux ADRs ont été émis suite à cette phase :

• ADR-023 : Runtime asynchrone Air sur io_uring.
• ADR-024 : Workflow de gestion des dépendances.

Les autres décisions sont des conventions documentées sans ADR formel.

1. Runtime asynchrone

Décision : runtime maison construit progressivement, en parallèle de la phase 1.

Voir ADR-023 pour la justification complète et le périmètre.

Justifications résumées :

• Alignement parfait avec io_uring (la couche 0 est io_uring-native).
• Principe d’ingénierie 6 (règle des 80%) : Tokio est massif, Air en utiliserait 20-30%.
• Principe d’ingénierie 7 (verbosité au service de la clarté) : pas de magie cachée.
• Leçon de l’expérience Tokio : éviter les écueils déjà identifiés.
• Cohérence verticale du stack Air.

Phasage proposé. Le runtime maison se construit en couche 1, en parallèle du modèle d’objet C-ABI. Phase 0 du projet : couche 0 + types. Phase 1 : runtime async maison + modèle d’objet C-ABI.

Nom et structure. Le runtime s’appelle air-runtime, organisé en plusieurs sous-crates :

• air-runtime-core : scheduler, tâches, primitives async.
• air-runtime-io : intégration io_uring.
• air-runtime-time : timers basés sur timerfd.
• air-runtime-signal : gestion des signaux async via signalfd.
• air-runtime-sync : mutex async, channels, notify.
• air-runtime : façade qui réexporte les modules nécessaires.

2. Cryptographie

Décision : RustCrypto pour les primitives, avec audit explicite par crate utilisée. Différé à la phase 1 ou 2.

Justifications :

• Pur Rust, pas de dépendance C.
• Modulaire : Air n’inclut que les primitives dont il a réellement besoin.
• Audité : les crates principales (sha2, ed25519-dalek, x25519-dalek) ont des audits publics.
• Maintenu activement.

Coût de désengagement. Moyen. L’API des primitives crypto est suffisamment stable que la migration serait possible.

Décision opérationnelle. Pour la phase 0, on n’a pas besoin de crypto. Le sujet est différé à la phase 1 ou phase 2 quand on construira les premières fonctionnalités qui en ont besoin. À ce moment-là, audit explicite sous Principe 6 pour chaque crate ajoutée.

Pas d’ADR formel à ce stade ; la décision sera prise au moment où le besoin émerge.

3. Outillage de fuzzing

Décision : cargo-fuzz comme outillage principal.

Justifications :

• Standard de l’écosystème Rust.
• Bien intégré à Cargo.
• Documentation extensive.
• Communauté large.

Pas d’ADR formel. Convention par défaut de l’écosystème Rust.

D’autres outils (afl.rs, honggfuzz) peuvent être ajoutés pour des cibles spécifiques si nécessaire.

4. Gestion des erreurs en couches supérieures

Décision : thiserror comme dépendance, avec coût de désengagement faible documenté.

Justifications :

• C’est essentiellement une macro. Pas de logique runtime.
• Standard de facto pour les bibliothèques Rust.
• Principe 6 respecté (usage concentré à ~100% par site d’utilisation).
• Élimine le boilerplate.

Convention. Tout Error Air dérive thiserror::Error. Pas d’ADR formel, mais à mentionner dans les conventions de code (Phase B).

Voir aussi ADR-019 pour le modèle d’erreurs hybride à deux niveaux.

5. Workflow de gestion des dépendances

Décision : workflow explicite avec DEPENDENCIES.md par crate et EXCEPTIONS.md au workspace.

Voir ADR-024 pour la spécification complète.

Points clés :

• Format standardisé de DEPENDENCIES.md (nom, version, % API utilisée, justification, coût de désengagement, statut d’audit).
• Format de EXCEPTIONS.md pour les exceptions à la règle des 80%.
• Processus d’ajout encadré par revue de mainteneur.
• Audit régulier en fin de phase.
• Outillage CI : cargo audit, cargo deny, cargo machete, script Air maison.

Récapitulatif Phase A

Décisions techniques tranchées :

Licence du document : MPL 2.0 Statut : Document de setup phase 0.