Air Desktop — Index des documents de conception

Document de référence — Version 1.4 (2026-07-10, passe post-M5 : ADRs jusqu’à 087, sceaux couche-0-v1.12 / couche-1-v1.9, jalon std-sur-Air atteint)

Ce document recense l’ensemble des documents de conception du projet Air Desktop, élaborés pendant les sessions préparatoires. Il sert de :

• Index navigationnel pour retrouver rapidement un document.
• Checklist de complétude pour vérifier que tout est en place.
• Carte des travaux à reprendre pour les sessions futures.

Identité du projet

• Nom du projet : Air
• Identité publique : Air Desktop
• Domaine : air-desktop.org
• Organisation GitHub : air-desktop-project
• Repo principal : github.com/air-desktop-project/air
• Préfixe technique des crates : air-
• Licence : Mozilla Public License 2.0

Convention de nommage des fichiers

• ADRs (Architecture Decision Records) : ADR-NNN-titre-court-LL.md (préfixe ADR-, numéro à 3 chiffres, titre en kebab-case, suffixe de langue -fr ou -en).
• Documents fondateurs (vision, charte, principes d’ingénierie) : nom thématique + suffixe de langue (vision-fr.md, charter-en.md, etc.).
• Specs et documents internes : nom thématique en kebab-case, langue implicite par contenu et contexte.

Structure de la documentation

