Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-062 — Sceau couche-1-v1.0 : gel de l’API Rust de la couche 1

Statut : Accepté (2026-07-03, autorisation BDFL explicite). RFC de structure (ADR-015). Tag git couche-1-v1.0 posé sur le commit de sceau. Companion des audits pré-sceau (docs/notes/audit-face-libc-cloture-fr.md, audit-face-pal-cloture-fr.md) et de la roadmap §5.4. Applique le modèle de re-sceau de la couche 0 (ADR-051, ADR-048) et la gouvernance de versionnement (ADR-012).

Catégorie : Sceau de couche fondatrice. Gèle une API Rust source-level ; n’affecte pas la C-ABI (régime propre, voir §Hors périmètre).

Contexte

La passe de production complète de la couche 1 (roadmap §2 cœur, §4 mono-toit dont l’async §4-K, §5.3 P0) est terminée : les deux audits pré-sceau (face-libc, face-PAL) n’ont plus de manque bloquant, et les 4 chantiers P0 fondateurs (AirFile #214, air-poll #215, termios/PTY #216, air-signal #217) sont livrés. La couche 1 a deux toits à construire dessus — la libc C-ABI (ADR-046/047/053) et le PAL Rust (la std cible *-linux-air, ADR-049/052). Pour leur donner une assise stable et éviter le va-et-vient sceau/descellement subi sur la couche 0, on fige l’API Rust de la couche 1 avant de bâtir les toits.

Décision

Ce qui est SCELLÉ — l’API Rust publique des crates couche 1

On gèle en couche-1-v1.0 la surface Rust publique (types, signatures de fonctions/méthodes, traits, ré-exports) des crates :

air-base-core, air-base-lib, air-crypto, air-socket, air-filesystem, air-memory, air-alloc, air-device, air-env, air-stdio, air-terminal, air-poll, air-signal, air-thread, air-process, air-runtime (async inclus, §4-K), air-config-schema, air-config-compile, air-config, air-libm.

Après le sceau, cette surface n’évolue que par descellement additif v1.x (RFC, ADR-015) : on ajoute, on ne casse pas ; les jalons antérieurs sont conservés (précédent ADR-051). Les implémentations internes ne sont pas gelées (optimisation, refactor libres tant que l’API publique tient).

Audit de sceau-readiness (préalable, fait). Une passe dédiée a vérifié, pour chaque additif prévu, s’il remodèlerait une signature existante (rupture) ou serait purement additif. Résultat : tous additifs sauf env/args, qui ont été remodelés à leur forme finale AVANT ce sceau (types chaîne-OS AirOsStr/ AirOsString ; air_env::get rend une copie possédée race-safe ; args::get reste &'static AirOsStr) — sinon un futur set_var/os_str les aurait cassés. Les destructeurs TLS, Condvar/Once, getsockopt/setsockopt, mman fichier-adossé, stat/fstat, mkstemp, spawn ergonomique et l’instrumentation IO (ADR-063) sont confirmés purement additifs.

Primitives unsafe nommées (actées). La règle « zéro unsafe exposé » de la couche 1 a quelques exceptions irréductibles de bas niveau, nommées et documentées (# Safety + // SAFETY:) : air-runtime::spawn (spawn de thread brut, extern "C" fn) et air-env::set_environ (publication de la table d’environnement au démarrage). Elles sont dans la surface scellée, en tant que primitives runtime assumées. (La face sigaction-de-faute, elle, est hors couche 1 — ADR-064 §2.)

Ce qui n’est PAS scellé — les toits et l’interne

  • La C-ABI : air-base-capi et la future libc C-ABI vivent au-dessus de la couche 1 et ont leur propre régime de stabilité (zones air-stable/ air-internal/air-experimental, ADR-012). Sceller la couche 1 ≠ figer les signatures C.
  • Le PAL std::sys (*-linux-air, ADR-049 phase 3) : consommateur, au-dessus.
  • Le toolchain C/C++ (clang air, compiler-rt, libc++…) : au-dessus.
  • Les crates couche 0 (air-sys-types, air-sys-syscall) : déjà scellées (couche-0-v1.8), régime propre.
  • Zones test-only et experimental : évolution libre.

Manques connus → additifs v1.x (non bloquants, déjà tranchés)

Spawn ergonomique §2.B.2 (dans air-runtime), Condvar/Once, mutation d’env (set_var…), newtype os_str, destructeurs TLS, gap aarch64 crypto (cpufeatures→libc, #14), instrumentation IO debug (ADR-063), moteur regex (§4-I). Chacun se traitera en descellement additif, jamais en refonte.

(Rappel décision : la face sigaction/handler-de-faute n’est pas un additif — elle est hors couche 1 Rust par principe, ADR-064 §2 ; les fautes → action par défaut.)

Conséquences

  • Pose du tag git couche-1-v1.0 sur le commit de sceau (après autorisation).
  • Toute évolution de l’API Rust couche 1 passe désormais par un RFC de descellement additif (couche-1-v1.x), sur le modèle couche 0.
  • Les toits (libc C-ABI, PAL) peuvent démarrer sur une assise stable.
  • La stabilité ABI (10 ans, air-abi-check/air-symver, ADR-012) s’applique aux zones air-stable de la C-ABI — pas à l’API Rust en tant que telle (le gel Rust est source-level, garanti par revue + RFC).

Alternatives rejetées

  • Sceller au fil de l’eau (comme subi en couche 0). Rejeté : on transforme les descellements structurels en additifs mineurs via une passe complète d’abord.
  • Inclure la C-ABI dans le gel Rust. Rejeté : la C-ABI a son propre régime (ADR-012) ; la mélanger figerait prématurément des signatures C encore en design.
  • Différer le sceau jusqu’aux additifs v1.x. Rejeté : ils sont non bloquants et additifs par construction ; attendre retarderait les toits sans réduire le risque.

Suite

  • Autorisation BDFL → bascule Statut = Accepté, commit de sceau, tag couche-1-v1.0, note de scellement dans INDEX.md + etat-avancement.md.
  • Démarrage des toits : ABI C (§4-J), libc C-ABI et PAL std::sys ; puis regex (§4-I).