ADR-033 — Modèle de configuration : source typée, compilation validée, artefact binaire

Statut : Accepté (2026-06-12). Décline les Principes d’ingénierie 4 (validation en amont, « parse, don’t validate »), 3 (zéro présomption sur les entrées) et 9 (budgets sur matériel modeste) en un modèle transverse de configuration système. Cohérent avec ADR-025 (builds reproductibles) et ADR-005 (systemd socle pour V1).

Catégorie : Architecture (transverse — couche 1 air-base-lib à couche 5 outils d’administration).

Contexte

Air s’adresse à deux publics qu’il refuse d’opposer : l’utilisateur qui ne veut pas savoir ce qu’il y a sous le capot et veut que « ça marche », et le développeur/technicien qui connaît sa machine et veut la régler finement. Les deux doivent être servis par le même système de configuration, sans que le premier puisse se tirer une balle dans le pied ni que le second soit bridé.

Le modèle Unix traditionnel — des fichiers texte éditables à la main sous /etc — a une vertu (lisibilité, grep, diff, versionnable) et un vice symétrique : une faute de frappe brique le système. Un grub.cfg erroné et la machine ne boote plus ; un fichier de /etc corrompu et un pan entier de la sécurité tombe, silencieusement. La validité n’est vérifiée qu’au runtime, trop tard, par le consommateur, de façon non uniforme.

À l’inverse, un magasin binaire canonique sans source lisible (le Registre Windows) échange ces vices contre d’autres : opacité, fragilité à la corruption, impossibilité de diff/versionner, point de défaillance monolithique.

Air veut le meilleur des deux : la sûreté et la rapidité d’un format de données vérifié, et la lisibilité et la maîtrise du texte — sans le piège de l’un ni de l’autre.

Décision

La configuration Air a pour source de vérité une source typée validée à l’écriture par un compilateur de configuration, qui en dérive un artefact binaire reproductible que le runtime consomme. Le texte lisible (JSON/YAML/TOML) est une projection d’import/export, jamais la forme runtime ; le binaire est un artefact de build, jamais la source de vérité.

Sept règles gravées :

1. La source typée fait foi ; le binaire est dérivé. La source (forme texte typée, ou entrée structurée d’une GUI) est canonique, versionnable, diffable. Le binaire est un artefact reproductible qu’on peut détruire et reconstruire à l’identique (même esprit qu’ADR-025). Jamais l’inverse : inverser, c’est réinventer le Registre.

2. La compilation valide en amont (Principe 4). Le compilateur vérifie schéma, types et invariants avant de produire le binaire, refuse une entrée invalide, et émet des diagnostics de qualité compilateur (ligne/colonne, message actionnable, suggestion). Le runtime ne voit jamais de configuration invalide.

3. Le compilateur est tenu à la barre couches 0/1. Il ingère de la donnée humaine = donnée hostile (Principe 3) : fuzzing obligatoire, property-testing, couverture 100 %. La confiance se déplace du « sysadmin soigneux » vers cet outil, qui devient un composant sécurité-critique.

4. Artefact binaire schema-first à évolution intégrée. Le format doit gérer la compatibilité avant/arrière par construction (numérotation de champs, optionnalité — famille Cap’n Proto / FlatBuffers / protobuf, à auditer sous la règle des 80 %, ADR-024). Il porte version de schéma + checksum : une corruption est détectée, jamais lue en silence. Lecture zéro-copie / mmap privilégiée (budget runtime, Principe 9).

5. Projections texte round-trippables. Import/export JSON/YAML/TOML pour le développeur et le technicien ; outil de diff lisible entre deux générations. Ces formes alimentent ou exportent la source, mais ne sont pas lues par le runtime.

6. Sûreté système par générations + switch atomique + rollback. Une configuration valide peut exprimer une mauvaise intention (couper le réseau, mauvais paramètre kernel) : la validité ne suffit pas. Le filet anti-brick réel est le modèle générationnel — conserver la dernière configuration compilée known-good, basculer atomiquement (air-filesystem::write_atomic), offrir un retour à la génération précédente (y compris une entrée de secours au boot pour le cas pré-userspace type bootloader).

7. Backends de compilation = le joint d’indépendance. Le compilateur émet vers une cible enfichable. Pour V1 sur systemd (ADR-005), la cible est l’ensemble unit files + drop-ins /etc générés et validés : l’humain édite la source Air, jamais l’unit file. Le jour où une brique systemd est remplacée par une brique Air native, on change le backend (émettre le binaire natif), sans toucher la source de l’utilisateur. Cf. la note de stratégie de remplacement progressif ci-dessous.

Conséquences

• AirConfig (spec air-base-lib services, aujourd’hui « parseur TOML derrière une feature ») est étendu vers ce modèle : un cœur validant unique, air-config, partagé par tous les frontends.
• Deux publics, un cœur. Frontend texte typé piloté par le schéma (autocomplétion, doc inline, erreurs précises) pour le développeur ; GUI contrainte par le schéma — l’état invalide devient inexprimable — pour l’utilisateur lambda. Même validation, mêmes générations, même rollback.
• Couches touchées : air-base-lib (couche 1, le cœur air-config), air-systemd (couche 2, backend unit files pour V1), les outils d’administration (couche 5), et les consommateurs comme air-device.
• Articulation principes/ADRs : Principe 4 (valider en amont, parse don’t validate), Principe 3 (entrée hostile → fuzzing), Principe 9 (lecture binaire économe), ADR-025 (artefact reproductible), ADR-019 (les erreurs de compilation sont des AirError riches et contextualisées).

Alternatives rejetées

• Statu quo Unix (texte /etc canonique, édité à la main). Lisible et versionnable, mais validité tardive et « typo qui brique » — le problème même qu’on résout.
• Binaire canonique sans source texte (modèle Registre). Rapide mais opaque, fragile, non diffable, non versionnable.
• Format binaire maison sans politique d’évolution. Dette de schéma garantie sur l’horizon 20 ans ; d’où l’exigence schema-first (règle 4).

Hors périmètre (à traiter ailleurs)

L’authentification/intégrité des exécutables, bibliothèques et pilotes présents sur la machine (signature, contrôle de ce qui « doit » être là, exceptions développeur) est un second pilier distinct — adjacent au package management et au confinement OS — qui fera l’objet de son propre ADR. Ce document ne couvre que la configuration.

Licence du document : MPL 2.0 Statut : Accepté. Édition directe autorisée en phase de design pré-ouverture publique ; après ouverture publique, toute évolution passe par RFC (ADR-015).