air/
├── README.md                                # Vue d'ensemble publique du projet
├── README-fr.md                             # Vue d'ensemble publique du projet (FR)
├── LICENSE                                  # MPL 2.0 (à copier)
├── CHANGELOG.md                             # À démarrer
├── CONTRIBUTING.md                          # À rédiger (TODO)
├── CODE_OF_CONDUCT.md                       # Contributor Covenant 2.1 (TODO)
├── SECURITY.md                              # À rédiger (TODO)
├── Cargo.toml                               # Workspace Rust privé (couche 0)
├── Cargo.lock                               # Lockfile committé
├── rust-toolchain.toml                      # Toolchain pinée
├── crates/
│   ├── air-sys-types/                       # Types fondamentaux de la couche 0
│   └── air-sys-syscall/                     # Wrappers Rust des syscalls Linux
└── docs/
    ├── INDEX.md                             # Ce document
    ├── EXCEPTIONS.md                        # Exceptions explicites au principe dépendances (ADR-024)
    ├── COVERAGE-EXCEPTIONS.md               # Branches/lignes couche 0 non couvertes (raison légitime)
    ├── UNSUPPORTED.md                       # Syscalls/opcodes legacy non wrappés + remplaçants (io_uring 3b)
    │
    ├── vision/
    │   ├── vision-fr.md                     # Vision du projet (FR)
    │   └── vision-en.md                     # Project Vision (EN)
    │
    ├── charte/
    │   ├── charte-fr.md                     # Charte (5 principes, FR)
    │   └── charter-en.md                    # Charter (EN)
    │
    ├── principes-ingenierie/
    │   ├── principes-ingenierie-fr.md       # 9 principes (FR)
    │   └── engineering-principles-en.md     # Engineering Principles (EN)
    │
    ├── adrs/
    │   ├── registre-adrs-fr.md              # Registre / index des ADRs (v3.36)
    │   ├── ADR-001-aircom-fr.md            # 17 ADRs fondateurs + ADR-018 imagerie
    │   ├── ADR-002-modele-objet-fr.md
    │   ├── ADR-003-compositeur-wayland-fr.md
    │   ├── ADR-004-linux-tier-1-fr.md
    │   ├── ADR-005-systemd-fr.md
    │   ├── ADR-006-profils-fr.md
    │   ├── ADR-007-air-console-fr.md
    │   ├── ADR-008-air-tui-fr.md
    │   ├── ADR-009-framework-vues-fr.md
    │   ├── ADR-010-airapp-fr.md
    │   ├── ADR-011-phasage-fr.md
    │   ├── ADR-012-versionnement-fr.md
    │   ├── ADR-012-bis-telemetrie-fr.md
    │   ├── ADR-013-distribution-fr.md
    │   ├── ADR-014-catalogue-materiel-fr.md
    │   ├── ADR-015-licence-gouvernance-fr.md
    │   ├── ADR-016-i18n-fr.md
    │   ├── ADR-017-accessibilite-fr.md
    │   ├── ADR-018-modele-imagerie-fr.md
    │   ├── ADR-019-modele-erreurs-fr.md     # ADRs phase 0 (renumérotés +1)
    │   ├── ADR-020-strategie-signaux-fr.md
    │   ├── ADR-021-conventions-couche-0-fr.md
    │   ├── ADR-022-architecture-io-uring-fr.md
    │   ├── ADR-023-runtime-air-fr.md
    │   ├── ADR-024-workflow-dependances-fr.md
    │   ├── ADR-025-builds-reproductibles-fr.md  # OK (clôt la série de design phase 0)
    │   ├── ADR-026-contrat-air-tui-fr.md        # OK (contrat 1.0 `air-tui`)
    │   └── ADR-027-doc-polyglotte-fr.md         # OK (doc polyglotte ABI C — diff. couche 2)
    │
    ├── architecture/
    │   └── macro-architecture-fr.md         # Macro-architecture des 6 couches
    │
    ├── notes/                               # Pistes / cadrages exploratoires (NON engageants)
    │   ├── libc-compat-exploration-fr.md
    │   ├── android-vendor-interface-exploration-fr.md
    │   ├── api-reseau-strategie-fr.md       # cadrage `air-network` (couche 2)
    │   ├── audit-dlmalloc-fr.md             # distillation dlmalloc → allocateur global Air (couche 1)
    │   └── audit-s2n-tls-fr.md              # relevé chiffré s2n-tls → contingence air-tls maison (couche 2)
    │
    ├── specs/
    │   ├── layer-0/
    │   │   ├── introduction-fr.md           # Intro développeur couche 0 (encart dev C/C++)
    │   │   ├── air-sys-types.md             # Partiel, avec TODO
    │   │   ├── family-process.md
    │   │   ├── family-fs.md
    │   │   ├── family-mem.md
    │   │   ├── family-signal.md
    │   │   ├── family-time.md
    │   │   ├── family-net.md
    │   │   ├── family-ipc.md
    │   │   ├── family-security.md
    │   │   ├── family-system.md
    │   │   ├── family-device.md             # uevent/evdev (sysfs → fs)
    │   │   ├── family-ebpf.md               # bpf() exhaustif + perf_event_open
    │   │   ├── family-fs-inotify.md         # extension inotify (prérequis AirFileSystemWatcher)
    │   │   ├── family-mem-mmap-region.md    # MmapRegion partageable refcounté (implémenté #31)
    │   │   ├── family-process-privsep.md    # setgroups/setres*id (prérequis drop_privileges)
    │   │   ├── io-uring-overview.md         # Synthèse, avec TODO
    │   │   ├── io-uring-1-core.md           # TODO
    │   │   ├── io-uring-2a-filesystem.md    # TODO
    │   │   ├── io-uring-2b-network.md       # TODO
    │   │   ├── io-uring-2c-async.md         # TODO
    │   │   ├── io-uring-3a-registration.md  # TODO
    │   │   ├── io-uring-3b-linked.md        # TODO
    │   │   ├── io-uring-3c-multishot.md     # TODO
    │   │   ├── io-uring-3d-shared.md        # TODO
    │   │   └── io-uring-4-raw.md            # TODO
    │   ├── layer-1/
    │   │   ├── air-base-lib-core.md         # erreurs, chaînes/chemins, temps
    │   │   ├── air-base-lib-services.md     # logging, identifiants, config
    │   │   ├── air-filesystem.md            # AirFileSystem + watcher
    │   │   ├── air-memory.md                # allocateurs arena/pool/slab + comptabilité
    │   │   ├── air-process.md               # processus, pidfd, drop_privileges
    │   │   ├── air-thread.md                # threads, mutex/rwlock/sémaphore, MPSC
    │   │   ├── air-socket.md                # sockets + résolution de noms enfichable
    │   │   ├── air-crypto.md                # primitives cryptographiques (RustCrypto)
    │   │   ├── air-device.md                # énumération/surveillance natives (sysfs+uevent)
    │   │   ├── air-config.md                # compilateur config + artefact Cap'n Proto (crate dédiée)
    │   │   ├── air-config-source-format.md  # grammaire du format de source air-config (design)
    │   │   └── air-config-schemas-v1.md     # schémas .capnp v1 + BNF gelée du format de source
    │   ├── layer-2/
    │   │   ├── air-object.md                # modèle d'objet C-ABI (clé de voûte couche 2)
    │   │   ├── air-com.md                    # IPC natif AirCom (sans-IO, capability=fd, pub-sub anneau shm)
    │   │   └── air-event.md                 # façade C-ABI de l'event loop async (sur air-runtime)
    │   └── layer-4/
    │       ├── air-tui-core.md              # Noyau 1.0 `Capabilities`/focus/commandes
    │       └── air-tui-runtime-api.md       # Surface d'API conceptuelle runtime
    │
    ├── setup/
    │   ├── phase-A-decisions.md
    │   ├── phase-B1-structure.md
    │   ├── phase-B2-operations.md
    │   ├── phase-C-infrastructure.md
    │   └── phase-D-community.md
    │
    ├── guides/                              # TODO
    │   ├── first-contribution.md
    │   └── getting-started/
    │
    └── maintainers/                         # TODO
        ├── release-process.md
        ├── moderation.md
        ├── onboarding-maintainers.md
        └── cve-handling.md

Inventaire des documents produits

Documents fondateurs

ADRs fondateurs (17) et ADR-018 (modèle d’imagerie)

Voir le registre des ADRs pour la liste consolidée. Tous les fichiers sont sous docs/adrs/.

ADRs phase 0

ADRs post-phase 0

Spécifications techniques de la couche 0

🔒 COUCHE 0 — SCELLÉE le 2026-06-14 (tag couche-0-v1), re-scellée couche-0-v1.1 (errno additif, PR #77), couche-0-v1.2 (extension exec/redirection execve/execveat/dup3/fchdir/chdir/exit_group, PR #100), couche-0-v1.3 (execve_prepared — exec sans alloc pour air-process, PR #104), puis couche-0-v1.4 le 2026-06-25 (faccessat honore réellement ses flags via faccessat2 SYS 439 — , couche-0-v1.5 (famille poll/ppoll — attente synchrone bornée interruptible, ADR-044, PR #129), puis couche-0-v1.6 le 2026-06-28 : la couche 0 devient std-free (#![cfg_attr(not(test), no_std)], prouvé par le compilateur, Principe 4) via types FD natifs d’Air (OwnedFd/BorrowedFd/RawFd + close(2) interne, PR #148), famille futex(2) (PR #147), std-free (ffi→alloc/core, OsString→octets, FutexMutex, PR #149) et clone3 spawn de thread (clone_thread + trampoline asm 2-arches, join CHILD_CLEARTID, PR #150) — ADR-048 + Amendement 1 ; jalons antérieurs conservés) ; puis couche-0-v1.7 (famille arch — arch_prctl set_fs/get_fs TLS x86_64, ADR-051/052) ; puis couche-0-v1.8 le 2026-07-02 (famille terminal — termios/tty complète : attributs tcgetattr/tcsetattr, contrôle-ligne tcdrain/tcflush/tcflow/tcsendbreak, winsize (TIOCGWINSZ/S), PTY (/dev/ptmx+TIOCGPTN/TIOCSPTLCK/TIOCGPTPEER), session/job-control (tc[gs]etpgrp/TIOCSCTTY/TIOCNOTTY/TIOCGSID) ; fonctions dédiées typées ADR-021 conv. 3, Option<Pid>, EINTR remonté, RAII FD ; tests sur PTY réel /dev/ptmx + cycle session en enfant setsid ; ADR-060, PRs #200–#204 ; 1 exception CHILD-EXIT) ; puis couche-0-v1.9 (signaux async, ADR-066), couche-0-v1.10 (sockaddr/sockopt libc, ADR-070/071), couche-0-v1.11 le 2026-07-09 (additifs cumulés libc/std — chroot/killpg/sigaltstack+AltStack/sendfile/fchmod/fchown/futimens/munmap_raw, ADR-085), puis couche-0-v1.12 le 2026-07-10 (raw_syscall** — escape hatch syscall générique, EXCEPTION assumée temporaire à retirer avec l’équipe Rust, ADR-087, jalon M5).** CODE complet (11 familles + io_uring 12 Temps + extensions MmapRegion/privsep/fs::inotify/ affinité CPU/exec/faccessat2), barrière complète verte sur 2 arches (x86_64 speedy, aarch64 raspi-srv-2), 100 % de couverture hors exceptions documentées (couvrable VIDE au sens strict, ADR-035 ; lignes 97,74 % / branches 82,73 % brutes), // SAFETY: sur chaque bloc unsafe, doc développeur FR + EN. Le socle syscall n’évolue plus que par RFC (ADR-015) ; les constantes Errno peuvent être complétées additivement par les besoins des contrats couche 1 landés (re-sceau vX.Y, jalons antérieurs conservés). Couche 1 — 8/8 CRATES CŒUR IMPLÉMENTÉ : air-base-lib cœur (PR #73) + air-crypto (PR #80) + air-socket (PR #86) + air-filesystem (PR #87) + air-memory (PR #88) + air-device (PR #94) + air-thread (PR #97) + air-process (PR #105). Reste pour clore la couche 1 : air-base-lib services (logging/identifiants ; air-config → crate dédiée, Cap’n Proto, ADR-040/041) et l’ABI C (libair-base.so, différée).

🔒 COUCHE 1 — SCELLÉE couche-1-v1.0 (2026-07-03, ADR-062) ; re-scellée v1.1 (ADR-065), v1.2 (ADR-066), couche-1-v1.3 (2026-07-05, ADR-067 — crate air-account) ; v1.4/v1.5 (credentials + drop_to_user, ADR-068), couche-1-v1.6 (air-handle + moteur socket, ADR-069), couche-1-v1.7 le 2026-07-09 (Managers de domaine ADR-077 + AirSignalManager, chantier B), couche-1-v1.8 le 2026-07-09 (air-process::spawn_process, socle posix_spawn, chantier B), couche-1-v1.9 le 2026-07-10 (introspection thread cible — air-runtime::process_context [auxv+bornes de pile] + AirProcessManager::resource_limit, socle de getauxval/pthread_getattr_np de la libc, ADR-086, jalon M5 ; earmark ADR-078 crypto → couche-1-v1.10). API Rust publique figée sur 17 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, air-config*, air-libm). Précédée des audits pré-sceau (#212/#213), des 4 P0 (AirFile #214, air-poll #215, termios/PTY #216, air-signal #217) et du remodel os_str env/args (#218). HORS sceau : C-ABI (air-base-capi + libc, régime air-stable) · PAL std::sys · toolchain C/C++. Évolution ensuite par descellement additif v1.x (RFC, modèle ADR-051). Toit libc — jalon M0 (fondations) posé : split code / artefact (ADR-029) — crates/air-libc-capi (rlib pur, le code : buildable pour *-linux-air) + crates/air-libc-c (cdylib host-only, l’artefact libair_c.so). M1-b — split « logique / shims C-ABI » (couverture) : la LOGIQUE mesurable vit dans des crates sœurs SANS symbole libc #[no_mangle] — crates/air-libc-fmt (moteur de format printf, couvert à 100 %, surface format-string N°1) et crates/air-libc-alloc (logique malloc/free/…, couvert à 100 %) ; les primitives mem*/str* (#![no_builtins]) dans crates/air-libc-strmem. Seul air-libc-capi porte les shims #[no_mangle] extern "C" (qui délèguent), exclu du gate de couverture (comme air-libc-strmem) car ces symboles surchargent le runtime de couverture LLVM. Régime air-stable — errno C-ABI (__errno_location + E*) + crt (__libc_start_main/air_main) câblé sur air_runtime::start::bootstrap ; registre libc-conformance.md ; harnais on-target rt/crates/airlibc-return42 (return 42). 1er additif v1.x révélé : AirRuntime::errno_location() -> *mut i32 (RFC de descellement à ratifier). Caveats de sceau résorbés post-sceau (PR #66, merge 380d389) : gates qualité gravés en cargo xtask (barrier/couvrable-vide/check-syscalls/ audit-exceptions/repro, cf. outillage-xtask.md). La reproductibilité ADR-025 est outillée (repro, 4 rlibs bit-pour-bit) ; le re-sync des fichier:ligne du registre est outillé (audit-exceptions), qui a corrigé une dérive du décompte → registre à 69 entrées production (STRUCTURAL 38, FEATURE-KERNEL 13, PRIVILEGE 10, CHILD-EXIT 8, DEFERRED-TOOLING 0). check-syscalls certifie 161 numéros conformes (2 arches, 0 écart).

Spécifications techniques de la couche 1

Spécifications techniques de la couche 2

Spécifications techniques de la couche 4

Spécifications techniques de la couche 5 (services système réseau)

Documents de setup phase 0

Point d’attention — Statut de la macro-architecture

La macro-architecture a fait l’objet d’une passe 1 de nettoyage (2026-05-20) qui a :

• Aligné la section 2 (couche 0) sur les ADRs phase 0 (ADR-019 modèle d’erreurs, ADR-020 stratégie signaux, ADR-021 conventions transverses, ADR-022 architecture io_uring) et sur le découpage acté en deux crates air-sys-types + air-sys-syscall.
• Neutralisé toutes les références prospectives ADR-018 à ADR-026 en marqueurs neutres (« ADR à produire — service [X] »). Les ADRs services système couche 5 recevront leur numéro définitif au moment de leur instruction (numéros ≥ ADR-028 ; ADR-027 est pris par la stratégie de documentation polyglotte).

Une passe 2 de complétion reste à mener plus tard, en parallèle de l’implémentation : enrichir les sections couches 1 à 5 avec les détails issus des ADRs et specs récents (notamment les conventions transverses dans le code couche 1, l’articulation détaillée AirCom/io_uring/runtime async, etc.).

Travaux à reprendre

Travaux prioritaires (à reprendre en premier)

1. CONTRIBUTING.md détaillé
   • Localisation : CONTRIBUTING.md à la racine du repo.
   • Périmètre : guide complet de contribution avec workflow Git, conventions, DCO, processus RFC.

Spec détaillée du module io_uring (9 documents)

À produire au niveau de détail des autres specs de familles :

5. docs/specs/layer-0/io-uring-1-core.md (Temps 1 : cœur API)
6. docs/specs/layer-0/io-uring-2a-filesystem.md (Temps 2a : 21 opérations FS)
7. docs/specs/layer-0/io-uring-2b-network.md (Temps 2b : 8 opérations réseau)
8. docs/specs/layer-0/io-uring-2c-async.md (Temps 2c : 9 opérations async)
9. docs/specs/layer-0/io-uring-3a-registration.md (Temps 3a : registration)
10. docs/specs/layer-0/io-uring-3b-linked.md (Temps 3b : linked)
11. docs/specs/layer-0/io-uring-3c-multishot.md (Temps 3c : multishot)
12. docs/specs/layer-0/io-uring-3d-shared.md (Temps 3d : shared)
13. docs/specs/layer-0/io-uring-4-raw.md (Temps 4 : raw)

Référence : ADR-022 + io-uring-overview.md.

Documents de conventions formels (mise en forme depuis Phases B et C)

14. STYLE_GUIDE.md à la racine (depuis Phase B1).
15. TESTING_GUIDE.md à la racine (depuis Phase B2 section 1).
16. ERROR_HANDLING.md à la racine (depuis Phase B2 section 2 + ADR-019).
17. COMMIT_CONVENTIONS.md à la racine (depuis Phase B2 section 3).
18. PR_REVIEW_GUIDE.md à la racine (depuis Phase B2 section 3).
19. RELEASE_PROCESS.md à la racine (depuis Phase C section 3).
20. INFRASTRUCTURE.md à la racine (depuis Phase C section 2).

Spec exhaustive de air-sys-types

21. Compléter docs/specs/layer-0/air-sys-types.md avec spec type par type (méthodes, invariants, tests). Probablement à produire en parallèle de l’implémentation effective de la crate.

Documents de la communauté

22. docs/guides/first-contribution.md : guide pas-à-pas du premier patch.
23. docs/guides/getting-started/ : guides de démarrage pour différents profils.
24. SECURITY.md à la racine : politique de divulgation des vulnérabilités.
25. CODE_OF_CONDUCT.md à la racine : Contributor Covenant 2.1 (texte officiel).
26. CHANGELOG.md à la racine : démarrage avec section [Unreleased].

Documents internes mainteneurs

27. docs/maintainers/release-process.md : procédure de release détaillée.
28. docs/maintainers/moderation.md : procédure de modération.
29. docs/maintainers/onboarding-maintainers.md : onboarding nouveau mainteneur.
30. docs/maintainers/cve-handling.md : gestion des CVEs.

Statistiques globales

Statistiques techniques (estimées)

Pour les conversations futures

Quand tu démarres une nouvelle session sur Air, pointe Claude vers ce document docs/INDEX.md comme premier point de référence. Claude pourra ainsi rapidement :

1. Comprendre ce qui existe déjà.
2. Comprendre ce qui reste à produire.
3. S’orienter dans la hiérarchie de documentation.

Suggestion de prompt initial :

« Bonjour, on continue le travail sur Air. Lis docs/INDEX.md pour comprendre l’état actuel du projet, puis on va travailler sur [sujet à préciser]. »

Ordre de priorité suggéré pour les travaux futurs

Court terme :

1. README final + CONTRIBUTING — pour que le repo soit présentable.

Moyen terme (avant ouverture publique) :

4. SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md.
5. Documents de conventions formels (mise en forme).
6. Configuration GitHub Actions de base.

Plus tard (en parallèle de l’implémentation) :

7. Spec détaillée io_uring (9 documents).
8. Spec exhaustive air-sys-types.
9. Documents internes mainteneurs.

Licence du document : MPL 2.0 Statut : Document de référence et checklist. Version 1.4 — passe post-M5 (2026-07-10) : inventaire ADRs porté à 087, sceaux couche-0-v1.12 / couche-1-v1.9, jalon std-sur-Air atteint.